Skip to content

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

feat: migrate browser and interact APIs to Hangar (#4757)

tomsideguidee26b2d80c795
diff --git a/.github/workflows/test-server.yml b/.github/workflows/test-server.yml
index 16076f9c3..12d9fd271 100644
--- a/.github/workflows/test-server.yml
+++ b/.github/workflows/test-server.yml
@@ -599,6 +599,11 @@ jobs:
nuq-fdb-core:
name: NuQ FoundationDB core tests
runs-on: blacksmith-4vcpu-ubuntu-2404
+ services:
+ redis:
+ image: redis
+ ports:
+ - 6379:6379
env:
FDB_VERSION: 7.3.63
steps:
diff --git a/.gitignore b/.gitignore
index 3c9c83018..425e61b4a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -65,3 +65,5 @@ apps/api/src/lib/scrape-interact/*.md
# stray test runner logs
vitest.out
+
+tmp/
\ No newline at end of file
diff --git a/apps/api/requests/v2/browser.requests.http b/apps/api/requests/v2/browser.requests.http
index fe046fc92..6cc545ec5 100644
--- a/apps/api/requests/v2/browser.requests.http
+++ b/apps/api/requests/v2/browser.requests.http
@@ -15,8 +15,8 @@ Authorization: Bearer {{$dotenv TEST_API_KEY}}
content-type: application/json
{
- "ttlTotal": 600,
- "ttlWithoutActivity": 120,
+ "ttl": 600,
+ "activityTtl": 120,
"streamWebView": false
}
@@ -26,7 +26,7 @@ Authorization: Bearer {{$dotenv TEST_API_KEY}}
content-type: application/json
{
- "ttlTotal": 300,
+ "ttl": 300,
"streamWebView": true
}
@@ -58,7 +58,7 @@ content-type: application/json
{
"code": "await page.goto('https://example.com');\nconst title = await page.title();\nconsole.log(title);",
- "language": "js"
+ "language": "node"
}
### Execute Code β€” screenshot to base64
@@ -85,10 +85,16 @@ content-type: application/json
GET {{baseUrl}}/v2/interact/{{sessionId}}/replay HTTP/1.1
Authorization: Bearer {{$dotenv TEST_API_KEY}}
-### Get Session Replay HLS playlist for tab 0
+### Replay keeps pages/pageCount; Hangar's desktop recording is page "0".
+### pageUrl is empty because the stream spans tabs; timestamps describe the video.
+### Get the single HLS playlist (segments load directly from Hangar)
GET {{baseUrl}}/v2/interact/{{sessionId}}/replay/0 HTTP/1.1
Authorization: Bearer {{$dotenv TEST_API_KEY}}
+### Get Hangar lifecycle status
+GET {{baseUrl}}/v2/browser/{{sessionId}} 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}}
@@ -99,10 +105,10 @@ content-type: application/json
}
### Delete Browser Session β€” replace sessionId with actual id
+### Waits for final duration and billing; retry if cleanup exceeds the wait deadline.
DELETE {{baseUrl}}/v2/browser/{{sessionId}} HTTP/1.1
Authorization: Bearer {{$dotenv TEST_API_KEY}}
content-type: application/json
-### WebSocket β€” webview stream (use a WS client, e.g. wscat)
-# wscat -c "ws://localhost:3002/v2/browser/{{sessionId}}" -H "Authorization: Bearer YOUR_API_KEY"
+# Open liveViewUrl or interactiveLiveViewUrl returned by creation in a browser.
diff --git a/apps/api/src/__tests__/nuq-fdb/router.test.ts b/apps/api/src/__tests__/nuq-fdb/router.test.ts
index f219f4edd..d3df8a5d6 100644
--- a/apps/api/src/__tests__/nuq-fdb/router.test.ts
+++ b/apps/api/src/__tests__/nuq-fdb/router.test.ts
@@ -11,7 +11,7 @@ import {
scrapeQueue,
crawlGroup,
crawlFinishedQueue,
- mirrorExternalSlotAcquire,
+ reserveExternalSlot,
mirrorExternalSlotRelease,
} from "../../services/worker/nuq-router";
import { scrapeQueueFdb } from "../../services/worker/nuq-fdb";
@@ -308,10 +308,10 @@ describeIf("NuQ router (forced FDB mode)", () => {
test("external slot mirror consumes and releases FDB capacity", async () => {
const teamId = randomUUID();
const holder = randomUUID();
- await mirrorExternalSlotAcquire(teamId, holder, 30_000);
+ await reserveExternalSlot(teamId, holder, 30_000, 10);
expect(await scrapeQueueFdb.getTeamActiveCount(teamId)).toBe(1);
// re-acquire (heartbeat) must not double-count
- await mirrorExternalSlotAcquire(teamId, holder, 30_000);
+ await reserveExternalSlot(teamId, holder, 30_000, 10);
expect(await scrapeQueueFdb.getTeamActiveCount(teamId)).toBe(1);
await mirrorExternalSlotRelease(teamId, holder);
expect(await scrapeQueueFdb.getTeamActiveCount(teamId)).toBe(0);
diff --git a/apps/api/src/__tests__/snips/v2/browser-profiles.test.ts b/apps/api/src/__tests__/snips/v2/browser-profiles.test.ts
index adc7ed9ca..4ab61e62f 100644
--- a/apps/api/src/__tests__/snips/v2/browser-profiles.test.ts
+++ b/apps/api/src/__tests__/snips/v2/browser-profiles.test.ts
@@ -6,236 +6,8 @@ import { describeIf, TEST_API_URL, TEST_PRODUCTION } from "../lib";
import { idmux, Identity } from "./lib";
import { db } from "../../../db/connection";
import * as schema from "../../../db/schema";
-import { browserProfileStorageId } from "../../../lib/browser-profiles";
-const WEBHOOK_SECRET = config.BROWSER_SERVICE_WEBHOOK_SECRET;
-
-// The browser service reports each successful profile save to the same webhook
-// as session.ended. These tests stand in for it, against a session row shaped
-// like the one the API writes when a session is created with a profile.
-describeIf(TEST_PRODUCTION && !!WEBHOOK_SECRET)(
- "Browser profile registry (profile.saved webhook)",
- () => {
- let identity: Identity;
- const sessionIds: string[] = [];
- const profileNames: string[] = [];
-
- beforeAll(async () => {
- identity = await idmux({ name: "browser-profiles", credits: 100 });
- });
-
- afterAll(async () => {
- if (profileNames.length > 0) {
- await db
- .delete(schema.browser_profiles)
- .where(
- and(
- eq(schema.browser_profiles.team_id, identity.teamId),
- inArray(schema.browser_profiles.name, profileNames),
- ),
- );
- }
- if (sessionIds.length > 0) {
- await db
- .delete(schema.browser_sessions)
- .where(inArray(schema.browser_sessions.id, sessionIds));
- }
- });
-
- const newProfileName = () => {
- const name = `snips-${uuidv7()}`;
- profileNames.push(name);
- return name;
- };
-
- // Returns the browser-service session id the webhook addresses.
- const createSession = async (profileName: string | null) => {
- const id = uuidv7();
- const browserId = `snips-${id}`;
- await db.insert(schema.browser_sessions).values({
- id,
- team_id: identity.teamId,
- browser_id: browserId,
- workspace_id: "",
- context_id: "",
- cdp_url: "wss://example.invalid/cdp",
- cdp_path: "https://example.invalid/view",
- stream_web_view: false,
- status: "destroyed",
- ttl_total: 60,
- should_bill: false,
- profile_name: profileName,
- });
- sessionIds.push(id);
- return browserId;
- };
-
- const profileSaved = (
- browserId: string,
- profileId: string,
- savedAt: string,
- sizeBytes?: number,
- ) => ({
- eventId: uuidv7(),
- eventType: "profile.saved",
- sessionId: browserId,
- profileId,
- savedAt,
- ...(sizeBytes !== undefined ? { sizeBytes } : {}),
- attempt: 0,
- });
-
- // A null secret omits the header.
- const send = (body: object, secret: string | null = WEBHOOK_SECRET!) => {
- const req = request(TEST_API_URL).post("/v2/browser/webhook/destroyed");
- if (secret !== null) req.set("x-browser-service-secret", secret);
- return req.send(body);
- };
-
- const profileRow = async (name: string) => {
- const [row] = await db
- .select()
- .from(schema.browser_profiles)
- .where(
- and(
- eq(schema.browser_profiles.team_id, identity.teamId),
- eq(schema.browser_profiles.name, name),
- ),
- );
- return row;
- };
-
- it("records a saved profile under the session's team", async () => {
- const name = newProfileName();
- const browserId = await createSession(name);
-
- const res = await send(
- profileSaved(
- browserId,
- browserProfileStorageId(identity.teamId, name),
- "2026-09-22T10:00:00.000Z",
- 4096,
- ),
- );
- expect(res.statusCode).toBe(200);
-
- const row = await profileRow(name);
- expect(row).toBeDefined();
- expect(new Date(row!.saved_at).toISOString()).toBe(
- "2026-09-22T10:00:00.000Z",
- );
- expect(row!.size_bytes).toBe(4096);
- });
-
- it("keeps the newest save when deliveries arrive out of order", async () => {
- const name = newProfileName();
- const profileId = browserProfileStorageId(identity.teamId, name);
- const first = await createSession(name);
- const second = await createSession(name);
-
- const newer = await send(
- profileSaved(second, profileId, "2026-09-22T12:00:00.000Z", 9000),
- );
- expect(newer.statusCode).toBe(200);
- // An older save's retry lands after the newer one.
- const older = await send(
- profileSaved(first, profileId, "2026-09-22T11:00:00.000Z", 1000),
- );
- expect(older.statusCode).toBe(200);
-
- const row = await profileRow(name);
- expect(new Date(row!.saved_at).toISOString()).toBe(
- "2026-09-22T12:00:00.000Z",
- );
- expect(row!.size_bytes).toBe(9000);
- });
-
- it("keeps the last known size when a newer save reports none", async () => {
- const name = newProfileName();
- const profileId = browserProfileStorageId(identity.teamId, name);
- const first = await createSession(name);
- const second = await createSession(name);
-
- expect(
- (
- await send(
- profileSaved(first, profileId, "2026-09-22T11:00:00.000Z", 1000),
- )
- ).statusCode,
- ).toBe(200);
- expect(
- (
- await send(
- profileSaved(second, profileId, "2026-09-22T12:00:00.000Z"),
- )
- ).statusCode,
- ).toBe(200);
-
- const row = await profileRow(name);
- expect(new Date(row!.saved_at).toISOString()).toBe(
- "2026-09-22T12:00:00.000Z",
- );
- expect(row!.size_bytes).toBe(1000);
- });
-
- it("rejects a save whose profile id does not match the session", async () => {
- const name = newProfileName();
- const browserId = await createSession(name);
-
- const res = await send(
- profileSaved(
- browserId,
- browserProfileStorageId(identity.teamId, `${name}-other`),
- "2026-09-22T10:00:00.000Z",
- ),
- );
- expect(res.statusCode).toBe(409);
- expect(await profileRow(name)).toBeUndefined();
- });
-
- it("ignores saves for unknown sessions and sessions without a profile", async () => {
- const name = newProfileName();
- const profileId = browserProfileStorageId(identity.teamId, name);
-
- const unknown = await send(
- profileSaved(
- `snips-unknown-${uuidv7()}`,
- profileId,
- "2026-09-22T10:00:00.000Z",
- ),
- );
- expect(unknown.statusCode).toBe(200);
-
- const withoutProfile = await createSession(null);
- const noProfile = await send(
- profileSaved(withoutProfile, profileId, "2026-09-22T10:00:00.000Z"),
- );
- expect(noProfile.statusCode).toBe(200);
-
- expect(await profileRow(name)).toBeUndefined();
- });
-
- it("rejects malformed events and requests without the secret", async () => {
- const name = newProfileName();
- const browserId = await createSession(name);
- const event = profileSaved(
- browserId,
- browserProfileStorageId(identity.teamId, name),
- "2026-09-22T10:00:00.000Z",
- );
-
- expect((await send({ ...event, savedAt: "yesterday" })).statusCode).toBe(
- 400,
- );
- expect((await send(event, null)).statusCode).toBe(401);
- expect((await send(event, "wrong-secret")).statusCode).toBe(401);
- expect(await profileRow(name)).toBeUndefined();
- });
- },
-);
-
-// Deleting goes through the browser service, which deletes the saved state.
-describeIf(TEST_PRODUCTION && !!config.BROWSER_SERVICE_URL)(
+describeIf(TEST_PRODUCTION && !!config.HANGAR_URL)(
"DELETE /v2/browser/profiles/:name",
() => {
let identity: Identity;
@@ -306,59 +78,5 @@ describeIf(TEST_PRODUCTION && !!config.BROWSER_SERVICE_URL)(
expect((await del("x".repeat(129))).statusCode).toBe(400);
expect((await del(`snips-${uuidv7()}`, null)).statusCode).toBe(401);
});
-
- // A profile.saved for a save made before the delete can arrive after it
- // (the browser service retries); it must not bring the listing back.
- (WEBHOOK_SECRET ? it : it.skip)(
- "ignores a late save from before the delete but records a later one",
- async () => {
- const name = `snips-${uuidv7()}`;
- profileNames.push(name);
- const sessionId = uuidv7();
- const browserId = `snips-${sessionId}`;
- await db.insert(schema.browser_sessions).values({
- id: sessionId,
- team_id: identity.teamId,
- browser_id: browserId,
- workspace_id: "",
- context_id: "",
- cdp_url: "wss://example.invalid/cdp",
- cdp_path: "https://example.invalid/view",
- stream_web_view: false,
- status: "destroyed",
- ttl_total: 60,
- should_bill: false,
- profile_name: name,
- });
- const saved = (savedAt: string) =>
- request(TEST_API_URL)
- .post("/v2/browser/webhook/destroyed")
- .set("x-browser-service-secret", WEBHOOK_SECRET!)
- .send({
- eventId: uuidv7(),
- eventType: "profile.saved",
- sessionId: browserId,
- profileId: browserProfileStorageId(identity.teamId, name),
- savedAt,
- attempt: 1,
- });
-
- try {
- const before = new Date(Date.now() - 60_000).toISOString();
- expect((await del(name)).statusCode).toBe(200);
-
- expect((await saved(before)).statusCode).toBe(200);
- expect(await profileExists(name)).toBe(false);
-
- const after = new Date(Date.now() + 60_000).toISOString();
- expect((await saved(after)).statusCode).toBe(200);
- expect(await profileExists(name)).toBe(true);
- } finally {
- await db
- .delete(schema.browser_sessions)
- .where(eq(schema.browser_sessions.id, sessionId));
- }
- },
- );
},
);
diff --git a/apps/api/src/__tests__/snips/v2/browser-replay.test.ts b/apps/api/src/__tests__/snips/v2/browser-replay.test.ts
index 61be415d1..3733055fc 100644
--- a/apps/api/src/__tests__/snips/v2/browser-replay.test.ts
+++ b/apps/api/src/__tests__/snips/v2/browser-replay.test.ts
@@ -1,11 +1,11 @@
import crypto from "crypto";
+import request from "supertest";
import { config } from "../../../config";
import {
ALLOW_TEST_SUITE_WEBSITE,
- HAS_FIRE_ENGINE,
- TEST_PRODUCTION,
TEST_SELF_HOST,
TEST_SUITE_WEBSITE,
+ TEST_API_URL,
itIf,
} from "../lib";
import {
@@ -39,9 +39,7 @@ describe("Interact session replay", () => {
}, 10000 + scrapeTimeout);
const canRunReplayHappyPath =
- ALLOW_TEST_SUITE_WEBSITE &&
- !!config.BROWSER_SERVICE_URL &&
- (TEST_PRODUCTION || HAS_FIRE_ENGINE);
+ !TEST_SELF_HOST && ALLOW_TEST_SUITE_WEBSITE && !!config.HANGAR_URL;
itIf(canRunReplayHappyPath)(
"records a session and serves replay metadata + HLS playlist after destroy",
@@ -56,6 +54,20 @@ describe("Interact session replay", () => {
expect(createResponse.statusCode).toBe(200);
expect(createResponse.body.success).toBe(true);
sessionId = createResponse.body.id as string;
+ expect(createResponse.body.playlistUrl).toBeUndefined();
+
+ expect(createResponse.body.cdpUrl).toMatch(/^wss?:\/\//);
+ const readonlyView = new URL(createResponse.body.liveViewUrl);
+ const interactiveView = new URL(
+ createResponse.body.interactiveLiveViewUrl,
+ );
+ expect(readonlyView.pathname).toBe("/live");
+ expect(interactiveView.origin + interactiveView.pathname).toBe(
+ readonlyView.origin + readonlyView.pathname,
+ );
+ expect(readonlyView.hash).not.toBe("");
+ expect(interactiveView.hash).not.toBe("");
+ expect(interactiveView.hash).not.toBe(readonlyView.hash);
// Generate on-screen activity so the screencast has frames to record.
const executeResponse = await browserExecuteRaw(
@@ -77,7 +89,10 @@ describe("Interact session replay", () => {
await sleep(15_000);
} finally {
if (sessionId) {
- await browserDeleteRaw(sessionId, identity);
+ const deleted = await browserDeleteRaw(sessionId, identity);
+ expect(deleted.statusCode).toBe(200);
+ expect(deleted.body.sessionDurationMs).toEqual(expect.any(Number));
+ expect(deleted.body.creditsBilled).toEqual(expect.any(Number));
}
}
@@ -90,37 +105,49 @@ describe("Interact session replay", () => {
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}`,
- );
- // pageUrl is the recorded page URL β€” should reflect where we navigated.
- expect(typeof page.pageUrl).toBe("string");
- expect(page.pageUrl).toContain(TEST_SUITE_WEBSITE);
- expect(page.endTimeMs).toBeGreaterThan(page.startTimeMs);
-
- const playlistResponse = await browserReplayPageRaw(
+ expect(replayResponse.body.pageCount).toBe(1);
+ expect(replayResponse.body.pages).toEqual([
+ {
+ pageId: "0",
+ url: `/v2/interact/${sessionId}/replay/0`,
+ pageUrl: "",
+ startTimeMs: 0,
+ endTimeMs: expect.any(Number),
+ },
+ ]);
+ expect(replayResponse.body.pages[0].endTimeMs).toBeGreaterThan(0);
+ const legacyPlaylist = await browserReplayPageRaw(
sessionId!,
- page.pageId,
+ "0",
identity,
);
- expect(playlistResponse.statusCode).toBe(200);
- expect(playlistResponse.headers["content-type"]).toContain(
+ expect(legacyPlaylist.statusCode).toBe(200);
+ expect(legacyPlaylist.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://");
+ expect(legacyPlaylist.text).toContain("#EXTM3U");
+ const segmentUrl = legacyPlaylist.text
+ .split(/\r?\n/)
+ .find((line: string) => line && !line.startsWith("#"));
+ if (!segmentUrl) throw new Error("Recording has no video segments");
+ expect(replayResponse.body.playlistUrl).toBeUndefined();
+ expect((await fetch(segmentUrl)).status).toBe(200);
+ expect(
+ (await browserReplayPageRaw(sessionId!, "1", identity)).statusCode,
+ ).toBe(404);
+ expect(
+ (await browserReplayPageRaw(sessionId!, "invalid", identity))
+ .statusCode,
+ ).toBe(400);
+ const browserAlias = await request(TEST_API_URL)
+ .get(`/v2/browser/${sessionId}/replay/0`)
+ .set("Authorization", `Bearer ${identity.apiKey}`);
+ expect(browserAlias.statusCode).toBe(200);
},
scrapeTimeout + 60_000,
);
- itIf(!TEST_SELF_HOST)(
+ itIf(!TEST_SELF_HOST && !!config.HANGAR_URL)(
"returns 404 when the session does not exist",
async () => {
const response = await browserReplayRaw(crypto.randomUUID(), identity);
@@ -131,21 +158,6 @@ describe("Interact session replay", () => {
},
);
- 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 () => {
@@ -166,6 +178,10 @@ describe("Interact session replay", () => {
expect(response.statusCode).toBe(403);
expect(response.body.success).toBe(false);
expect(response.body.error).toBe("Forbidden.");
+ expect(
+ (await browserReplayPageRaw(sessionId, "0", otherIdentity))
+ .statusCode,
+ ).toBe(403);
} finally {
if (sessionId) {
await browserDeleteRaw(sessionId, identity);
@@ -174,4 +190,121 @@ describe("Interact session replay", () => {
},
scrapeTimeout,
);
+ itIf(canRunReplayHappyPath)(
+ "keeps viewer fields as strings when disabled and reports no replay",
+ async () => {
+ let sessionId: string | undefined;
+ try {
+ const created = await browserCreateRaw(
+ {
+ ttl: 120,
+ activityTtl: 120,
+ streamWebView: false,
+ recordSession: false,
+ },
+ identity,
+ );
+ expect(created.statusCode).toBe(200);
+ sessionId = created.body.id;
+ expect(created.body.cdpUrl).toMatch(/^wss?:\/\//);
+ expect(created.body.liveViewUrl).toBe("");
+ expect(created.body.interactiveLiveViewUrl).toBe("");
+ expect(created.body.playlistUrl).toBeUndefined();
+ expect((await browserReplayRaw(sessionId!, identity)).statusCode).toBe(
+ 404,
+ );
+ expect(
+ (await browserReplayPageRaw(sessionId!, "0", identity)).statusCode,
+ ).toBe(404);
+ } finally {
+ if (sessionId) await browserDeleteRaw(sessionId, identity);
+ }
+ },
+ scrapeTimeout,
+ );
+
+ itIf(!TEST_SELF_HOST && !!config.HANGAR_URL)(
+ "persists profiles, excludes concurrent writers, and discards reader changes",
+ async () => {
+ const profile = {
+ name: `snips-${crypto.randomUUID()}`,
+ saveChanges: true,
+ };
+ const active = new Set<string>();
+ const create = async (saveChanges: boolean) => {
+ const response = await browserCreateRaw(
+ {
+ ttl: 300,
+ activityTtl: 300,
+ recordSession: false,
+ streamWebView: false,
+ profile: { ...profile, saveChanges },
+ },
+ identity,
+ );
+ expect(response.statusCode).toBe(200);
+ active.add(response.body.id);
+ return response.body.id as string;
+ };
+ const stop = async (id: string) => {
+ expect((await browserDeleteRaw(id, identity)).statusCode).toBe(200);
+ for (let attempt = 0; attempt < 90; attempt++) {
+ const response = await request(TEST_API_URL)
+ .get(`/v2/browser/${id}`)
+ .set("Authorization", `Bearer ${identity.apiKey}`);
+ expect(response.statusCode).toBe(200);
+ if (response.body.status === "stopped") {
+ expect(response.body.error).toBeUndefined();
+ active.delete(id);
+ return;
+ }
+ await sleep(1000);
+ }
+ throw new Error("Hangar did not stop the profile session");
+ };
+ try {
+ const writer = await create(true);
+ const conflict = await browserCreateRaw(
+ { profile, recordSession: false },
+ identity,
+ );
+ expect(conflict.statusCode).toBe(409);
+ const readerDuringWrite = await create(false);
+ await stop(readerDuringWrite);
+ const written = await browserExecuteRaw(
+ writer,
+ {
+ language: "node",
+ code: `await context.addCookies([{name:'hangar-profile', value:'saved', domain:'example.com', path:'/', expires:Math.floor(Date.now()/1000)+3600}]);`,
+ },
+ identity,
+ );
+ expect(written.body.exitCode).toBe(0);
+ await stop(writer);
+ const reader = await create(false);
+ const read = await browserExecuteRaw(
+ reader,
+ {
+ code: `console.log((await context.cookies()).find(c => c.name === 'hangar-profile')?.value); await context.clearCookies();`,
+ },
+ identity,
+ );
+ expect(read.body.stdout).toContain("saved");
+ await stop(reader);
+ const next = await create(false);
+ const unchanged = await browserExecuteRaw(
+ next,
+ {
+ code: `console.log((await context.cookies()).find(c => c.name === 'hangar-profile')?.value);`,
+ },
+ identity,
+ );
+ expect(unchanged.body.stdout).toContain("saved");
+ await stop(next);
+ } finally {
+ for (const id of active) await browserDeleteRaw(id, identity);
+ }
+ },
+ scrapeTimeout + 300_000,
+ );
});
diff --git a/apps/api/src/__tests__/snips/v2/keyless.test.ts b/apps/api/src/__tests__/snips/v2/keyless.test.ts
index b92fa8f3d..6bf149b7d 100644
--- a/apps/api/src/__tests__/snips/v2/keyless.test.ts
+++ b/apps/api/src/__tests__/snips/v2/keyless.test.ts
@@ -655,7 +655,7 @@ describeIf(KEYLESS_ENABLED)("Keyless free tier", () => {
scrapeTimeout,
);
- itIf(!!config.BROWSER_SERVICE_URL)(
+ itIf(!!config.HANGAR_URL)(
"rejects projected keyless interact session creation before browser work (429)",
async () => {
const scrapeResponse = await request(TEST_API_URL)
diff --git a/apps/api/src/__tests__/snips/v2/lib.ts b/apps/api/src/__tests__/snips/v2/lib.ts
index cba7dfef7..fec7ad9b2 100644
--- a/apps/api/src/__tests__/snips/v2/lib.ts
+++ b/apps/api/src/__tests__/snips/v2/lib.ts
@@ -349,6 +349,8 @@ export async function browserCreateRaw(
ttl?: number;
activityTtl?: number;
recordSession?: boolean;
+ streamWebView?: boolean;
+ profile?: { name: string; saveChanges?: boolean };
},
identity: Identity,
) {
@@ -396,10 +398,7 @@ export async function browserReplayPageRaw(
) {
return await request(TEST_API_URL)
.get(
- "/v2/interact/" +
- encodeURIComponent(sessionId) +
- "/replay/" +
- encodeURIComponent(pageId),
+ `/v2/interact/${encodeURIComponent(sessionId)}/replay/${encodeURIComponent(pageId)}`,
)
.set("Authorization", `Bearer ${identity.apiKey}`)
.send();
diff --git a/apps/api/src/__tests__/snips/v2/scrape-browser.test.ts b/apps/api/src/__tests__/snips/v2/scrape-browser.test.ts
index a51c3c3ae..47ef358e0 100644
--- a/apps/api/src/__tests__/snips/v2/scrape-browser.test.ts
+++ b/apps/api/src/__tests__/snips/v2/scrape-browser.test.ts
@@ -35,8 +35,9 @@ describe("Scrape browser interact replay", () => {
}, 10000 + scrapeTimeout);
const canRunReplayHappyPath =
+ !TEST_SELF_HOST &&
ALLOW_TEST_SUITE_WEBSITE &&
- !!config.BROWSER_SERVICE_URL &&
+ !!config.HANGAR_URL &&
(TEST_PRODUCTION || HAS_FIRE_ENGINE);
itIf(canRunReplayHappyPath)(
@@ -73,7 +74,7 @@ describe("Scrape browser interact replay", () => {
language: "node",
timeout: 60,
code: `
- const replayMarker = await page.evaluate(() => window.__firecrawlReplayMarker ?? null);
+ const replayMarker = await page.evaluate(() => window.__firecrawlReplayMarker ?? null, undefined, undefined, false);
console.log(replayMarker ?? "missing-marker");
`,
},
@@ -83,8 +84,18 @@ describe("Scrape browser interact replay", () => {
expect(executeResponse.statusCode).toBe(200);
expect(executeResponse.body.success).toBe(true);
expect(executeResponse.body.stdout).toContain(marker);
- expect(typeof executeResponse.body.cdpUrl).toBe("string");
- expect(executeResponse.body.cdpUrl.length).toBeGreaterThan(0);
+ expect(executeResponse.body.cdpUrl).toMatch(/^wss?:\/\//);
+ const readonlyView = new URL(executeResponse.body.liveViewUrl);
+ const interactiveView = new URL(
+ executeResponse.body.interactiveLiveViewUrl,
+ );
+ expect(readonlyView.pathname).toBe("/live");
+ expect(interactiveView.origin + interactiveView.pathname).toBe(
+ readonlyView.origin + readonlyView.pathname,
+ );
+ expect(readonlyView.hash).not.toBe("");
+ expect(interactiveView.hash).not.toBe("");
+ expect(interactiveView.hash).not.toBe(readonlyView.hash);
} finally {
if (scrapeId) {
await scrapeStopInteractiveBrowserRaw(scrapeId, identity);
diff --git a/apps/api/src/__tests__/snips/v2/types-validation.test.ts b/apps/api/src/__tests__/snips/v2/types-validation.test.ts
index 1088495f3..36dff1e21 100644
--- a/apps/api/src/__tests__/snips/v2/types-validation.test.ts
+++ b/apps/api/src/__tests__/snips/v2/types-validation.test.ts
@@ -691,8 +691,8 @@ describe("V2 Types Validation", () => {
expect(result.maxAge).toBeUndefined();
});
- // lockdown takes precedence silently at the engine layer; other options are ignored, not rejected
- it("should accept lockdown: true alongside any other options", () => {
+ // Profiles require browser state, which a cache-only request cannot supply.
+ it("should reject profile state with lockdown", () => {
const input: ScrapeRequestInput = {
url: "https://example.com",
lockdown: true,
@@ -703,8 +703,9 @@ describe("V2 Types Validation", () => {
formats: [{ type: "markdown" }, { type: "changeTracking" }],
};
- const result = scrapeRequestSchema.parse(input);
- expect(result.lockdown).toBe(true);
+ expect(() => scrapeRequestSchema.parse(input)).toThrow(
+ "Profiles require live browsing and cannot be used with lockdown.",
+ );
});
});
});
diff --git a/apps/api/src/config.ts b/apps/api/src/config.ts
index 21e032cdb..014a41cd7 100644
--- a/apps/api/src/config.ts
+++ b/apps/api/src/config.ts
@@ -600,9 +600,7 @@ const configSchema = z.object({
WIKIPEDIA_ENTERPRISE_PASSWORD: z.string().optional(),
// Browser Service
- BROWSER_SERVICE_URL: z.string().optional(),
- BROWSER_SERVICE_API_KEY: z.string().optional(),
- BROWSER_SERVICE_WEBHOOK_SECRET: z.string().optional(),
+ HANGAR_URL: z.url().optional(),
// Audio (avgrab)
AVGRAB_SERVICE_URL: z.string().optional(),
diff --git a/apps/api/src/controllers/v2/__tests__/browser-billing.test.ts b/apps/api/src/controllers/v2/__tests__/browser-billing.test.ts
index 0a54c86d6..5a14751a6 100644
--- a/apps/api/src/controllers/v2/__tests__/browser-billing.test.ts
+++ b/apps/api/src/controllers/v2/__tests__/browser-billing.test.ts
@@ -7,13 +7,10 @@ import { vi } from "vitest";
const mockGetValue = vi.fn<(key: string) => Promise<string | null>>();
const mockSetValue =
vi.fn<(key: string, value: string, ttl: number) => Promise<void>>();
-const mockDeleteKey = vi.fn<(key: string) => Promise<void>>();
-
vi.mock("../../../services/redis", () => ({
getValue: (key: string) => mockGetValue(key),
setValue: (key: string, value: string, ttl: number) =>
mockSetValue(key, value, ttl),
- deleteKey: (key: string) => mockDeleteKey(key),
}));
vi.mock("../../../lib/logger", () => ({
@@ -34,7 +31,6 @@ import {
import {
markBrowserSessionUsedPrompt,
didBrowserSessionUsePrompt,
- clearBrowserSessionPromptFlag,
} from "../../../lib/browser-sessions";
// ---------------------------------------------------------------------------
@@ -45,7 +41,6 @@ beforeEach(() => {
vi.clearAllMocks();
mockGetValue.mockResolvedValue(null);
mockSetValue.mockResolvedValue(undefined);
- mockDeleteKey.mockResolvedValue(undefined);
});
// ---------------------------------------------------------------------------
@@ -97,13 +92,13 @@ describe("calculateBrowserSessionCredits", () => {
});
describe("with interact rate (420/hr)", () => {
- it("returns minimum 2 credits for very short sessions", () => {
+ it("returns minimum 7 credits (one minute) for very short sessions", () => {
expect(calculateBrowserSessionCredits(0, INTERACT_CREDITS_PER_HOUR)).toBe(
- 2,
+ 7,
);
expect(
calculateBrowserSessionCredits(1000, INTERACT_CREDITS_PER_HOUR),
- ).toBe(2);
+ ).toBe(7);
});
it("calculates 7 credits per minute", () => {
@@ -131,10 +126,10 @@ describe("calculateBrowserSessionCredits", () => {
});
it("rounds up to next integer", () => {
- // 31s / 3600s * 420 = 3.616... β†’ ceil = 4
+ // 91s / 3600s * 420 = 10.616... β†’ ceil = 11
expect(
- calculateBrowserSessionCredits(31_000, INTERACT_CREDITS_PER_HOUR),
- ).toBe(4);
+ calculateBrowserSessionCredits(91_000, INTERACT_CREDITS_PER_HOUR),
+ ).toBe(11);
});
});
@@ -174,22 +169,22 @@ describe("calculateBrowserSessionCredits", () => {
describe("prompt usage tracking", () => {
describe("markBrowserSessionUsedPrompt", () => {
- it("sets Redis flag with 2-hour TTL", async () => {
+ it("sets Redis flag with a 2-day TTL", async () => {
await markBrowserSessionUsedPrompt("session-123");
expect(mockSetValue).toHaveBeenCalledWith(
"browser_session:used_prompt:session-123",
"1",
- 7200,
+ 2 * 86400,
);
});
- it("does not throw on Redis failure", async () => {
+ it("propagates Redis failure so the prompt is not admitted", async () => {
mockSetValue.mockRejectedValueOnce(new Error("Redis down"));
- await expect(
- markBrowserSessionUsedPrompt("session-123"),
- ).resolves.not.toThrow();
+ await expect(markBrowserSessionUsedPrompt("session-123")).rejects.toThrow(
+ "Redis down",
+ );
});
});
@@ -211,30 +206,13 @@ describe("prompt usage tracking", () => {
expect(result).toBe(false);
});
- it("returns false on Redis failure (graceful fallback to browser rate)", async () => {
+ it("propagates Redis failure so settlement retries instead of billing the cheaper rate", async () => {
mockGetValue.mockRejectedValueOnce(new Error("Redis down"));
- const result = await didBrowserSessionUsePrompt("session-123");
- expect(result).toBe(false);
- });
- });
-
- describe("clearBrowserSessionPromptFlag", () => {
- it("deletes the Redis key", async () => {
- await clearBrowserSessionPromptFlag("session-123");
-
- expect(mockDeleteKey).toHaveBeenCalledWith(
- "browser_session:used_prompt:session-123",
+ await expect(didBrowserSessionUsePrompt("session-123")).rejects.toThrow(
+ "Redis down",
);
});
-
- it("does not throw on Redis failure", async () => {
- mockDeleteKey.mockRejectedValueOnce(new Error("Redis down"));
-
- await expect(
- clearBrowserSessionPromptFlag("session-123"),
- ).resolves.not.toThrow();
- });
});
});
@@ -271,21 +249,7 @@ describe("billing rate selection", () => {
expect(credits).toBe(10);
});
- it("falls back to 120/hr when Redis is down", async () => {
- mockGetValue.mockRejectedValueOnce(new Error("Redis down"));
-
- const usedPrompt = await didBrowserSessionUsePrompt("session-123");
- const rate = usedPrompt
- ? INTERACT_CREDITS_PER_HOUR
- : BROWSER_CREDITS_PER_HOUR;
- const credits = calculateBrowserSessionCredits(5 * 60_000, rate);
-
- expect(usedPrompt).toBe(false);
- expect(rate).toBe(120);
- expect(credits).toBe(10);
- });
-
- it("full flow: mark β†’ check β†’ bill β†’ clear", async () => {
+ it("full flow: mark β†’ check β†’ bill", async () => {
await markBrowserSessionUsedPrompt("session-456");
expect(mockSetValue).toHaveBeenCalledTimes(1);
@@ -298,8 +262,5 @@ describe("billing rate selection", () => {
INTERACT_CREDITS_PER_HOUR,
);
expect(credits).toBe(21); // 3 min * 7 credits/min
-
- await clearBrowserSessionPromptFlag("session-456");
- expect(mockDeleteKey).toHaveBeenCalledTimes(1);
});
});
diff --git a/apps/api/src/controllers/v2/__tests__/browser-delete.test.ts b/apps/api/src/controllers/v2/__tests__/browser-delete.test.ts
index fbb67d84e..fec28e969 100644
--- a/apps/api/src/controllers/v2/__tests__/browser-delete.test.ts
+++ b/apps/api/src/controllers/v2/__tests__/browser-delete.test.ts
@@ -4,12 +4,20 @@ import type { RequestWithAuth } from "../types";
const mocks = vi.hoisted(() => ({
getBrowserSession: vi.fn(),
getBrowserSessionFromScrape: vi.fn(),
- claimBrowserSessionDestroyed: vi.fn(),
+ settleBrowserSessionOnce: vi.fn(),
mirrorExternalSlotRelease: vi.fn(),
billTeam: vi.fn(),
dbRows: [] as unknown[],
}));
+vi.mock("../../../config", async importOriginal => {
+ const actual = await importOriginal<typeof import("../../../config")>();
+ return {
+ ...actual,
+ config: { ...actual.config, HANGAR_URL: "http://hangar.test" },
+ };
+});
+
// Only the real getBrowserSessionFromScrape reaches this: it selects every
// row for a scrape, newest first.
vi.mock("../../../db/connection", () => {
@@ -39,28 +47,22 @@ vi.mock("../../../lib/logger", () => {
vi.mock("../../../lib/browser-sessions", () => ({
insertBrowserSession: vi.fn(),
+ completeBrowserSessionSettlement: vi.fn(async () => {}),
getBrowserSession: mocks.getBrowserSession,
getBrowserSessionFromScrape: mocks.getBrowserSessionFromScrape,
- getBrowserSessionByBrowserId: vi.fn(),
listBrowserSessions: vi.fn(),
updateBrowserSessionActivity: vi.fn(),
- updateBrowserSessionStatus: vi.fn(),
- updateBrowserSessionCreditsUsed: vi.fn(),
updateBrowserSessionScrapeId: vi.fn(),
- claimBrowserSessionDestroyed: mocks.claimBrowserSessionDestroyed,
- invalidateActiveBrowserSessionCount: vi.fn(() => Promise.resolve()),
+ settleBrowserSessionOnce: mocks.settleBrowserSessionOnce,
didBrowserSessionUsePrompt: vi.fn(),
- clearBrowserSessionPromptFlag: vi.fn(() => Promise.resolve()),
markBrowserSessionUsedPrompt: vi.fn(),
upsertBrowserProfile: vi.fn(),
deleteBrowserProfile: vi.fn(),
- recordBrowserProfileDeleted: vi.fn(),
- getBrowserProfileDeletedAt: vi.fn(),
}));
vi.mock("../../../services/worker/nuq-router", () => ({
getCombinedTeamActiveCount: vi.fn(),
- mirrorExternalSlotAcquire: vi.fn(),
+ reserveExternalSlot: vi.fn(async () => true),
mirrorExternalSlotRelease: mocks.mirrorExternalSlotRelease,
}));
@@ -93,7 +95,11 @@ function makeSession(
function makeRes() {
return {
- status: vi.fn().mockReturnThis(),
+ statusCode: 200,
+ status: vi.fn(function (this: { statusCode: number }, code: number) {
+ this.statusCode = code;
+ return this;
+ }),
json: vi.fn(),
} as unknown as Response & {
status: ReturnType<typeof vi.fn>;
@@ -125,12 +131,13 @@ describe("browser session DELETE on an already destroyed session", () => {
await browserDeleteController(req as any, res as any);
- expect(res.status).toHaveBeenCalledWith(200);
+ expect(res.status).not.toHaveBeenCalled();
+ expect(res.statusCode).toBe(200);
expect(res.json).toHaveBeenCalledWith(
expect.objectContaining({ success: true }),
);
expect(fetchMock).not.toHaveBeenCalled();
- expect(mocks.claimBrowserSessionDestroyed).not.toHaveBeenCalled();
+ expect(mocks.settleBrowserSessionOnce).not.toHaveBeenCalled();
expect(mocks.billTeam).not.toHaveBeenCalled();
});
@@ -146,16 +153,17 @@ describe("browser session DELETE on an already destroyed session", () => {
await scrapeStopInteractiveBrowserController(req as any, res as any);
- expect(res.status).toHaveBeenCalledWith(200);
+ expect(res.status).not.toHaveBeenCalled();
+ expect(res.statusCode).toBe(200);
expect(res.json).toHaveBeenCalledWith(
expect.objectContaining({ success: true }),
);
expect(fetchMock).not.toHaveBeenCalled();
- expect(mocks.claimBrowserSessionDestroyed).not.toHaveBeenCalled();
+ expect(mocks.settleBrowserSessionOnce).not.toHaveBeenCalled();
expect(mocks.billTeam).not.toHaveBeenCalled();
});
- it("still returns 502 for an active session when the browser service fails", async () => {
+ it("returns an upstream failure without settling an active session", async () => {
mocks.getBrowserSession.mockResolvedValue(makeSession("active"));
fetchMock.mockResolvedValue({
ok: false,
@@ -171,12 +179,12 @@ describe("browser session DELETE on an already destroyed session", () => {
await browserDeleteController(req as any, res as any);
expect(fetchMock).toHaveBeenCalledTimes(1);
- expect(res.status).toHaveBeenCalledWith(502);
+ expect(res.status).toHaveBeenCalledWith(500);
expect(res.json).toHaveBeenCalledWith({
success: false,
- error: "Browser session release was not confirmed.",
+ error: "Hangar request failed.",
});
- expect(mocks.claimBrowserSessionDestroyed).not.toHaveBeenCalled();
+ expect(mocks.settleBrowserSessionOnce).not.toHaveBeenCalled();
});
it("DELETE /v2/scrape/:jobId/interact releases the active row when the scrape also has a destroyed row", async () => {
@@ -196,14 +204,18 @@ describe("browser session DELETE on an already destroyed session", () => {
status: 200,
json: () =>
Promise.resolve({
- ok: true,
- sessionDurationMs: 1000,
- cleanupQueued: true,
+ id: "active-browser-id",
+ status: "stopped",
+ created_at: 100,
+ ended_at: 101,
}),
});
// Another path already billed the session, so the controller stops
// after the release and does not bill.
- mocks.claimBrowserSessionDestroyed.mockResolvedValue(false);
+ mocks.settleBrowserSessionOnce.mockResolvedValue({
+ creditsBilled: 0,
+ newlySettled: false,
+ });
mocks.mirrorExternalSlotRelease.mockResolvedValue(undefined);
const req = {
params: { jobId: "22222222-2222-2222-2222-222222222222" },
@@ -215,15 +227,21 @@ describe("browser session DELETE on an already destroyed session", () => {
expect(fetchMock).toHaveBeenCalledTimes(1);
expect(fetchMock.mock.calls[0][0]).toMatch(
- /\/browsers\/active-browser-id$/,
+ /\/browsers\/active-browser-id\/stop$/,
);
expect(fetchMock.mock.calls[0][1]).toEqual(
- expect.objectContaining({ method: "DELETE" }),
+ expect.objectContaining({ method: "POST" }),
+ );
+ expect(mocks.settleBrowserSessionOnce).toHaveBeenCalledWith(
+ activeId,
+ expect.any(Function),
);
- expect(mocks.claimBrowserSessionDestroyed).toHaveBeenCalledWith(activeId);
- expect(res.status).toHaveBeenCalledWith(200);
+ expect(res.status).not.toHaveBeenCalled();
+ expect(res.statusCode).toBe(200);
expect(res.json).toHaveBeenCalledWith(
expect.objectContaining({ success: true, sessionDurationMs: 1000 }),
);
});
});
+
+vi.mock("../../../services/redlock", () => ({ redlock: { using: vi.fn() } }));
diff --git a/apps/api/src/controllers/v2/__tests__/scrape-browser.test.ts b/apps/api/src/controllers/v2/__tests__/scrape-browser.test.ts
index 77c99f0fd..ab6830fca 100644
--- a/apps/api/src/controllers/v2/__tests__/scrape-browser.test.ts
+++ b/apps/api/src/controllers/v2/__tests__/scrape-browser.test.ts
@@ -2,6 +2,23 @@ import type { Response } from "express";
import { vi } from "vitest";
import { config } from "../../../config";
import { supabaseGetScrapeByIdDirect } from "../../../lib/supabase-jobs";
+import {
+ insertBrowserSession,
+ getBrowserSession,
+} from "../../../lib/browser-sessions";
+import {
+ createHangarBrowser,
+ executeHangarBrowser,
+ stopHangarBrowser,
+ getHangarRecording,
+} from "../../../lib/hangar";
+import {
+ browserExecuteController,
+ browserDeleteController,
+ browserReplayController,
+ browserReplayPageController,
+} from "../browser";
+import { executeCodeViaBrowserSession } from "../../../lib/scrape-interact/browser-agent";
import { scrapeInteractController } from "../scrape-browser";
import type { RequestWithAuth } from "../types";
@@ -9,38 +26,95 @@ vi.mock("uuid", () => ({
v7: vi.fn(() => "session-123"),
}));
+vi.mock("../../../config", () => ({
+ config: {
+ USE_DB_AUTHENTICATION: true,
+ HANGAR_URL: "http://localhost:9000",
+ },
+}));
+vi.mock("../../../lib/logger", () => ({
+ logger: {
+ info: vi.fn(),
+ debug: vi.fn(),
+ warn: vi.fn(),
+ error: vi.fn(),
+ child: vi.fn().mockReturnThis(),
+ },
+}));
+vi.mock("../../../services/worker/nuq-router", () => ({
+ scrapeQueue: { getJob: vi.fn(async () => null) },
+ getCombinedTeamActiveCount: vi.fn(async () => 0),
+ reserveExternalSlot: vi.fn(async () => true),
+ mirrorExternalSlotRelease: vi.fn(async () => {}),
+}));
+vi.mock("../../../lib/operational-job-access", () => ({
+ getScrapeJobAccess: vi.fn(async () => ({
+ teamId: "team-123",
+ expiresAtMs: Date.now() + 60_000,
+ })),
+}));
+vi.mock("../../../lib/job-state-store", () => ({
+ readScrapeJobState: vi.fn(async () => null),
+}));
+vi.mock("../../../lib/job-store-fallback", () => ({
+ recordJobStorePostgresFallback: vi.fn(),
+}));
+vi.mock("../../auth", () => ({
+ getACUCTeam: vi.fn(async () => ({ org_id: null })),
+}));
+vi.mock("../../../lib/request-credits-store", () => ({
+ recordRequestCredits: vi.fn(),
+}));
+vi.mock("../../../lib/keyless", () => ({
+ keylessTeamUuid: vi.fn(() => null),
+ updateKeylessBrowserCredits: vi.fn(async () => true),
+ adjustKeylessCredits: vi.fn(async () => {}),
+}));
+vi.mock("../../../lib/scrape-interact/langsmith", () => ({
+ sanitizeUrlForTrace: (url: string) => url,
+}));
+
vi.mock("../../../lib/supabase-jobs", () => ({
supabaseGetScrapeByIdDirect: vi.fn(),
}));
vi.mock("../../../lib/browser-sessions", () => ({
insertBrowserSession: vi.fn(),
+ completeBrowserSessionSettlement: vi.fn(async () => {}),
getBrowserSession: vi.fn(),
+ listUnsettledHangarSessions: vi.fn(async () => []),
updateBrowserSessionActivity: vi.fn(() => Promise.resolve()),
- updateBrowserSessionCreditsUsed: vi.fn(() => Promise.resolve()),
updateBrowserSessionScrapeId: vi.fn(() => Promise.resolve()),
- claimBrowserSessionDestroyed: vi.fn(),
- invalidateActiveBrowserSessionCount: vi.fn(() => Promise.resolve()),
+ settleBrowserSessionOnce: vi.fn(),
getBrowserSessionFromScrape: vi.fn(),
markBrowserSessionUsedPrompt: vi.fn(() => Promise.resolve()),
didBrowserSessionUsePrompt: vi.fn(),
- clearBrowserSessionPromptFlag: vi.fn(() => Promise.resolve()),
}));
vi.mock("../../../lib/concurrency-limit", () => ({
+ getEffectiveConcurrencyLimit: vi.fn(async () => 10),
getConcurrencyLimitActiveJobsCount: vi.fn(),
pushConcurrencyLimitActiveJob: vi.fn(() => Promise.resolve()),
removeConcurrencyLimitActiveJob: vi.fn(() => Promise.resolve()),
}));
-vi.mock("../../../lib/scrape-interact/browser-service-client", () => ({
- browserServiceRequest: vi.fn(),
- BrowserServiceError: class BrowserServiceError extends Error {
- status = 500;
+vi.mock("../../../lib/hangar", () => ({
+ createHangarBrowser: vi.fn(),
+ executeHangarBrowser: vi.fn(),
+ stopHangarBrowser: vi.fn(),
+ getHangarRecording: vi.fn(),
+ HangarError: class HangarError extends Error {
+ constructor(
+ public status: number,
+ message: string,
+ ) {
+ super(message);
+ }
},
}));
vi.mock("../../../lib/scrape-interact/browser-agent", () => ({
+ selectBrowserAgentTab: vi.fn(async () => {}),
executePromptViaBrowserAgent: vi.fn(),
executeCodeViaBrowserSession: vi.fn(),
}));
@@ -59,7 +133,7 @@ vi.mock("../../../services/logging/log_job", () => ({
vi.mock("../../../services/autumn/autumn.service", () => ({
autumnService: {
- checkCredits: vi.fn(),
+ checkCredits: vi.fn(async () => ({ allowed: true })),
},
}));
@@ -70,10 +144,13 @@ describe("scrapeInteractController", () => {
({
status: vi.fn().mockReturnThis(),
json: vi.fn(),
+ setHeader: vi.fn().mockReturnThis(),
+ send: vi.fn(),
}) as unknown as Response;
beforeEach(() => {
vi.clearAllMocks();
+ vi.mocked(getBrowserSession).mockResolvedValue(null);
});
afterEach(() => {
@@ -101,4 +178,165 @@ describe("scrapeInteractController", () => {
"Scrape interact requires stored scrape context and is not available when database authentication is disabled.",
});
});
+
+ it("returns the newly created session's distinct canonical viewer URLs after replay", async () => {
+ config.USE_DB_AUTHENTICATION = true;
+ const created = {
+ id: "br_session",
+ status: "running",
+ created_at: 100,
+ ended_at: null,
+ max_expires_at: 700,
+ playlist_url: "https://hangar.example/recordings/token/index.m3u8",
+ cdp_url: "wss://hangar.example/cdp?token=cdp",
+ view_url: "https://hangar.example/live#view",
+ control_url: "https://hangar.example/live#control",
+ recording: true,
+ };
+ vi.mocked(supabaseGetScrapeByIdDirect).mockResolvedValue({
+ id: "scrape-123",
+ team_id: "team-123",
+ url: "https://example.com",
+ options: {},
+ } as any);
+ const executed = {
+ stdout: "https://example.com",
+ result: "",
+ stderr: "",
+ exitCode: 0,
+ killed: false,
+ };
+ vi.mocked(createHangarBrowser).mockResolvedValue(created as any);
+ vi.mocked(executeHangarBrowser).mockResolvedValue(executed);
+ vi.mocked(insertBrowserSession).mockImplementation(async row => row as any);
+ vi.mocked(executeCodeViaBrowserSession).mockResolvedValue(executed);
+ const res = buildRes();
+ await scrapeInteractController(
+ {
+ params: { jobId: "scrape-123" },
+ body: { code: "console.log('ok')" },
+ headers: {},
+ auth: { team_id: "team-123" },
+ acuc: {},
+ } as any,
+ res,
+ );
+ expect(res.status).toHaveBeenCalledWith(200);
+ expect(res.json).toHaveBeenCalledWith(
+ expect.objectContaining({
+ success: true,
+ cdpUrl: created.cdp_url,
+ liveViewUrl: created.view_url,
+ interactiveLiveViewUrl: created.control_url,
+ }),
+ );
+ });
+
+ it.each([
+ browserExecuteController,
+ browserDeleteController,
+ browserReplayController,
+ browserReplayPageController,
+ ])(
+ "authorizes session ownership before execution, deletion, or returning recording capabilities",
+ async controller => {
+ vi.mocked(getBrowserSession).mockResolvedValue({
+ id: "session",
+ browser_id: "br_other",
+ team_id: "another-team",
+ context_id: "https://hangar.example/recordings/private/index.m3u8",
+ } as any);
+ const res = buildRes();
+ await controller(
+ {
+ params: { sessionId: "session", pageId: "0" },
+ body: { code: "console.log(1)" },
+ auth: { team_id: "team-123" },
+ } as any,
+ res,
+ );
+ expect(res.status).toHaveBeenCalledWith(403);
+ expect(executeHangarBrowser).not.toHaveBeenCalled();
+ expect(stopHangarBrowser).not.toHaveBeenCalled();
+ expect(getHangarRecording).not.toHaveBeenCalled();
+ expect(res.json).toHaveBeenCalledWith({
+ success: false,
+ error: "Forbidden.",
+ });
+ },
+ );
+
+ it("keeps the replay envelope with one desktop stream after the session stops", async () => {
+ const url = "https://hangar.example/recordings/token/index.m3u8";
+ vi.mocked(getBrowserSession).mockResolvedValue({
+ id: "session",
+ team_id: "team-123",
+ status: "destroyed",
+ context_id: url,
+ } as any);
+ const res = buildRes();
+ vi.mocked(getHangarRecording).mockResolvedValue({
+ playlist: "#EXTM3U\n#EXTINF:5,\nhttps://hangar.example/segment.ts\n",
+ durationMs: 5000,
+ });
+ await browserReplayController(
+ {
+ params: { sessionId: "session" },
+ auth: { team_id: "team-123" },
+ } as any,
+ res,
+ );
+ expect(res.json).toHaveBeenCalledWith({
+ success: true,
+ pages: [
+ {
+ pageId: "0",
+ url: "/v2/interact/session/replay/0",
+ pageUrl: "",
+ startTimeMs: 0,
+ endTimeMs: 5000,
+ },
+ ],
+ pageCount: 1,
+ });
+ const pageRes = buildRes();
+ await browserReplayPageController(
+ {
+ params: { sessionId: "session", pageId: "0" },
+ auth: { team_id: "team-123" },
+ } as any,
+ pageRes,
+ );
+ expect(pageRes.status).toHaveBeenCalledWith(200);
+ expect(pageRes.setHeader).toHaveBeenCalledWith(
+ "Content-Type",
+ "application/vnd.apple.mpegurl",
+ );
+ expect(pageRes.send).toHaveBeenCalledWith(
+ expect.stringContaining("#EXTM3U"),
+ );
+ });
+
+ it.each([
+ ["invalid", 400],
+ ["1", 404],
+ ])("rejects unavailable replay page %s", async (pageId, status) => {
+ vi.mocked(getBrowserSession).mockResolvedValue({
+ id: "session",
+ team_id: "team-123",
+ context_id: "https://hangar.example/playlist",
+ } as any);
+ const res = buildRes();
+ await browserReplayPageController(
+ {
+ params: { sessionId: "session", pageId },
+ auth: { team_id: "team-123" },
+ } as any,
+ res,
+ );
+ expect(res.status).toHaveBeenCalledWith(status);
+ expect(getHangarRecording).not.toHaveBeenCalled();
+ });
});
+
+vi.mock("../../../services/redlock", () => ({ redlock: { using: vi.fn() } }));
diff --git a/apps/api/src/controllers/v2/browser-replay.ts b/apps/api/src/controllers/v2/browser-replay.ts
deleted file mode 100644
index 59ab42118..000000000
--- a/apps/api/src/controllers/v2/browser-replay.ts
+++ /dev/null
@@ -1,198 +0,0 @@
-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.",
- });
- }
-
- // The browser service response is only type-asserted (no runtime schema
- // validation), so defend against a well-formed 200 that omits `pages`
- // (e.g. version skew) β€” turn a would-be TypeError/500 into an empty list.
- const pages = recording.pages ?? [];
-
- return res.status(200).json({
- success: true,
- pages: 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 ?? pages.length,
- });
-}
-
-/**
- * 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 1a5d48929..e06b6dccf 100644
--- a/apps/api/src/controllers/v2/browser.ts
+++ b/apps/api/src/controllers/v2/browser.ts
@@ -1,69 +1,44 @@
-import { v7 as uuidv7 } from "uuid";
-import { Request, Response } from "express";
+import {
+ getSafeMode,
+ SAFE_MODE_BROWSER_UNSUPPORTED_MESSAGE,
+} from "../../lib/safe-mode";
+import { deleteBrowserProfile } from "../../lib/browser-sessions";
+import { deleteHangarProfile } from "../../lib/hangar";
+import { Response } from "express";
import { z } from "zod";
-import { logger as _logger } from "../../lib/logger";
import { config } from "../../config";
+import { RequestWithAuth } from "./types";
+import { integrationSchema } from "../../utils/integration";
+import { isAgentInteropSecretValid } from "../../lib/agent-interop";
import {
- insertBrowserSession,
getBrowserSession,
- getBrowserSessionByBrowserId,
listBrowserSessions,
updateBrowserSessionActivity,
- updateBrowserSessionStatus,
- updateBrowserSessionCreditsUsed,
- claimBrowserSessionDestroyed,
- invalidateActiveBrowserSessionCount,
- didBrowserSessionUsePrompt,
- clearBrowserSessionPromptFlag,
- upsertBrowserProfile,
- deleteBrowserProfile,
- recordBrowserProfileDeleted,
- getBrowserProfileDeletedAt,
} from "../../lib/browser-sessions";
import {
- getCombinedTeamActiveCount,
- mirrorExternalSlotAcquire,
- mirrorExternalSlotRelease,
-} from "../../services/worker/nuq-router";
-import { getEffectiveConcurrencyLimit } from "../../lib/concurrency-limit";
-import { RequestWithAuth } from "./types";
-import { billTeam } from "../../services/billing/credit_billing";
-import { enqueueBrowserSessionActivity } from "../../lib/browser-session-activity";
-import { logRequest } from "../../services/logging/log_job";
-import { externalRequestId } from "../../lib/external-request-id";
-import { integrationSchema } from "../../utils/integration";
+ createBrowserSession,
+ browserSessionLinks,
+ stopBrowserSession,
+ settleBrowserSession,
+} from "../../lib/browser-lifecycle";
import {
- BROWSER_CREDITS_PER_HOUR,
- INTERACT_CREDITS_PER_HOUR,
- calculateBrowserSessionCredits,
-} from "../../lib/browser-billing";
-import { autumnService } from "../../services/autumn/autumn.service";
-import { orgIdForTeam } from "../../lib/team-org";
-import { isAgentInteropSecretValid } from "../../lib/agent-interop";
-import { recordRequestCredits } from "../../lib/request-credits-store";
-import {
- browserProfileStorageId,
- profileSavedEventSchema,
- resolveProfileSave,
-} from "../../lib/browser-profiles";
-import {
- getSafeMode,
- SAFE_MODE_BROWSER_UNSUPPORTED_MESSAGE,
-} from "../../lib/safe-mode";
-
-// ---------------------------------------------------------------------------
-// Zod schemas
-// ---------------------------------------------------------------------------
+ executeHangarBrowser,
+ getHangarBrowser,
+ getHangarRecording,
+ HangarError,
+} from "../../lib/hangar";
+import { enqueueBrowserSessionActivity } from "../../lib/browser-session-activity";
+import { browserProfileNameSchema } from "../../lib/browser-profiles";
-const browserCreateRequestSchema = z.object({
- ttl: z.number().min(30).max(3600).default(600),
- activityTtl: z.number().min(10).max(3600).default(300),
+export const browserCreateRequestSchema = z.object({
+ ttl: z.number().int().min(30).max(3600).default(600),
+ activityTtl: z.number().int().min(10).max(3600).default(300),
streamWebView: z.boolean().default(true),
recordSession: z.boolean().default(true),
- integration: integrationSchema.optional().transform(val => val || null),
+ integration: integrationSchema.optional().transform(value => value || null),
profile: z
.object({
- name: z.string().min(1).max(128),
+ name: browserProfileNameSchema,
saveChanges: z.boolean().default(true),
})
.optional(),
@@ -76,513 +51,124 @@ const browserCreateRequestSchema = z.object({
.optional(),
});
-type BrowserCreateRequest = z.infer<typeof browserCreateRequestSchema>;
-
-interface BrowserCreateResponse {
- success: boolean;
- id?: string;
- cdpUrl?: string;
- liveViewUrl?: string;
- interactiveLiveViewUrl?: string;
- expiresAt?: string;
- error?: string;
-}
-
const browserExecuteRequestSchema = z.object({
- code: z.string().min(1).max(100_000),
+ code: z
+ .string()
+ .min(1)
+ .refine(
+ value => Buffer.byteLength(value, "utf8") <= 100_000,
+ "Code must not exceed 100,000 UTF-8 bytes.",
+ ),
language: z.enum(["python", "node", "bash"]).default("node"),
- timeout: z.number().min(1).max(300).default(30),
+ timeout: z.number().int().min(1).max(300).default(30),
origin: z.string().optional(),
});
-type BrowserExecuteRequest = z.infer<typeof browserExecuteRequestSchema>;
-
-interface BrowserExecuteResponse {
- success: boolean;
- stdout?: string;
- result?: string;
- stderr?: string;
- exitCode?: number;
- killed?: boolean;
- error?: string;
-}
-
-interface BrowserDeleteResponse {
- success: boolean;
- sessionDurationMs?: number;
- creditsBilled?: number;
- cleanupQueued?: boolean;
- error?: string;
-}
-
-interface BrowserListResponse {
- success: boolean;
- sessions?: Array<{
- id: string;
- status: string;
- cdpUrl: string;
- liveViewUrl: string;
- interactiveLiveViewUrl: string;
- streamWebView: boolean;
- createdAt: string;
- lastActivity: string;
- }>;
- error?: string;
-}
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-/**
- * Build headers for authenticating against the browser service.
- */
-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;
-}
-
-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.
- */
-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,
+export function browserError(res: Response, error: unknown) {
+ return res.status(error instanceof HangarError ? error.status : 502).json({
+ success: false,
+ error:
+ error instanceof HangarError
+ ? error.message
+ : "Browser operation failed.",
});
-
- 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>;
-}
-
-// ---------------------------------------------------------------------------
-// Browser service response types
-// ---------------------------------------------------------------------------
-
-interface BrowserServiceCreateResponse {
- sessionId: string;
- cdpUrl: string;
- viewUrl: string;
- iframeUrl: string;
- interactiveIframeUrl: string;
- expiresAt: string;
}
-interface BrowserServiceExecResponse {
- stdout: string;
- result: string;
- stderr: string;
- exitCode: number;
- killed: boolean;
-}
-
-interface BrowserServiceDeleteResponse {
- ok: boolean;
- sessionDurationMs: number;
- cleanupQueued: boolean;
-}
-
-// ---------------------------------------------------------------------------
-// Controllers
-// ---------------------------------------------------------------------------
-
export async function browserCreateController(
- req: RequestWithAuth<{}, BrowserCreateResponse, BrowserCreateRequest>,
- res: Response<BrowserCreateResponse>,
+ req: RequestWithAuth<{}, any, any>,
+ res: Response,
) {
- // if (!req.acuc?.flags?.browserBeta) {
- // return res.status(403).json({
- // success: false,
- // error:
- // "Browser is currently in beta. Please contact [email protected] to request access.",
- // });
- // }
-
- const sessionId = uuidv7();
- const logger = _logger.child({
- sessionId,
- teamId: req.auth.team_id,
- module: "api/v2",
- method: "browserCreateController",
- });
-
- req.body = browserCreateRequestSchema.parse(req.body);
-
+ const body = browserCreateRequestSchema.parse(req.body);
if (getSafeMode(req.acuc?.flags)) {
- return res.status(403).json({
- success: false,
- error: SAFE_MODE_BROWSER_UNSUPPORTED_MESSAGE,
- });
+ return res
+ .status(403)
+ .json({ success: false, error: SAFE_MODE_BROWSER_UNSUPPORTED_MESSAGE });
}
-
+ req.body = body;
if (
- req.body.__agentInterop &&
- config.AGENT_INTEROP_SECRET &&
- !isAgentInteropSecretValid(req.body.__agentInterop.auth)
+ body.__agentInterop &&
+ (!config.AGENT_INTEROP_SECRET ||
+ !isAgentInteropSecretValid(body.__agentInterop.auth))
) {
- return res.status(403).json({
- success: false,
- error: "Invalid agent interop.",
- });
- } else if (req.body.__agentInterop && !config.AGENT_INTEROP_SECRET) {
- return res.status(403).json({
- success: false,
- error: "Agent interop is not enabled.",
- });
- }
-
- const shouldBill = req.body.__agentInterop?.shouldBill ?? true;
- const agentRequestId = req.body.__agentInterop?.requestId ?? null;
-
- const {
- ttl,
- activityTtl,
- streamWebView,
- recordSession,
- profile,
- integration,
- } = req.body;
-
- if (!config.BROWSER_SERVICE_URL) {
- return res.status(503).json({
- success: false,
- error:
- "Browser feature is not configured (BROWSER_SERVICE_URL is missing).",
- });
- }
-
- logger.info("Creating browser session", { ttl, activityTtl });
-
- // 0a. Check if team has enough credits for the full TTL
- if (shouldBill) {
- const estimatedCredits = calculateBrowserSessionCredits(ttl * 1000);
- // No org, no Autumn customer to gate against: fail open, exactly as
- // checkCredits answered for an identity it could not name.
- const orgId = req.acuc?.org_id ?? null;
- const autumnResult = orgId
- ? await autumnService.checkCredits({
- teamId: req.auth.team_id,
- orgId,
- value: estimatedCredits,
- properties: {
- source: "browserCreate",
- path: req.path,
- apiKeyId: req.acuc?.api_key_id ?? null,
- },
- })
- : null;
-
- if (autumnResult !== null && !autumnResult.allowed) {
- logger.warn("Insufficient credits for browser session TTL", {
- estimatedCredits,
- ttl,
- });
- return res.status(402).json({
- 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.`,
- });
- }
- }
-
- // 0b. Enforce concurrency limit (shared pool with scrape/crawl/interact)
- const concurrencyLimit = await getEffectiveConcurrencyLimit(
- req.auth.team_id,
- req.acuc?.org_id ?? null,
- );
- const activeCount = await getCombinedTeamActiveCount(req.auth.team_id);
- if (activeCount >= concurrencyLimit) {
- logger.warn("Concurrency limit reached for browser session", {
- activeCount,
- limit: concurrencyLimit,
- });
- return res.status(429).json({
- success: false,
- error: `You have reached the maximum number of concurrent jobs (${concurrencyLimit}). Please wait for existing jobs to complete or destroy browser sessions before creating new ones.`,
- });
- }
-
- // 1. Create a browser session via the browser service (retry up to 3 times)
- const MAX_CREATE_RETRIES = 3;
- let svcResponse: BrowserServiceCreateResponse | undefined;
- let lastCreateError: unknown;
-
- // Build persistentStorage from profile if provided
- let persistentStorage: { uniqueId: string; write: boolean } | undefined;
- if (profile) {
- persistentStorage = {
- uniqueId: browserProfileStorageId(req.auth.team_id, profile.name),
- write: profile.saveChanges !== false,
- };
- }
-
- for (let attempt = 1; attempt <= MAX_CREATE_RETRIES; attempt++) {
- try {
- svcResponse = await browserServiceRequest<BrowserServiceCreateResponse>(
- "POST",
- "/browsers",
- {
- ttl,
- record: recordSession,
- customerId: req.auth.team_id,
- ...(activityTtl !== undefined ? { activityTtl } : {}),
- ...(persistentStorage !== undefined ? { persistentStorage } : {}),
- },
- );
- break;
- } catch (err) {
- // 409 means the profile is locked by another writer β€” don't retry
- if (err instanceof BrowserServiceError && err.status === 409) {
- logger.warn("Profile is locked", {
- profileName: profile?.name,
- error: err,
- });
- return res.status(409).json({
- 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.",
- });
- }
-
- 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,
- attempts: MAX_CREATE_RETRIES,
- });
- return res.status(502).json({
- success: false,
- error: "Failed to create browser session.",
- });
+ return res
+ .status(403)
+ .json({ success: false, error: "Invalid agent interop." });
}
-
- // 2. Persist session in Supabase
try {
- if (!agentRequestId) {
- await logRequest({
- id: sessionId,
- kind: "browser",
- api_version: "v2",
- external_request_id: externalRequestId(req),
- team_id: req.auth.team_id,
- target_hint: "Browser session",
- origin: "api",
- integration: integration ?? null,
- zeroDataRetention: false,
- api_key_id: req.acuc!.api_key_id,
- });
- }
- await insertBrowserSession({
- id: sessionId,
- team_id: req.auth.team_id,
- request_id: agentRequestId ?? sessionId,
- should_bill: shouldBill,
- browser_id: svcResponse.sessionId,
- workspace_id: "",
- context_id: "",
- cdp_url: svcResponse.cdpUrl,
- cdp_path: svcResponse.iframeUrl, // repurposed: stores view URL
- cdp_interactive_path: svcResponse.interactiveIframeUrl, // repurposed: stores interactive view URL
- stream_web_view: streamWebView,
- status: "active",
- ttl_total: ttl,
- ttl_without_activity: activityTtl ?? null,
- credits_used: null,
- profile_name: profile?.name ?? null,
- });
- } catch (err) {
- // If we can't persist, tear down the browser session
- logger.error("Failed to persist browser session, cleaning up", {
- error: err,
+ const { session, expiresAt } = await createBrowserSession(req, {
+ ...body,
+ shouldBill: body.__agentInterop?.shouldBill,
+ requestId: body.__agentInterop?.requestId,
});
- await browserServiceRequest(
- "DELETE",
- `/browsers/${svcResponse.sessionId}`,
- ).catch(() => {});
- return res.status(500).json({
- success: false,
- error: "Failed to persist browser session.",
+ return res.json({
+ success: true,
+ id: session.id,
+ ...browserSessionLinks(session),
+ expiresAt,
});
+ } catch (error) {
+ return browserError(res, error);
}
-
- // Invalidate cached count so next check reflects the new session
- invalidateActiveBrowserSessionCount(req.auth.team_id).catch(() => {});
-
- // Register in the shared concurrency limiter so this session counts
- // against the team's concurrent job limit while it's active.
- mirrorExternalSlotAcquire(req.auth.team_id, sessionId, ttl * 1000).catch(
- () => {},
- );
-
- logger.info("Browser session created", {
- sessionId,
- browserId: svcResponse.sessionId,
- });
-
- return res.status(200).json({
- success: true,
- id: sessionId,
- cdpUrl: svcResponse.cdpUrl,
- liveViewUrl: svcResponse.iframeUrl,
- interactiveLiveViewUrl: svcResponse.interactiveIframeUrl,
- expiresAt: svcResponse.expiresAt,
- });
}
-export async function browserExecuteController(
- req: RequestWithAuth<
- { sessionId: string },
- BrowserExecuteResponse,
- BrowserExecuteRequest
- >,
- res: Response<BrowserExecuteResponse>,
+async function resolveBrowserSession(
+ req: RequestWithAuth<{ sessionId: string }, any, any>,
+ res: Response,
) {
- // if (!req.acuc?.flags?.browserBeta) {
- // return res.status(403).json({
- // success: false,
- // error:
- // "Browser is currently in beta. Please contact [email protected] to request access.",
- // });
- // }
-
- req.body = browserExecuteRequestSchema.parse(req.body);
-
- if (getSafeMode(req.acuc?.flags)) {
- return res.status(403).json({
- success: false,
- error: SAFE_MODE_BROWSER_UNSUPPORTED_MESSAGE,
- });
- }
-
- const id = req.params.sessionId;
- const { code, language, timeout, origin } = req.body;
-
- const logger = _logger.child({
- sessionId: id,
- teamId: req.auth.team_id,
- module: "api/v2",
- method: "browserExecuteController",
- });
-
- // Look up session from Supabase
- const session = await getBrowserSession(id);
-
+ const session = await getBrowserSession(req.params.sessionId);
if (!session) {
- return res.status(404).json({
- success: false,
- error: "Browser session not found.",
- });
+ res
+ .status(404)
+ .json({ success: false, error: "Browser session not found." });
+ return;
}
-
if (session.team_id !== req.auth.team_id) {
- return res.status(403).json({
- success: false,
- error: "Forbidden.",
- });
+ res.status(403).json({ success: false, error: "Forbidden." });
+ return;
}
+ return session;
+}
- if (session.status === "destroyed") {
- return res.status(410).json({
- success: false,
- error: "Browser session has been destroyed.",
- });
+export async function browserExecuteController(
+ req: RequestWithAuth<{ sessionId: string }, any, any>,
+ res: Response,
+) {
+ const body = browserExecuteRequestSchema.parse(req.body);
+ if (getSafeMode(req.acuc?.flags)) {
+ return res
+ .status(403)
+ .json({ success: false, error: SAFE_MODE_BROWSER_UNSUPPORTED_MESSAGE });
}
-
- // Update activity timestamp (fire-and-forget)
- updateBrowserSessionActivity(id).catch(() => {});
-
- logger.info("Executing code in browser session", { language, timeout });
-
- // Execute code via the browser service
- let execResult: BrowserServiceExecResponse;
+ const session = await resolveBrowserSession(req, res);
+ if (!session) return;
+ if (session.status === "destroyed")
+ return res
+ .status(410)
+ .json({ success: false, error: "Browser session has been destroyed." });
try {
- execResult = await browserServiceRequest<BrowserServiceExecResponse>(
- "POST",
- `/browsers/${session.browser_id}/exec`,
- { code, 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.",
+ updateBrowserSessionActivity(session.id).catch(() => {});
+ const result = await executeHangarBrowser(session.browser_id, body);
+ enqueueBrowserSessionActivity({
+ team_id: req.auth.team_id,
+ session_id: session.id,
+ source: "browser",
+ language: body.language,
+ timeout: body.timeout,
+ exit_code: result.exitCode,
+ killed: result.killed,
+ });
+ return res.json({
+ success: true,
+ ...result,
+ ...(result.exitCode !== 0 || result.killed
+ ? { error: result.stderr || "Execution failed" }
+ : {}),
});
+ } catch (error) {
+ return browserError(res, error);
}
-
- logger.debug("Execution result", {
- exitCode: execResult.exitCode,
- killed: execResult.killed,
- stdoutLength: execResult.stdout?.length,
- stderrLength: execResult.stderr?.length,
- });
-
- enqueueBrowserSessionActivity({
- team_id: req.auth.team_id,
- session_id: id,
- source: "browser",
- language,
- timeout,
- exit_code: execResult.exitCode ?? null,
- killed: execResult.killed ?? false,
- });
-
- const hasError = execResult.exitCode !== 0 || execResult.killed;
-
- return res.status(200).json({
- success: true,
- stdout: execResult.stdout,
- result: execResult.result,
- stderr: execResult.stderr,
- exitCode: execResult.exitCode,
- killed: execResult.killed,
- ...(hasError ? { error: execResult.stderr || "Execution failed" } : {}),
- });
}
-const profileNameSchema = z.string().min(1).max(128);
-const deletedAtSchema = z.iso.datetime({ offset: true });
-
// DELETE /v2/browser/profiles/:name
// Deletes a persistent profile's saved state and its listing. Deleting a
// profile that has no saved state succeeds.
@@ -591,518 +177,139 @@ export async function browserProfileDeleteController(
res: Response<{ success: boolean; error?: string }>,
) {
if (getSafeMode(req.acuc?.flags)) {
- return res.status(403).json({
- success: false,
- error: SAFE_MODE_BROWSER_UNSUPPORTED_MESSAGE,
- });
+ return res
+ .status(403)
+ .json({ success: false, error: SAFE_MODE_BROWSER_UNSUPPORTED_MESSAGE });
}
-
- const parsed = profileNameSchema.safeParse(req.params.name);
- if (!parsed.success) {
+ const name = browserProfileNameSchema.safeParse(req.params.name);
+ if (!name.success) {
return res.status(400).json({
success: false,
- error: "Profile name must be between 1 and 128 characters.",
+ error: "Profile name must be between 1 and 128 UTF-8 bytes.",
});
}
- const name = parsed.data;
-
- if (!config.BROWSER_SERVICE_URL) {
- return res.status(503).json({
- success: false,
- error:
- "Browser feature is not configured (BROWSER_SERVICE_URL is missing).",
- });
- }
-
- const logger = _logger.child({
- teamId: req.auth.team_id,
- module: "api/v2",
- method: "browserProfileDeleteController",
- });
-
- const storageId = browserProfileStorageId(req.auth.team_id, name);
- let result: { deletedAt?: unknown } | undefined;
try {
- result = await browserServiceRequest<{ deletedAt?: unknown }>(
- "DELETE",
- `/profiles/${encodeURIComponent(storageId)}`,
+ const { deletedAt } = await deleteHangarProfile(
+ req.auth.team_id,
+ name.data,
);
- } catch (err) {
- if (err instanceof BrowserServiceError && err.status === 409) {
+ await deleteBrowserProfile(req.auth.team_id, name.data, deletedAt);
+ return res.json({ success: true });
+ } catch (error) {
+ if (error instanceof HangarError && error.status === 409) {
return res.status(409).json({
success: false,
error:
"A session is currently saving to this profile. Stop that session, then delete the profile.",
});
}
- logger.error("Failed to delete profile via browser service", {
- error: err,
- });
- return res.status(502).json({
- success: false,
- error: "Failed to delete profile.",
- });
+ return browserError(res, error);
}
-
- // profile.saved events carry the browser service's clock, so the tombstone
- // must too; without its deletion time the tombstone could not be compared,
- // so fail and let the (idempotent) delete be retried.
- const parsedDeletedAt = deletedAtSchema.safeParse(result?.deletedAt);
- if (!parsedDeletedAt.success) {
- logger.error("Browser service profile delete returned no valid deletedAt", {
- deletedAt: result?.deletedAt,
- });
- return res.status(502).json({
- success: false,
- error: "Failed to delete profile.",
- });
- }
- const deletedAt = parsedDeletedAt.data;
-
- // Tombstone before removing the row: a late profile.saved for an earlier
- // save that lands before this upserts a row the delete below removes, and
- // any that lands after it is ignored.
- await recordBrowserProfileDeleted(storageId, deletedAt);
- await deleteBrowserProfile(req.auth.team_id, name);
- logger.info("Deleted browser profile");
- return res.status(200).json({ success: true });
}
export async function browserDeleteController(
- req: RequestWithAuth<{ sessionId: string }, BrowserDeleteResponse>,
- res: Response<BrowserDeleteResponse>,
+ req: RequestWithAuth<{ sessionId: string }, any, any>,
+ res: Response,
) {
- // if (!req.acuc?.flags?.browserBeta) {
- // return res.status(403).json({
- // success: false,
- // error:
- // "Browser is currently in beta. Please contact [email protected] to request access.",
- // });
- // }
-
- const id = req.params.sessionId;
-
- const logger = _logger.child({
- sessionId: id,
- teamId: req.auth.team_id,
- module: "api/v2",
- method: "browserDeleteController",
- });
-
- const session = await getBrowserSession(id);
-
- 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.",
- });
- }
-
- // A destroyed session was already released and billed (by an earlier
- // DELETE or by the browser service's session.ended webhook). The browser
- // service no longer knows it, so asking it again can only fail. Report
- // success so that DELETE stays idempotent.
- if (session.status === "destroyed") {
- logger.info("Browser session already destroyed, nothing to release");
- return res.status(200).json({
- success: true,
- cleanupQueued: true,
- });
- }
-
- logger.info("Deleting browser session");
-
- let deleteResult: BrowserServiceDeleteResponse;
+ const session = await resolveBrowserSession(req, res);
+ if (!session) return;
try {
- deleteResult = await browserServiceRequest<BrowserServiceDeleteResponse>(
- "DELETE",
- `/browsers/${session.browser_id}`,
- );
- } catch (err) {
- logger.error("Browser service did not confirm session release", {
- error: err,
- });
- return res.status(502).json({
- success: false,
- error: "Browser session release was not confirmed.",
- });
+ return res.json(await stopBrowserSession(session));
+ } catch (error) {
+ return browserError(res, error);
}
+}
- if (
- !deleteResult ||
- !deleteResult.ok ||
- !deleteResult.cleanupQueued ||
- !Number.isFinite(deleteResult.sessionDurationMs) ||
- deleteResult.sessionDurationMs < 0
- ) {
- logger.error("Browser service returned an invalid release confirmation", {
- deleteResult,
- });
- return res.status(502).json({
- success: false,
- error: "Browser session release was not confirmed.",
- });
- }
-
- const durationMs = deleteResult.sessionDurationMs;
-
- const claimed = await claimBrowserSessionDestroyed(session.id);
-
- // Invalidate cached count so next check reflects the destroyed session
- invalidateActiveBrowserSessionCount(session.team_id).catch(() => {});
- mirrorExternalSlotRelease(session.team_id, session.id).catch(error => {
- logger.error(
- "Failed to remove concurrency limiter entry for browser session",
- {
- error,
- sessionId: session.id,
- teamId: session.team_id,
- },
- );
- });
-
- if (!claimed) {
- // The webhook (or another DELETE call) already transitioned and billed.
- logger.info("Session already destroyed by another path, skipping billing", {
- sessionId: session.id,
- });
- return res.status(200).json({
+export async function browserStatusController(
+ req: RequestWithAuth<{ sessionId: string }, any, any>,
+ res: Response,
+) {
+ const session = await resolveBrowserSession(req, res);
+ if (!session) return;
+ try {
+ const browser = await getHangarBrowser(session.browser_id);
+ const billing = await settleBrowserSession(session, browser);
+ return res.json({
success: true,
- sessionDurationMs: durationMs,
- cleanupQueued: true,
+ id: session.id,
+ status: browser.status,
+ ...browserSessionLinks(session),
+ ...billing,
+ error: browser.error ?? undefined,
});
+ } catch (error) {
+ return browserError(res, error);
}
-
- const usedPrompt = await didBrowserSessionUsePrompt(session.id);
- const rate = usedPrompt
- ? INTERACT_CREDITS_PER_HOUR
- : BROWSER_CREDITS_PER_HOUR;
- const creditsBilled = session.should_bill
- ? calculateBrowserSessionCredits(durationMs, rate)
- : 0;
-
- clearBrowserSessionPromptFlag(session.id).catch(() => {});
-
- await updateBrowserSessionCreditsUsed(session.id, creditsBilled);
-
- const agentRequestId =
- session.request_id && session.request_id !== session.id
- ? session.request_id
- : null;
- if (session.should_bill) {
- billTeam(
- req.auth.team_id,
- req.acuc?.org_id ?? null,
- creditsBilled,
- req.acuc?.api_key_id ?? null,
- {
- endpoint: agentRequestId
- ? "agent"
- : usedPrompt
- ? "interact"
- : "browser",
- jobId: agentRequestId ?? session.id,
- // Keyed on the session rather than on jobId, deliberately: one agent
- // request can drive several sessions, and each is its own charge β€” a key
- // built from the shared agent id would collapse them into one. The
- // per-path suffix guards the other direction: the webhook teardown below
- // bills the same session through a different path.
- chargeId: `${session.id}:destroy`,
- },
- ).catch(error => {
- logger.error("Failed to bill team for browser session", {
- error,
- creditsBilled,
- durationMs,
- });
- });
- }
-
- if (agentRequestId) {
- await recordRequestCredits({
- requestId: agentRequestId,
- jobId: session.id,
- credits: creditsBilled,
- }).catch(error => {
- logger.error("Failed to record browser request credits in Bigtable", {
- error,
- requestId: agentRequestId,
- sessionId: session.id,
- creditsBilled,
- });
- });
- }
-
- logger.info("Browser session destroyed", {
- sessionDurationMs: durationMs,
- creditsBilled,
- });
-
- return res.status(200).json({
- success: true,
- sessionDurationMs: durationMs,
- creditsBilled,
- cleanupQueued: true,
- });
}
export async function browserListController(
- req: RequestWithAuth<{}, BrowserListResponse>,
- res: Response<BrowserListResponse>,
+ req: RequestWithAuth<{}, any, any>,
+ res: Response,
) {
- // if (!req.acuc?.flags?.browserBeta) {
- // return res.status(403).json({
- // success: false,
- // error:
- // "Browser is currently in beta. Please contact [email protected] to request access.",
- // });
- // }
-
- const logger = _logger.child({
- teamId: req.auth.team_id,
- module: "api/v2",
- method: "browserListController",
- });
-
- logger.info("Listing browser sessions");
-
- const statusFilter = (req.query as Record<string, string>).status as
- | "active"
- | "destroyed"
- | undefined;
-
- const rows = await listBrowserSessions(req.auth.team_id, {
- status: statusFilter,
- });
-
- return res.status(200).json({
+ const status = z
+ .enum(["active", "destroyed", "error"])
+ .optional()
+ .parse(req.query.status);
+ const sessions = await listBrowserSessions(req.auth.team_id, { status });
+ return res.json({
success: true,
- sessions: rows.map(r => ({
- id: r.id,
- status: r.status,
- cdpUrl: r.cdp_url,
- liveViewUrl: r.cdp_path,
- interactiveLiveViewUrl: r.cdp_interactive_path,
- streamWebView: r.stream_web_view,
- createdAt: r.created_at,
- lastActivity: r.updated_at,
+ sessions: sessions.map(session => ({
+ id: session.id,
+ status: session.status,
+ ...browserSessionLinks(session),
+ streamWebView: session.stream_web_view,
+ createdAt: session.created_at,
+ lastActivity: session.updated_at,
})),
});
}
-// Records that a session's persistent profile now has saved state, so the
-// profile can be listed. Retried by the browser service on any non-2xx.
-async function handleProfileSavedWebhook(
- req: Request,
+export async function browserReplayController(
+ req: RequestWithAuth<{ sessionId: string }, any, any>,
res: Response,
- logger: typeof _logger,
) {
- const parsed = profileSavedEventSchema.safeParse(req.body);
- if (!parsed.success) {
- logger.warn("Malformed profile.saved webhook", { error: parsed.error });
- return res.status(400).json({ error: "Invalid profile.saved event" });
- }
- const event = parsed.data;
- const browserId = event.sessionId;
-
- const session = await getBrowserSessionByBrowserId(browserId);
- if (!session) {
- logger.warn("No session found for profile.saved webhook", {
- browserId,
- eventId: event.eventId,
- });
- return res.status(200).json({ ok: true });
- }
-
- const resolution = resolveProfileSave(
- session,
- event,
- await getBrowserProfileDeletedAt(event.profileId),
- );
- if (resolution.action === "ignore") {
- logger.info("Not recording saved profile", {
- browserId,
- sessionId: session.id,
- reason: resolution.reason,
- });
- return res.status(200).json({ ok: true });
- }
- if (resolution.action === "reject") {
- logger.error("profile.saved webhook does not match the session's profile", {
- browserId,
- sessionId: session.id,
- teamId: session.team_id,
- profileId: event.profileId,
+ const session = await resolveBrowserSession(req, res);
+ if (!session) return;
+ if (!session.context_id)
+ return res.status(404).json({ success: false, error: "Replay not found." });
+ try {
+ const recording = await getHangarRecording(session.context_id);
+ res.setHeader("Cache-Control", "no-store");
+ return res.json({
+ success: true,
+ pages: [
+ {
+ pageId: "0",
+ url: `/v2/interact/${encodeURIComponent(session.id)}/replay/0`,
+ // The desktop stream spans tabs and has no single page URL.
+ pageUrl: "",
+ startTimeMs: 0,
+ endTimeMs: recording.durationMs,
+ },
+ ],
+ pageCount: 1,
});
- return res
- .status(409)
- .json({ error: "Profile does not match the session" });
+ } catch (error) {
+ return browserError(res, error);
}
-
- await upsertBrowserProfile({
- teamId: resolution.teamId,
- name: resolution.name,
- savedAt: event.savedAt,
- sizeBytes: event.sizeBytes,
- });
- logger.info("Recorded saved browser profile", {
- browserId,
- sessionId: session.id,
- teamId: resolution.teamId,
- eventId: event.eventId,
- });
- return res.status(200).json({ ok: true });
}
-export async function browserWebhookDestroyedController(
- req: Request,
+export async function browserReplayPageController(
+ req: RequestWithAuth<{ sessionId: string; pageId: string }, any, any>,
res: Response,
) {
- const logger = _logger.child({
- module: "api/v2",
- method: "browserWebhookDestroyedController",
- });
-
- // Validate browser service secret
- const secret = req.headers["x-browser-service-secret"];
- if (
- !config.BROWSER_SERVICE_WEBHOOK_SECRET ||
- !secret ||
- secret !== config.BROWSER_SERVICE_WEBHOOK_SECRET
- ) {
- return res.status(401).json({ error: "Unauthorized" });
- }
-
- // The browser service posts every outbox event here. session.ended (the
- // original event, sent without a check on eventType) bills below.
- if (req.body?.eventType === "profile.saved") {
- return handleProfileSavedWebhook(req, res, logger);
- }
-
- const { sessionId, sessionDurationMs } = req.body as {
- sessionId?: string;
- sessionDurationMs?: number;
- };
- if (!sessionId) {
- return res.status(400).json({ error: "Missing browserId" });
- }
- if (
- !Number.isFinite(sessionDurationMs) ||
- (sessionDurationMs as number) < 0
- ) {
- return res.status(400).json({ error: "Missing sessionDurationMs" });
- }
- let browserId = sessionId;
-
- logger.info("Received destroyed webhook from browser service", { browserId });
-
- const session = await getBrowserSessionByBrowserId(browserId);
- if (!session) {
- logger.warn("No session found for destroyed webhook", { browserId });
- return res.status(200).json({ ok: true });
- }
-
- const claimed = await claimBrowserSessionDestroyed(session.id);
-
- invalidateActiveBrowserSessionCount(session.team_id).catch(() => {});
- mirrorExternalSlotRelease(session.team_id, session.id).catch(error => {
- logger.error(
- "Failed to remove concurrency limiter entry for browser session via webhook",
- {
- error,
- sessionId: session.id,
- teamId: session.team_id,
- },
- );
- });
-
- if (!claimed) {
- logger.info("Session already destroyed by another path, skipping billing", {
- sessionId: session.id,
- browserId,
- });
- return res.status(200).json({ ok: true });
- }
-
- const durationMs = sessionDurationMs as number;
-
- const usedPrompt = await didBrowserSessionUsePrompt(session.id);
- const rate = usedPrompt
- ? INTERACT_CREDITS_PER_HOUR
- : BROWSER_CREDITS_PER_HOUR;
- const creditsBilled = session.should_bill
- ? calculateBrowserSessionCredits(durationMs, rate)
- : 0;
-
- clearBrowserSessionPromptFlag(session.id).catch(() => {});
-
- await updateBrowserSessionCreditsUsed(session.id, creditsBilled);
-
- const agentRequestId =
- session.request_id && session.request_id !== session.id
- ? session.request_id
- : null;
- if (session.should_bill) {
- // The webhook carries no request context, so the team's ACUC answers for
- // the org β€” the same lookup the biller used to make for itself.
- billTeam(
- session.team_id,
- await orgIdForTeam(session.team_id),
- creditsBilled,
- null,
- {
- endpoint: agentRequestId
- ? "agent"
- : usedPrompt
- ? "interact"
- : "browser",
- jobId: agentRequestId ?? session.id,
- // Same reasoning as the destroy path above: keyed on the session, not on
- // jobId, and suffixed per path so the two teardown routes cannot dedupe
- // each other's charge away.
- chargeId: `${session.id}:webhook`,
- },
- ).catch(error => {
- logger.error("Failed to bill team for browser session via webhook", {
- error,
- teamId: session.team_id,
- sessionId: session.id,
- creditsBilled,
- durationMs,
- });
- });
- }
-
- if (agentRequestId) {
- await recordRequestCredits({
- requestId: agentRequestId,
- jobId: session.id,
- credits: creditsBilled,
- }).catch(error => {
- logger.error("Failed to record browser request credits in Bigtable", {
- error,
- requestId: agentRequestId,
- sessionId: session.id,
- creditsBilled,
- });
- });
+ if (!/^\d{1,3}$/.test(req.params.pageId))
+ return res.status(400).json({ success: false, error: "Invalid pageId." });
+ const session = await resolveBrowserSession(req, res);
+ if (!session) return;
+ if (req.params.pageId !== "0" || !session.context_id)
+ return res.status(404).json({ success: false, error: "Replay not found." });
+ try {
+ const recording = await getHangarRecording(session.context_id);
+ res.setHeader("Content-Type", "application/vnd.apple.mpegurl");
+ res.setHeader("Cache-Control", "no-store");
+ return res.status(200).send(recording.playlist);
+ } catch (error) {
+ return browserError(res, error);
}
-
- logger.info("Session marked as destroyed via webhook", {
- sessionId: session.id,
- browserId,
- durationMs,
- creditsBilled,
- usedPrompt,
- rate,
- });
-
- return res.status(200).json({ ok: true });
}
diff --git a/apps/api/src/controllers/v2/scrape-browser.ts b/apps/api/src/controllers/v2/scrape-browser.ts
index 91fbca3ca..52157ad28 100644
--- a/apps/api/src/controllers/v2/scrape-browser.ts
+++ b/apps/api/src/controllers/v2/scrape-browser.ts
@@ -1,34 +1,25 @@
-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,
getBrowserSession,
+ getBrowserSessionFromScrape,
updateBrowserSessionActivity,
- updateBrowserSessionCreditsUsed,
updateBrowserSessionScrapeId,
- claimBrowserSessionDestroyed,
- invalidateActiveBrowserSessionCount,
- getBrowserSessionFromScrape,
- markBrowserSessionUsedPrompt,
- didBrowserSessionUsePrompt,
- clearBrowserSessionPromptFlag,
} from "../../lib/browser-sessions";
-import { getEffectiveConcurrencyLimit } from "../../lib/concurrency-limit";
import {
- getCombinedTeamActiveCount,
- mirrorExternalSlotAcquire,
- mirrorExternalSlotRelease,
-} from "../../services/worker/nuq-router";
+ BrowserExecutionResult,
+ executeHangarBrowser,
+ HangarError,
+} from "../../lib/hangar";
import {
- browserServiceRequest,
- BrowserServiceError,
- BrowserServiceExecResponse,
- BrowserServiceCreateResponse,
- BrowserServiceDeleteResponse,
-} from "../../lib/scrape-interact/browser-service-client";
+ createBrowserSession,
+ reserveBrowserPromptCredits,
+ stopBrowserSession,
+ browserSessionLinks,
+} from "../../lib/browser-lifecycle";
+import { browserCreateRequestSchema, browserError } from "./browser";
import {
ScrapeContextRow,
buildReplayContextFromScrape,
@@ -38,6 +29,7 @@ import {
import {
executePromptViaBrowserAgent,
executeCodeViaBrowserSession,
+ selectBrowserAgentTab,
AgentResult,
} from "../../lib/scrape-interact/browser-agent";
import { sanitizeUrlForTrace } from "../../lib/scrape-interact/langsmith";
@@ -47,53 +39,30 @@ import {
SAFE_MODE_BROWSER_UNSUPPORTED_MESSAGE,
} from "../../lib/safe-mode";
import { RequestWithAuth, ScrapeOptions } from "./types";
-import { billTeam } from "../../services/billing/credit_billing";
import {
KEYLESS_FREE_TIER_LIMIT_MESSAGE,
- adjustKeylessCredits,
keylessTeamUuid,
keylessLimitBody,
- logKeylessCreditUsage,
- reserveKeylessCredits,
} from "../../lib/keyless";
import { enqueueBrowserSessionActivity } from "../../lib/browser-session-activity";
-import { logRequest } from "../../services/logging/log_job";
-import { externalRequestId } from "../../lib/external-request-id";
import { integrationSchema } from "../../utils/integration";
import { supabaseGetScrapeByIdDirect } from "../../lib/supabase-jobs";
-import {
- BROWSER_CREDITS_PER_HOUR,
- INTERACT_CREDITS_PER_HOUR,
- calculateBrowserSessionCredits,
-} from "../../lib/browser-billing";
-import { autumnService } from "../../services/autumn/autumn.service";
import { applyAgentAuthDiscoveryHeader } from "../../lib/agent-auth-discovery";
import { getScrapeJobAccess } from "../../lib/operational-job-access";
import { readScrapeJobState } from "../../lib/job-state-store";
import { scrapeQueue } from "../../services/worker/nuq-router";
import { recordJobStorePostgresFallback } from "../../lib/job-store-fallback";
-import { browserProfileStorageId } from "../../lib/browser-profiles";
-
-// ---------------------------------------------------------------------------
-// Schemas
-// ---------------------------------------------------------------------------
-
-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(),
+ code: z
+ .string()
+ .min(1)
+ .refine(
+ value => Buffer.byteLength(value, "utf8") <= 100_000,
+ "Code must not exceed 100,000 UTF-8 bytes.",
+ )
+ .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),
@@ -110,6 +79,7 @@ type BrowserExecuteRequest = z.infer<typeof browserExecuteRequestSchema>;
interface BrowserExecuteResponse {
success: boolean;
sessionId?: string;
+ truncated?: boolean;
cdpUrl?: string;
liveViewUrl?: string;
interactiveLiveViewUrl?: string;
@@ -126,14 +96,9 @@ interface BrowserDeleteResponse {
success: boolean;
sessionDurationMs?: number;
creditsBilled?: number;
- cleanupQueued?: boolean;
error?: string;
}
-// ---------------------------------------------------------------------------
-// POST /v2/scrape/:jobId/interact
-// ---------------------------------------------------------------------------
-
export async function scrapeInteractController(
req: RequestWithAuth<
{ jobId: string },
@@ -283,7 +248,7 @@ export async function scrapeInteractController(
logger,
profile,
);
- if ("error" in created) {
+ if (created.error === true) {
if (
created.status === 429 &&
created.body.error === KEYLESS_FREE_TIER_LIMIT_MESSAGE
@@ -349,12 +314,16 @@ export async function scrapeInteractController(
orgId: req.auth.org_id ?? undefined,
};
- let execResult: BrowserServiceExecResponse | AgentResult;
+ let execResult: BrowserExecutionResult | AgentResult;
if (prompt && !rawCode) {
logger.info("Starting agent loop from prompt", { prompt, timeout });
- markBrowserSessionUsedPrompt(session.id).catch(() => {});
+ try {
+ await reserveBrowserPromptCredits(req, session);
+ } catch (error) {
+ return browserError(res, error);
+ }
try {
execResult = await executePromptViaBrowserAgent(
@@ -430,6 +399,7 @@ export async function scrapeInteractController(
logger.debug("Execution result", {
exitCode: execResult.exitCode,
killed: execResult.killed,
+ truncated: execResult.truncated,
stdoutLength: execResult.stdout?.length,
stderrLength: execResult.stderr?.length,
});
@@ -440,522 +410,76 @@ 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,
+ ...browserSessionLinks(session),
...(agentOutput ? { output: agentOutput } : {}),
stdout: execResult.stdout,
result: execResult.result,
stderr: execResult.stderr,
exitCode: execResult.exitCode,
killed: execResult.killed,
+ truncated: execResult.truncated,
...(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) {
+ if (!session)
return res
.status(404)
.json({ success: false, error: "Browser session not found." });
- }
- if (session.team_id !== req.auth.team_id) {
+ 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,
- });
- // A destroyed session was already released and billed (by an earlier
- // DELETE or by the browser service's session.ended webhook). The browser
- // service no longer knows it, so asking it again can only fail. Report
- // success so that DELETE stays idempotent.
- if (session.status === "destroyed") {
- logger.info("Browser session already destroyed, nothing to release");
- return res.status(200).json({
- success: true,
- cleanupQueued: true,
- });
- }
-
- logger.info("Deleting browser session");
-
- let deleteResult: BrowserServiceDeleteResponse;
try {
- deleteResult = await browserServiceRequest<BrowserServiceDeleteResponse>(
- "DELETE",
- `/browsers/${session.browser_id}`,
- );
- } catch (err) {
- logger.error("Browser service did not confirm session release", {
- error: err,
- });
- return res.status(502).json({
- success: false,
- error: "Browser session release was not confirmed.",
- });
+ return res.json(await stopBrowserSession(session));
+ } catch (error) {
+ return browserError(res, error);
}
-
- if (
- !deleteResult ||
- !deleteResult.ok ||
- !deleteResult.cleanupQueued ||
- !Number.isFinite(deleteResult.sessionDurationMs) ||
- deleteResult.sessionDurationMs < 0
- ) {
- logger.error("Browser service returned an invalid release confirmation", {
- deleteResult,
- });
- return res.status(502).json({
- success: false,
- error: "Browser session release was not confirmed.",
- });
- }
-
- const durationMs = deleteResult.sessionDurationMs;
-
- const claimed = await claimBrowserSessionDestroyed(session.id);
-
- invalidateActiveBrowserSessionCount(session.team_id).catch(() => {});
- mirrorExternalSlotRelease(session.team_id, session.id).catch(error => {
- logger.error(
- "Failed to remove concurrency limiter entry for browser session",
- {
- error,
- sessionId: session.id,
- teamId: session.team_id,
- },
- );
- });
-
- if (!claimed) {
- logger.info("Session already destroyed by another path, skipping billing", {
- sessionId: session.id,
- });
- return res.status(200).json({
- success: true,
- sessionDurationMs: durationMs,
- cleanupQueued: true,
- });
- }
-
- const usedPrompt = await didBrowserSessionUsePrompt(session.id);
- const rate = usedPrompt
- ? INTERACT_CREDITS_PER_HOUR
- : BROWSER_CREDITS_PER_HOUR;
- const creditsBilled = calculateBrowserSessionCredits(durationMs, rate);
-
- clearBrowserSessionPromptFlag(session.id).catch(() => {});
-
- 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?.org_id ?? null,
- creditsBilled,
- req.acuc?.api_key_id ?? null,
- {
- endpoint: "interact",
- // Not set from this request: the stop request is not the one that
- // created the session, so its header would misattribute the charge.
- // firebill finds the creating request's id by the session id.
- jobId: session.id,
- chargeId: `${session.id}:scrape-browser`,
- },
- ).catch(error => {
- logger.error("Failed to bill team for interact session", {
- error,
- creditsBilled,
- durationMs,
- });
- });
-
- const reservedCredits = calculateBrowserSessionCredits(
- session.ttl_total * 1000,
- BROWSER_CREDITS_PER_HOUR,
- );
- adjustKeylessCredits(req.auth.team_id, creditsBilled - reservedCredits).catch(
- () => {},
- );
- logKeylessCreditUsage(req.auth.team_id, creditsBilled).catch(() => {});
-
- logger.info("Browser session destroyed", {
- sessionDurationMs: durationMs,
- creditsBilled,
- usedPrompt,
- rate,
- });
-
- return res.status(200).json({
- success: true,
- sessionDurationMs: durationMs,
- creditsBilled,
- cleanupQueued: 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,
+ replayContext: NonNullable<
+ ReturnType<typeof buildReplayContextFromScrape>["context"]
+ >,
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 (uses base rate β€” actual billing may be higher if prompts are used)
- const estimatedCredits = calculateBrowserSessionCredits(ttl * 1000);
- const reservation = await reserveKeylessCredits(
- req.auth.team_id,
- estimatedCredits,
- );
- if (!reservation.ok) {
- return {
- status: 429,
- body: await keylessLimitBody(req.auth.team_id, "v2_browser"),
- error: true,
- };
- }
- const keylessReserved = estimatedCredits;
-
- // No org, no Autumn customer to gate against: fail open, exactly as
- // checkCredits answered for an identity it could not name.
- const orgId = req.acuc?.org_id ?? null;
- const autumnResult = orgId
- ? await autumnService.checkCredits({
- teamId: req.auth.team_id,
- orgId,
- value: estimatedCredits,
- properties: {
- source: "scrapeBrowserCreate",
- path: req.path,
- apiKeyId: req.acuc?.api_key_id ?? null,
- },
- })
- : null;
-
- if (autumnResult !== null && !autumnResult.allowed) {
- adjustKeylessCredits(req.auth.team_id, -keylessReserved).catch(() => {});
- 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 β€” uses the same concurrency pool as scrape/crawl
- const concurrencyLimit = await getEffectiveConcurrencyLimit(
- req.auth.team_id,
- req.acuc?.org_id ?? null,
- );
- const activeCount = await getCombinedTeamActiveCount(req.auth.team_id);
- if (activeCount >= concurrencyLimit) {
- adjustKeylessCredits(req.auth.team_id, -keylessReserved).catch(() => {});
- return {
- status: 429,
- body: {
- success: false,
- error: `You have reached the maximum number of concurrent jobs (${concurrencyLimit}). Please wait for existing jobs to complete or destroy browser 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) {
- persistentStorage = {
- uniqueId: browserProfileStorageId(req.auth.team_id, profile.name),
- write: profile.saveChanges !== false,
- };
- }
-
- for (let attempt = 1; attempt <= MAX_CREATE_RETRIES; attempt++) {
- try {
- svcResponse = await browserServiceRequest<BrowserServiceCreateResponse>(
- "POST",
- "/browsers",
- {
- ttl,
- // Record interact sessions so the replay endpoints (which we expose
- // via the returned sessionId) have data. Set explicitly rather than
- // relying on the browser service's implicit default, matching the
- // standalone browser create path.
- record: true,
- customerId: req.auth.team_id,
- ...(activityTtl !== undefined ? { activityTtl } : {}),
- ...(persistentStorage !== undefined ? { persistentStorage } : {}),
- },
- );
- break;
- } catch (err) {
- if (err instanceof BrowserServiceError && err.status === 409) {
- adjustKeylessCredits(req.auth.team_id, -keylessReserved).catch(
- () => {},
- );
- 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) {
- adjustKeylessCredits(req.auth.team_id, -keylessReserved).catch(() => {});
- 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`,
- {
+ const { session } = await createBrowserSession(req, {
+ ...browserCreateRequestSchema.parse({}),
+ scrapeId,
+ profile,
+ initialize: async browserId => {
+ const replay = await executeHangarBrowser(browserId, {
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.",
- );
- }
-
- // Prime agent-browser before consolidating: its first command of a session
- // spawns an about:blank tab, so trigger it now and let the sync below close it.
- const primeResult = await browserServiceRequest<BrowserServiceExecResponse>(
- "POST",
- `/browsers/${svcResponse.sessionId}/exec`,
- {
- code: `agent-browser get url`,
- language: "bash",
- timeout: 10,
- origin: "scrape_replay_sync",
- },
- ).catch(() => null);
-
- // Keep only the content tab, repoint the REPL's page var, bring to front.
- // agent-browser falls back to the surviving tab when its own is closed.
- 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",
+ });
+ if (replay.exitCode !== 0 || replay.killed)
+ throw new HangarError(
+ 409,
+ "Failed to initialize browser session from the original scrape context. Please rerun the scrape and try again.",
+ );
+ await selectBrowserAgentTab(browserId);
},
- ).catch(() => {});
-
- // Verify agent-browser is on the content page after cleanup.
- let agentUrl = (primeResult?.stdout || "").trim();
- if (!agentUrl || agentUrl === "about:blank") {
- const syncResult =
- await browserServiceRequest<BrowserServiceExecResponse>(
- "POST",
- `/browsers/${svcResponse.sessionId}/exec`,
- {
- code: `agent-browser get url`,
- language: "bash",
- timeout: 10,
- origin: "scrape_replay_sync",
- },
- );
- 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) {
- adjustKeylessCredits(req.auth.team_id, -keylessReserved).catch(() => {});
- 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",
- external_request_id: externalRequestId(req),
- 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,
- request_id: sessionId,
- should_bill: true,
- 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,
- profile_name: profile?.name ?? null,
});
-
- invalidateActiveBrowserSessionCount(req.auth.team_id).catch(() => {});
-
- // Register in the shared concurrency limiter so this session counts
- // against the team's concurrent job limit while it's active.
- mirrorExternalSlotAcquire(req.auth.team_id, sessionId, ttl * 1000).catch(
- () => {},
- );
-
return { session };
- } catch (err) {
- adjustKeylessCredits(req.auth.team_id, -keylessReserved).catch(() => {});
- 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,
- };
+ } catch (error) {
+ logger.error("Failed to initialize scrape browser session", { error });
+ const status = error instanceof HangarError ? error.status : 502;
+ const message =
+ error instanceof HangarError
+ ? error.message
+ : "Failed to create browser session.";
+ const body =
+ message === KEYLESS_FREE_TIER_LIMIT_MESSAGE
+ ? await keylessLimitBody(req.auth.team_id, "v2_browser")
+ : { success: false as const, error: message };
+ return { error: true as const, status, body };
}
}
diff --git a/apps/api/src/controllers/v2/types.ts b/apps/api/src/controllers/v2/types.ts
index 274566fe1..88ecc7bd1 100644
--- a/apps/api/src/controllers/v2/types.ts
+++ b/apps/api/src/controllers/v2/types.ts
@@ -2,6 +2,7 @@ import { Request, Response } from "express";
import { hasCategory } from "../../lib/search-query-builder";
import { config } from "../../config";
import { z } from "zod";
+import { browserProfileNameSchema } from "../../lib/browser-profiles";
import { protocolIncluded, checkUrl } from "../../lib/validateUrl";
import { hasReachableHost } from "../../lib/url-utils";
import { countries } from "../../lib/validate-country";
@@ -740,7 +741,7 @@ const redactPIISchema = z
});
// inferred shape: RedactPIIOptions | undefined after the transform
-const baseScrapeOptions = z.strictObject({
+const scrapeOptionFields = z.strictObject({
formats: z
.preprocess(
val => {
@@ -838,7 +839,7 @@ const baseScrapeOptions = z.strictObject({
profile: z
.object({
- name: z.string().min(1).max(128),
+ name: browserProfileNameSchema,
saveChanges: z.boolean().default(true),
})
.optional(),
@@ -851,6 +852,14 @@ const baseScrapeOptions = z.strictObject({
__forceFirePDF: z.boolean().prefault(false).optional(),
});
+const baseScrapeOptions = scrapeOptionFields.refine(
+ options => !(options.profile && options.lockdown),
+ {
+ message: "Profiles require live browsing and cannot be used with lockdown.",
+ path: ["profile"],
+ },
+);
+
type ScrapeOptionsBase = z.infer<typeof baseScrapeOptions>;
const waitForRefine = (obj?: ScrapeOptionsBase): boolean => {
@@ -1125,7 +1134,7 @@ export const agentRequestSchema = z
export type AgentRequest = z.infer<typeof agentRequestSchema>;
// export type AgentRequestInput = z.input<typeof agentRequestSchema>;
-const scrapeRequestSchemaBase = baseScrapeOptions.extend({
+const scrapeRequestSchemaBase = baseScrapeOptions.safeExtend({
url: URL,
origin: z.string().optional().prefault("api"),
integration: integrationSchema.optional().transform(val => val || null),
@@ -1185,7 +1194,7 @@ const uploadedParseFileSchema = z.custom<UploadedParseFile>(
},
);
-const parseRequestSchemaBase = baseScrapeOptions.extend({
+const parseRequestSchemaBase = baseScrapeOptions.safeExtend({
origin: z.string().optional().prefault("api"),
integration: integrationSchema.optional().transform(val => val || null),
zeroDataRetention: z.boolean().optional(),
@@ -1217,7 +1226,7 @@ export const parseRequestSchema = strictWithMessage(parseRequestSchemaBase)
export type ParseRequest = z.infer<typeof parseRequestSchema>;
export type ParseRequestInput = z.input<typeof parseRequestSchemaBase>;
-const batchScrapeRequestSchemaBase = baseScrapeOptions.extend({
+const batchScrapeRequestSchemaBase = baseScrapeOptions.safeExtend({
urls: URL.array().min(1),
origin: z.string().optional().prefault("api"),
integration: integrationSchema.optional().transform(val => val || null),
@@ -1241,23 +1250,24 @@ export const batchScrapeRequestSchema = strictWithMessage(
.refine(waitForRefine, waitForRefineOpts)
.transform(extractTransformRequired);
-const batchScrapeRequestSchemaNoURLValidationBase = baseScrapeOptions.extend({
- urls: z.string().array().min(1),
- origin: z.string().optional().prefault("api"),
- integration: integrationSchema.optional().transform(val => val || null),
- webhook: webhookSchema.optional(),
- appendToId: z.uuid().optional(),
- ignoreInvalidURLs: z.boolean().prefault(true),
- maxConcurrency: z.int().positive().optional(),
- zeroDataRetention: z.boolean().optional(),
- __agentInterop: z
- .object({
- auth: z.string(),
- requestId: z.string(),
- shouldBill: z.boolean(),
- })
- .optional(),
-});
+const batchScrapeRequestSchemaNoURLValidationBase =
+ baseScrapeOptions.safeExtend({
+ urls: z.string().array().min(1),
+ origin: z.string().optional().prefault("api"),
+ integration: integrationSchema.optional().transform(val => val || null),
+ webhook: webhookSchema.optional(),
+ appendToId: z.uuid().optional(),
+ ignoreInvalidURLs: z.boolean().prefault(true),
+ maxConcurrency: z.int().positive().optional(),
+ zeroDataRetention: z.boolean().optional(),
+ __agentInterop: z
+ .object({
+ auth: z.string(),
+ requestId: z.string(),
+ shouldBill: z.boolean(),
+ })
+ .optional(),
+ });
export const batchScrapeRequestSchemaNoURLValidation = strictWithMessage(
batchScrapeRequestSchemaNoURLValidationBase,
@@ -2420,7 +2430,7 @@ export const searchRequestSchema = z
__searchPreviewToken: z.string().optional(),
threatProtection: threatProtectionOverrideSchema.optional(),
scrapeOptions: baseScrapeOptions
- .extend({
+ .safeExtend({
formats: z
.preprocess(
val => {
diff --git a/apps/api/src/db/schema/public.ts b/apps/api/src/db/schema/public.ts
index 774bd1273..4a4717a35 100644
--- a/apps/api/src/db/schema/public.ts
+++ b/apps/api/src/db/schema/public.ts
@@ -149,8 +149,7 @@ export const browser_sessions = pgTable("browser_sessions", {
});
// Index of saved persistent browser profiles (see browser_profiles migration).
-// Contents live in browser-service object storage; a row is upserted when the
-// browser service reports a successful save.
+// Contents live in Hangar; reconciliation upserts a row after a confirmed save.
export const browser_profiles = pgTable(
"browser_profiles",
{
diff --git a/apps/api/src/lib/browser-lifecycle.ts b/apps/api/src/lib/browser-lifecycle.ts
new file mode 100644
index 000000000..d7b2e507a
--- /dev/null
+++ b/apps/api/src/lib/browser-lifecycle.ts
@@ -0,0 +1,463 @@
+import { z } from "zod";
+import { recordRequestCredits } from "./request-credits-store";
+import { upsertBrowserProfile } from "./browser-sessions";
+import { v7 as uuidv7 } from "uuid";
+import { config } from "../config";
+import { RequestWithAuth } from "../controllers/v2/types";
+import {
+ createHangarBrowser,
+ getHangarBrowser,
+ stopHangarBrowser,
+ HangarBrowser,
+ HangarError,
+} from "./hangar";
+import {
+ insertBrowserSession,
+ completeBrowserSessionSettlement,
+ markBrowserSessionUsedPrompt,
+ settleBrowserSessionOnce,
+ withLockedBrowserSession,
+ didBrowserSessionUsePrompt,
+ listUnsettledHangarSessions,
+ BrowserSessionRow,
+} from "./browser-sessions";
+import {
+ calculateBrowserSessionCredits,
+ BROWSER_CREDITS_PER_HOUR,
+ INTERACT_CREDITS_PER_HOUR,
+} from "./browser-billing";
+import { getEffectiveConcurrencyLimit } from "./concurrency-limit";
+import {
+ reserveExternalSlot,
+ mirrorExternalSlotRelease,
+} from "../services/worker/nuq-router";
+import { autumnService } from "../services/autumn/autumn.service";
+import { billTeam } from "../services/billing/credit_billing";
+import { orgIdForTeam } from "./team-org";
+import { logRequest } from "../services/logging/log_job";
+import { externalRequestId } from "./external-request-id";
+import {
+ updateKeylessBrowserCredits,
+ logKeylessCreditUsage,
+ KEYLESS_FREE_TIER_LIMIT_MESSAGE,
+} from "./keyless";
+import { logger } from "./logger";
+import { redlock } from "../services/redlock";
+import { redisRateLimitClient } from "../services/rate-limiter";
+
+export function browserSessionLinks(session: BrowserSessionRow) {
+ return {
+ cdpUrl: session.cdp_url,
+ liveViewUrl: session.cdp_path ?? "",
+ interactiveLiveViewUrl: session.cdp_interactive_path ?? "",
+ };
+}
+
+export async function createBrowserSession(
+ req: RequestWithAuth<any, any, any>,
+ options: {
+ ttl: number;
+ activityTtl: number;
+ streamWebView: boolean;
+ recordSession: boolean;
+ profile?: { name: string; saveChanges: boolean };
+ scrapeId?: string;
+ shouldBill?: boolean;
+ requestId?: string;
+ initialize?: (browserId: string) => Promise<void>;
+ },
+) {
+ if (!config.HANGAR_URL)
+ throw new HangarError(
+ 503,
+ "Browser feature is not configured (HANGAR_URL is missing).",
+ );
+ const shouldBill = options.shouldBill ?? true;
+ const estimatedCredits = shouldBill
+ ? calculateBrowserSessionCredits(options.ttl * 1000)
+ : 0;
+ const limit = await getEffectiveConcurrencyLimit(
+ req.auth.team_id,
+ req.acuc?.org_id ?? null,
+ );
+ if (shouldBill && req.acuc?.org_id) {
+ const credit = await autumnService.checkCredits({
+ teamId: req.auth.team_id,
+ orgId: req.acuc.org_id,
+ value: estimatedCredits,
+ properties: {
+ source: "browserCreate",
+ path: req.path,
+ apiKeyId: req.acuc?.api_key_id ?? null,
+ },
+ });
+ if (credit !== null && !credit.allowed)
+ throw new HangarError(
+ 402,
+ `Insufficient credits for a ${options.ttl}s browser session (requires ~${estimatedCredits} credits).`,
+ );
+ }
+ const id = uuidv7();
+ let browserId: string | undefined;
+ try {
+ if (
+ !(await reserveExternalSlot(
+ req.auth.team_id,
+ id,
+ (options.ttl + 300) * 1000,
+ limit,
+ ))
+ )
+ throw new HangarError(
+ 429,
+ `You have reached the maximum number of concurrent jobs (${limit}).`,
+ );
+ if (
+ !(await updateKeylessBrowserCredits(
+ req.auth.team_id,
+ id,
+ estimatedCredits,
+ ))
+ )
+ throw new HangarError(429, KEYLESS_FREE_TIER_LIMIT_MESSAGE);
+ const browser = await createHangarBrowser(id, req.auth.team_id, options);
+ browserId = browser.id;
+ if (options.initialize) await options.initialize(browser.id);
+ if (!options.requestId)
+ await logRequest({
+ id,
+ kind: options.scrapeId ? "interact" : "browser",
+ api_version: "v2",
+ external_request_id: externalRequestId(req),
+ team_id: req.auth.team_id,
+ target_hint: "Browser session",
+ origin: req.body?.origin ?? "api",
+ integration: req.body?.integration ?? null,
+ zeroDataRetention: false,
+ api_key_id: req.acuc?.api_key_id ?? null,
+ });
+ const session = await insertBrowserSession({
+ id,
+ team_id: req.auth.team_id,
+ request_id: options.requestId ?? id,
+ should_bill: shouldBill,
+ scrape_id: options.scrapeId,
+ browser_id: browser.id,
+ workspace_id: "",
+ context_id: browser.playlist_url ?? "",
+ cdp_url: browser.cdp_url,
+ cdp_path: browser.view_url ?? "",
+ cdp_interactive_path: browser.control_url ?? "",
+ stream_web_view: options.streamWebView,
+ status: "active",
+ ttl_total: options.ttl,
+ ttl_without_activity: options.activityTtl,
+ credits_used: null,
+ profile_name: options.profile?.name ?? null,
+ });
+ return {
+ session,
+ expiresAt:
+ browser.max_expires_at === null
+ ? undefined
+ : new Date(browser.max_expires_at * 1000).toISOString(),
+ };
+ } catch (error) {
+ if (browserId) await stopHangarBrowser(browserId).catch(() => {});
+ await mirrorExternalSlotRelease(req.auth.team_id, id).catch(error =>
+ logger.error("Failed to release browser reservation", {
+ sessionId: id,
+ error,
+ }),
+ );
+ await updateKeylessBrowserCredits(req.auth.team_id, id, 0, true).catch(
+ error =>
+ logger.error("Failed to refund browser reservation", {
+ sessionId: id,
+ error,
+ }),
+ );
+ throw error;
+ }
+}
+
+export async function settleBrowserSession(
+ session: BrowserSessionRow,
+ browser: HangarBrowser,
+) {
+ if (browser.status !== "stopped" && browser.status !== "failed") return;
+ if (
+ !Number.isFinite(browser.ended_at) ||
+ !Number.isFinite(browser.created_at) ||
+ browser.ended_at! < browser.created_at
+ )
+ throw new HangarError(
+ 502,
+ "Hangar did not return a valid session duration.",
+ );
+ if (
+ session.profile_name &&
+ browser.profile_saved_at &&
+ z.uuid().safeParse(session.team_id).success
+ ) {
+ const savedAt = new Date(browser.profile_saved_at * 1000).toISOString();
+ await upsertBrowserProfile({
+ teamId: session.team_id,
+ name: session.profile_name,
+ savedAt,
+ sizeBytes: undefined,
+ });
+ }
+ const sessionDurationMs = (browser.ended_at! - browser.created_at) * 1000;
+ // The prompt flag is read under the row lock so a concurrent prompt cannot
+ // change the rate after it is recorded.
+ let usedPrompt = false;
+ const { creditsBilled, newlySettled } = await settleBrowserSessionOnce(
+ session.id,
+ async current => {
+ usedPrompt =
+ current.should_bill && (await didBrowserSessionUsePrompt(current.id));
+ return current.should_bill
+ ? calculateBrowserSessionCredits(
+ sessionDurationMs,
+ usedPrompt ? INTERACT_CREDITS_PER_HOUR : BROWSER_CREDITS_PER_HOUR,
+ )
+ : 0;
+ },
+ );
+ // Billing follows the receipt commit, like every other endpoint: a retried
+ // settlement never re-queues the debit, and a failed charge is logged.
+ if (newlySettled) {
+ const agentRequestId =
+ session.request_id && session.request_id !== session.id
+ ? session.request_id
+ : undefined;
+ if (session.should_bill) {
+ billTeam(
+ session.team_id,
+ await orgIdForTeam(session.team_id),
+ creditsBilled,
+ null,
+ {
+ endpoint: agentRequestId
+ ? "agent"
+ : usedPrompt || session.scrape_id
+ ? "interact"
+ : "browser",
+ jobId: agentRequestId ?? session.id,
+ chargeId: `${session.id}:destroy`,
+ },
+ ).catch(error =>
+ logger.error("Failed to bill browser session", {
+ sessionId: session.id,
+ creditsBilled,
+ error,
+ }),
+ );
+ }
+ if (agentRequestId) {
+ await recordRequestCredits({
+ requestId: agentRequestId,
+ jobId: session.id,
+ credits: creditsBilled,
+ }).catch(error =>
+ logger.error("Failed to record browser request credits", {
+ sessionId: session.id,
+ error,
+ }),
+ );
+ }
+ }
+ await finalizeBrowserSession(session, creditsBilled);
+ return { sessionDurationMs, creditsBilled };
+}
+
+async function finalizeBrowserSession(
+ session: BrowserSessionRow,
+ credits: number,
+) {
+ await updateKeylessBrowserCredits(session.team_id, session.id, credits, true);
+ await mirrorExternalSlotRelease(session.team_id, session.id);
+ if (await completeBrowserSessionSettlement(session.id))
+ await logKeylessCreditUsage(session.team_id, credits);
+}
+
+export async function reserveBrowserPromptCredits(
+ req: RequestWithAuth<any, any, any>,
+ session: BrowserSessionRow,
+) {
+ const closed = new HangarError(
+ 410,
+ "Browser session is no longer accepting prompts.",
+ );
+ if (session.status !== "active" || session.credits_used !== null)
+ throw closed;
+ // Upstream checks stay outside the row lock so a slow Hangar or Autumn
+ // response does not pin a database connection.
+ const browser = await getHangarBrowser(session.browser_id, 0, 5000);
+ if (["stopping", "stopped", "failed"].includes(browser.status)) throw closed;
+ // The interact rate is reserved once per session; later prompts add nothing.
+ if (await didBrowserSessionUsePrompt(session.id)) return;
+ const credits = calculateBrowserSessionCredits(
+ session.ttl_total * 1000,
+ INTERACT_CREDITS_PER_HOUR,
+ );
+ if (session.should_bill && req.acuc?.org_id) {
+ const credit = await autumnService.checkCredits({
+ teamId: session.team_id,
+ orgId: req.acuc.org_id,
+ value: credits,
+ properties: {
+ source: "browserPrompt",
+ path: req.path,
+ apiKeyId: req.acuc?.api_key_id ?? null,
+ },
+ });
+ if (credit !== null && !credit.allowed)
+ throw new HangarError(
+ 402,
+ "Insufficient credits for a browser prompt session.",
+ );
+ }
+ // The same row lock guards settlement: a prompt admitted before stop
+ // records its rate before billing reads it, and a later prompt cannot
+ // change it. A failed flag read/write must not run at the cheaper rate.
+ await withLockedBrowserSession(session.id, async current => {
+ if (current.status !== "active" || current.credits_used !== null)
+ throw closed;
+ if (await didBrowserSessionUsePrompt(current.id)) return;
+ if (
+ current.should_bill &&
+ !(await updateKeylessBrowserCredits(current.team_id, current.id, credits))
+ )
+ throw new HangarError(429, KEYLESS_FREE_TIER_LIMIT_MESSAGE);
+ await markBrowserSessionUsedPrompt(current.id);
+ });
+}
+
+export async function stopBrowserSession(session: BrowserSessionRow) {
+ if (session.status === "destroyed") {
+ return {
+ success: true,
+ status: "stopped",
+ creditsBilled: session.credits_used ?? 0,
+ };
+ }
+ let browser = await stopHangarBrowser(session.browser_id);
+ if (!["stopping", "stopped", "failed"].includes(browser.status))
+ throw new HangarError(502, "Hangar did not confirm the stop request.");
+ // A successful public DELETE includes final duration and billing, even
+ // though Hangar's stop endpoint acknowledges cleanup asynchronously.
+ const deadline = Date.now() + 30_000;
+ while (browser.status === "stopping") {
+ const remaining = deadline - Date.now();
+ if (remaining <= 0)
+ throw new HangarError(
+ 502,
+ "Browser is still stopping. Retry deletion shortly.",
+ );
+ browser = await getHangarBrowser(
+ session.browser_id,
+ 0,
+ Math.min(remaining, 5000),
+ );
+ if (browser.status === "stopping")
+ await new Promise(resolve => setTimeout(resolve, 250));
+ }
+ if (browser.status !== "stopped" && browser.status !== "failed")
+ throw new HangarError(502, "Hangar did not confirm session release.");
+ const settled = await settleBrowserSession(session, browser);
+ return {
+ success: true,
+ status: browser.status,
+ ...settled,
+ };
+}
+
+let reconciling = false;
+export async function reconcileBrowserSessions() {
+ if (!config.HANGAR_URL || reconciling) return;
+ reconciling = true;
+ let acquired = false;
+ try {
+ await redlock.using(
+ ["browser:reconcile:lock"],
+ 60_000,
+ { retryCount: 0 },
+ async signal => {
+ acquired = true;
+ const nextRun = Number(
+ await redisRateLimitClient.get("browser:reconcile:next"),
+ );
+ if (nextRun > Date.now()) return;
+ await redisRateLimitClient.set(
+ "browser:reconcile:next",
+ Date.now() + 15_000,
+ "EX",
+ 60,
+ );
+ // Fix the end of each sweep so new sessions cannot indefinitely
+ // postpone retrying older sessions. Failed rows retain their backoff.
+ const scanKey = "browser:reconcile:scan";
+ const cursor = await redisRateLimitClient.hgetall(scanKey);
+ const { sessions, through } = await listUnsettledHangarSessions(cursor);
+ const results = await Promise.allSettled(
+ sessions.map(async session => {
+ const key = `browser:reconcile:${session.id}`;
+ const state = await redisRateLimitClient.hgetall(key);
+ if (Number(state.next) > Date.now() || signal.aborted) return;
+ let failures = 0;
+ try {
+ // The persisted receipt lets quota reconciliation retry independently
+ // of Hangar availability and recording/session metadata retention.
+ if (session.credits_used !== null) {
+ await finalizeBrowserSession(session, session.credits_used);
+ } else {
+ await settleBrowserSession(
+ session,
+ await getHangarBrowser(session.browser_id, 0, 5000),
+ );
+ }
+ } catch (error) {
+ failures = Math.min(Number(state.failures ?? 0) + 1, 5);
+ // Repeat failures during an outage are expected; only the
+ // first one per session is an error.
+ logger[failures > 1 ? "warn" : "error"](
+ "Failed to reconcile Hangar session",
+ {
+ sessionId: session.id,
+ error,
+ },
+ );
+ }
+ await redisRateLimitClient.hset(key, {
+ failures,
+ next: Date.now() + Math.min(300_000, 30_000 * 2 ** failures),
+ });
+ await redisRateLimitClient.expire(key, 2 * 86400);
+ }),
+ );
+ results.forEach((result, index) => {
+ if (result.status === "rejected")
+ logger.error("Failed to update browser reconciliation state", {
+ sessionId: sessions[index].id,
+ error: result.reason,
+ });
+ });
+ if (signal.aborted) throw signal.error;
+ const lastId = sessions.at(-1)?.id;
+ if (lastId && through && lastId !== through) {
+ await redisRateLimitClient.hset(scanKey, { after: lastId, through });
+ } else {
+ await redisRateLimitClient.del(scanKey);
+ }
+ },
+ );
+ } catch (error) {
+ // Other replicas normally own the lease; only log failures after acquiring it.
+ if (acquired)
+ logger.error("Failed to reconcile browser sessions", { error });
+ } finally {
+ reconciling = false;
+ }
+}
diff --git a/apps/api/src/lib/browser-profiles.test.ts b/apps/api/src/lib/browser-profiles.test.ts
index f53ce10eb..8ccfe0d62 100644
--- a/apps/api/src/lib/browser-profiles.test.ts
+++ b/apps/api/src/lib/browser-profiles.test.ts
@@ -1,144 +1,16 @@
-import {
- browserProfileStorageId,
- profileSavedEventSchema,
- resolveProfileSave,
-} from "./browser-profiles";
-
+import { browserProfileDeletedKey } from "./browser-profiles";
const TEAM = "00000000-0000-4000-8000-000000000001";
const OTHER_TEAM = "00000000-0000-4000-8000-000000000002";
-
-describe("browserProfileStorageId", () => {
- it("prefixes the name with the first 16 hex chars of sha256(teamId)", () => {
- expect(browserProfileStorageId(TEAM, "my-profile")).toBe(
- "11e594f481958c10_my-profile",
+describe("browserProfileDeletedKey", () => {
+ it("isolates teams and preserves names containing separators", () => {
+ expect(browserProfileDeletedKey(TEAM, "login")).not.toBe(
+ browserProfileDeletedKey(OTHER_TEAM, "login"),
);
- expect(browserProfileStorageId(OTHER_TEAM, "my-profile")).toBe(
- "e79acd97ac880866_my-profile",
+ expect(browserProfileDeletedKey("a_b", "c")).not.toBe(
+ browserProfileDeletedKey("a", "b_c"),
);
- });
-
- it("keeps the name verbatim, underscores included", () => {
- expect(browserProfileStorageId(TEAM, "a_b c")).toBe(
- "11e594f481958c10_a_b c",
+ expect(browserProfileDeletedKey(TEAM, "a/b c")).not.toBe(
+ browserProfileDeletedKey(TEAM, "a/b"),
);
});
});
-
-describe("profileSavedEventSchema", () => {
- const event = {
- eventId: "a4f5c6a0-4c1f-4a7f-9d0b-3e0f1d2c3b4a",
- eventType: "profile.saved",
- sessionId: "bs_123",
- profileId: "11e594f481958c10_my-profile",
- savedAt: "2026-09-22T19:30:00.000Z",
- sizeBytes: 48213,
- attempt: 2,
- };
-
- it("accepts the event the browser service sends", () => {
- expect(profileSavedEventSchema.parse(event)).toMatchObject({
- sessionId: "bs_123",
- profileId: "11e594f481958c10_my-profile",
- savedAt: "2026-09-22T19:30:00.000Z",
- sizeBytes: 48213,
- });
- });
-
- it("accepts an event without a size", () => {
- const { sizeBytes: _, ...withoutSize } = event;
- expect(profileSavedEventSchema.safeParse(withoutSize).success).toBe(true);
- });
-
- it.each([
- ["another event type", { eventType: "session.ended" }],
- ["a missing savedAt", { savedAt: undefined }],
- ["a savedAt that is not a timestamp", { savedAt: "yesterday" }],
- ["a negative size", { sizeBytes: -1 }],
- ["a fractional size", { sizeBytes: 1.5 }],
- ["an empty profile id", { profileId: "" }],
- ])("rejects %s", (_, override) => {
- expect(
- profileSavedEventSchema.safeParse({ ...event, ...override }).success,
- ).toBe(false);
- });
-});
-
-describe("resolveProfileSave", () => {
- const profileId = browserProfileStorageId(TEAM, "my-profile");
- const savedAt = "2026-09-22T12:00:00.000Z";
- const session = { team_id: TEAM, profile_name: "my-profile" };
-
- it("upserts under the session's own team and profile name", () => {
- expect(resolveProfileSave(session, { profileId, savedAt })).toEqual({
- action: "upsert",
- teamId: TEAM,
- name: "my-profile",
- });
- });
-
- it("ignores sessions that recorded no profile name", () => {
- for (const profile_name of [null, undefined]) {
- expect(
- resolveProfileSave(
- { team_id: TEAM, profile_name },
- { profileId, savedAt },
- ),
- ).toEqual({ action: "ignore", reason: "no_profile_name" });
- }
- });
-
- it("ignores keyless callers, which have no team to list under", () => {
- const keylessTeam = "preview_keyless_203.0.113.7";
- expect(
- resolveProfileSave(
- { team_id: keylessTeam, profile_name: "my-profile" },
- {
- profileId: browserProfileStorageId(keylessTeam, "my-profile"),
- savedAt,
- },
- ),
- ).toEqual({ action: "ignore", reason: "not_a_team" });
- });
-
- it("rejects a storage id that belongs to another team", () => {
- expect(
- resolveProfileSave(session, {
- profileId: browserProfileStorageId(OTHER_TEAM, "my-profile"),
- savedAt,
- }),
- ).toEqual({ action: "reject", reason: "profile_mismatch" });
- });
-
- it("rejects a storage id for a different profile name", () => {
- expect(
- resolveProfileSave(session, {
- profileId: browserProfileStorageId(TEAM, "other-profile"),
- savedAt,
- }),
- ).toEqual({ action: "reject", reason: "profile_mismatch" });
- });
-
- it("ignores a save from before the profile was deleted", () => {
- for (const deletedAt of [savedAt, "2026-09-22T12:00:01.000Z"]) {
- expect(
- resolveProfileSave(session, { profileId, savedAt }, deletedAt),
- ).toEqual({ action: "ignore", reason: "deleted" });
- }
- });
-
- it("fails closed on an unreadable deletion time", () => {
- expect(
- resolveProfileSave(session, { profileId, savedAt }, "not-a-time"),
- ).toEqual({ action: "ignore", reason: "deleted" });
- });
-
- it("records a save made after the profile was deleted", () => {
- expect(
- resolveProfileSave(
- session,
- { profileId, savedAt },
- "2026-09-22T11:59:59.000Z",
- ),
- ).toEqual({ action: "upsert", teamId: TEAM, name: "my-profile" });
- });
-});
diff --git a/apps/api/src/lib/browser-profiles.ts b/apps/api/src/lib/browser-profiles.ts
index 39005405c..e4de7da53 100644
--- a/apps/api/src/lib/browser-profiles.ts
+++ b/apps/api/src/lib/browser-profiles.ts
@@ -1,84 +1,14 @@
-// Pure helpers for persistent browser profiles, kept free of the DB so the
-// scrape engine can import the storage id. The table writes live in
-// browser-sessions.ts.
-import { createHash } from "crypto";
import { z } from "zod";
-/**
- * The id a profile's saved state is stored under in the browser service: the
- * first 16 hex chars of sha256(teamId), then the profile name. /scrape, browser
- * sessions and interact sessions must all derive it the same way, or they read
- * and write different profiles.
- */
-export function browserProfileStorageId(teamId: string, name: string): string {
- const teamHash = createHash("sha256")
- .update(teamId)
- .digest("hex")
- .slice(0, 16);
- return `${teamHash}_${name}`;
-}
-
-// Sent by the browser service's webhook outbox after it uploads a session's
-// profile. It names the browser-service session and the storage id only.
-export const profileSavedEventSchema = z.object({
- eventType: z.literal("profile.saved"),
- eventId: z.string().min(1),
- sessionId: z.string().min(1),
- profileId: z.string().min(1),
- savedAt: z.iso.datetime({ offset: true }),
- sizeBytes: z.number().int().nonnegative().optional(),
-});
-
-type ProfileSavedEvent = z.infer<typeof profileSavedEventSchema>;
-
-type ProfileSaveResolution =
- | { action: "upsert"; teamId: string; name: string }
- | { action: "ignore"; reason: "no_profile_name" | "not_a_team" | "deleted" }
- | { action: "reject"; reason: "profile_mismatch" };
-
-// Redis key holding when a profile was last deleted (browser-service clock),
-// kept for longer than the browser service retries a profile.saved event.
-export function browserProfileDeletedKey(storageId: string): string {
- return `browser-profile-deleted:${storageId}`;
-}
-
-/**
- * Decides what a reported save means for the session it came from. The team
- * and profile name come from our own session row, never from the event, and
- * the event's storage id must be the one that row derives. `deletedAt` is when
- * the profile was last deleted, if recently.
- */
-export function resolveProfileSave(
- session: { team_id: string; profile_name?: string | null },
- event: Pick<ProfileSavedEvent, "profileId" | "savedAt">,
- deletedAt?: string | null,
-): ProfileSaveResolution {
- // Sessions created before profile_name was recorded.
- if (!session.profile_name) {
- return { action: "ignore", reason: "no_profile_name" };
- }
- // Keyless callers (preview_keyless_<ip>) have no teams row to list under.
- if (!z.uuid().safeParse(session.team_id).success) {
- return { action: "ignore", reason: "not_a_team" };
- }
- if (
- browserProfileStorageId(session.team_id, session.profile_name) !==
- event.profileId
- ) {
- return { action: "reject", reason: "profile_mismatch" };
- }
- // A save that finished before the profile was deleted (its event delivered
- // late) must not bring the listing back; a save after the delete does. An
- // unreadable deletion time fails closed.
- if (deletedAt) {
- const deletedMs = Date.parse(deletedAt);
- if (Number.isNaN(deletedMs) || Date.parse(event.savedAt) <= deletedMs) {
- return { action: "ignore", reason: "deleted" };
- }
- }
- return {
- action: "upsert",
- teamId: session.team_id,
- name: session.profile_name,
- };
+// Hangar limits profile names to 1–128 UTF-8 bytes, not characters.
+export const browserProfileNameSchema = z
+ .string()
+ .min(1)
+ .refine(
+ value => Buffer.byteLength(value, "utf8") <= 128,
+ "Profile name must be between 1 and 128 UTF-8 bytes.",
+ );
+
+export function browserProfileDeletedKey(teamId: string, name: string): string {
+ return `browser-profile-deleted:${JSON.stringify([teamId, name])}`;
}
diff --git a/apps/api/src/lib/browser-sessions.ts b/apps/api/src/lib/browser-sessions.ts
index 99eab3204..ac6367984 100644
--- a/apps/api/src/lib/browser-sessions.ts
+++ b/apps/api/src/lib/browser-sessions.ts
@@ -1,32 +1,26 @@
-import { and, desc, eq, sql } from "drizzle-orm";
import { z } from "zod";
-import { deleteKey, getValue, setValue } from "../services/redis";
+import { createHash } from "node:crypto";
+import { and, asc, desc, eq, gt, like, lte, ne, sql } from "drizzle-orm";
+import { getValue, setValue } from "../services/redis";
import { redisRateLimitClient } from "../services/rate-limiter";
import { db } from "../db/connection";
import * as schema from "../db/schema";
import { browserProfileDeletedKey } from "./browser-profiles";
-import { logger as _logger } from "./logger";
-
-const logger = _logger.child({ module: "browser-sessions" });
-
-function activeBrowserCountKey(teamId: string): string {
- return `browser_sessions:active_count:${teamId}`;
-}
type BrowserSessionStatus = "active" | "destroyed" | "error";
-interface BrowserSessionRow {
+export interface BrowserSessionRow {
id: string;
team_id: string;
request_id: string | null;
should_bill: boolean;
scrape_id?: string | null; // linked scrape job id for /scrape/:jobId/interact sessions
- browser_id: string; // browser service sessionId
+ browser_id: string; // Hangar browser id
workspace_id: string; // unused (legacy), stored as ""
- context_id: string; // unused (legacy), stored as ""
- cdp_url: string; // full CDP WebSocket URL from browser service
- cdp_path: string; // repurposed: stores the view WebSocket URL
- cdp_interactive_path: string; // repurposed: stores the interactive view WebSocket URL
+ context_id: string; // Hangar playlist URL; empty when recording is disabled
+ cdp_url: string; // Hangar CDP WebSocket URL
+ cdp_path: string; // Hangar view URL
+ cdp_interactive_path: string; // Hangar control URL
stream_web_view: boolean;
status: BrowserSessionStatus;
ttl_total: number;
@@ -37,293 +31,231 @@ interface BrowserSessionRow {
updated_at: string; // ISO timestamp
}
-// ---------------------------------------------------------------------------
-// CRUD helpers
-// ---------------------------------------------------------------------------
+export async function listUnsettledHangarSessions(cursor: {
+ after?: string;
+ through?: string;
+}): Promise<{ sessions: BrowserSessionRow[]; through: string | null }> {
+ const unsettled = and(
+ eq(schema.browser_sessions.status, "active"),
+ like(schema.browser_sessions.browser_id, "br\\_%"),
+ );
+ let through = cursor.through;
+ const after = through ? cursor.after : undefined;
+ if (!through) {
+ const [last] = await db
+ .select({ id: schema.browser_sessions.id })
+ .from(schema.browser_sessions)
+ .where(unsettled)
+ .orderBy(desc(schema.browser_sessions.id))
+ .limit(1);
+ through = last?.id;
+ }
+ if (!through) return { sessions: [], through: null };
+ const sessions = (await db
+ .select()
+ .from(schema.browser_sessions)
+ .where(
+ and(
+ unsettled,
+ lte(schema.browser_sessions.id, through),
+ after ? gt(schema.browser_sessions.id, after) : undefined,
+ ),
+ )
+ .orderBy(asc(schema.browser_sessions.id))
+ .limit(20)) as BrowserSessionRow[];
+ return { sessions, through };
+}
+
+/** Serialize prompt-rate changes and settlement across replicas. */
+export async function withLockedBrowserSession<T>(
+ id: string,
+ run: (
+ session: BrowserSessionRow,
+ tx: Pick<typeof db, "update">,
+ ) => Promise<T>,
+): Promise<T> {
+ return db.transaction(async tx => {
+ const [row] = await tx
+ .select()
+ .from(schema.browser_sessions)
+ .where(eq(schema.browser_sessions.id, id))
+ .for("update");
+ if (!row) throw new Error("Browser session not found.");
+ return run(row as BrowserSessionRow, tx);
+ });
+}
+
+/** Record the billed amount once; a failed bill leaves the row unsettled for retry. */
+export async function settleBrowserSessionOnce(
+ id: string,
+ bill: (session: BrowserSessionRow) => Promise<number>,
+): Promise<{ creditsBilled: number; newlySettled: boolean }> {
+ return withLockedBrowserSession(id, async (row, tx) => {
+ if (row.status === "destroyed" || row.credits_used !== null)
+ return { creditsBilled: row.credits_used ?? 0, newlySettled: false };
+ const creditsBilled = await bill(row);
+ await tx
+ .update(schema.browser_sessions)
+ .set({
+ credits_used: creditsBilled,
+ updated_at: new Date().toISOString(),
+ })
+ .where(eq(schema.browser_sessions.id, id));
+ return { creditsBilled, newlySettled: true };
+ });
+}
+
+/** Keep the row discoverable until its keyless refund and slot release succeed. */
+export async function completeBrowserSessionSettlement(id: string) {
+ const completed = await db
+ .update(schema.browser_sessions)
+ .set({
+ status: "destroyed",
+ deleted_at: new Date().toISOString(),
+ })
+ .where(
+ and(
+ eq(schema.browser_sessions.id, id),
+ ne(schema.browser_sessions.status, "destroyed"),
+ sql`${schema.browser_sessions.credits_used} IS NOT NULL`,
+ ),
+ )
+ .returning({ id: schema.browser_sessions.id });
+ return completed.length > 0;
+}
export async function insertBrowserSession(
row: Omit<BrowserSessionRow, "created_at" | "updated_at">,
): Promise<BrowserSessionRow> {
const now = new Date().toISOString();
- const full: BrowserSessionRow = {
- ...row,
- created_at: now,
- updated_at: now,
- };
-
- const MAX_ATTEMPTS = 10;
- let lastError: any = null;
- for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
- try {
- const [data] = await db
- .insert(schema.browser_sessions)
- .values(full)
- .returning();
-
- return data as BrowserSessionRow;
- } catch (error) {
- lastError = error;
- logger.error("Error inserting browser session, trying again", {
- error,
- id: row.id,
- attempt,
- });
- await new Promise(resolve => setTimeout(resolve, 75));
- }
- }
-
- logger.error("Failed to insert browser session after all retries", {
- error: lastError,
- id: row.id,
- attempts: MAX_ATTEMPTS,
- });
- throw new Error(
- `Failed to insert browser session: ${lastError?.message ?? "unknown error"}`,
- );
+ const [data] = await db
+ .insert(schema.browser_sessions)
+ .values({ ...row, created_at: now, updated_at: now })
+ .returning();
+ return data as BrowserSessionRow;
}
export async function getBrowserSession(
id: string,
): Promise<BrowserSessionRow | null> {
- try {
- const [data] = await db
- .select()
- .from(schema.browser_sessions)
- .where(eq(schema.browser_sessions.id, id))
- .limit(1);
- return (data ?? null) as BrowserSessionRow | null;
- } catch (error) {
- logger.error("Failed to get browser session", { error, id });
- throw new Error(
- `Failed to get browser session: ${error instanceof Error ? error.message : JSON.stringify(error)}`,
- );
- }
+ const [data] = await db
+ .select()
+ .from(schema.browser_sessions)
+ .where(eq(schema.browser_sessions.id, id))
+ .limit(1);
+ return (data ?? null) as BrowserSessionRow | null;
}
export async function getBrowserSessionFromScrape(
id: string,
): Promise<BrowserSessionRow | null> {
- try {
- // scrape_id is not unique: two concurrent interact calls on one scrape can
- // each insert a row. Prefer the newest row that is not destroyed, so that
- // callers act on a live session. Fall back to the newest destroyed row.
- const rows = (await db
- .select()
- .from(schema.browser_sessions)
- .where(eq(schema.browser_sessions.scrape_id, id))
- .orderBy(
- desc(schema.browser_sessions.created_at),
- )) as BrowserSessionRow[];
- return rows.find(row => row.status !== "destroyed") ?? rows[0] ?? null;
- } catch (error) {
- logger.error("Failed to get browser session from scrape", { error, id });
- throw new Error(
- `Failed to get browser session from scrape: ${error instanceof Error ? error.message : JSON.stringify(error)}`,
- );
- }
+ // scrape_id is not unique: two concurrent interact calls on one scrape can
+ // each insert a row. Prefer the newest row that is not destroyed, so that
+ // callers act on a live session. Fall back to the newest destroyed row.
+ const rows = (await db
+ .select()
+ .from(schema.browser_sessions)
+ .where(eq(schema.browser_sessions.scrape_id, id))
+ .orderBy(desc(schema.browser_sessions.created_at))) as BrowserSessionRow[];
+ return rows.find(row => row.status !== "destroyed") ?? rows[0] ?? null;
}
export async function listBrowserSessions(
teamId: string,
opts?: { status?: BrowserSessionStatus },
): Promise<BrowserSessionRow[]> {
- const conditions = [eq(schema.browser_sessions.team_id, teamId)];
- if (opts?.status) {
- conditions.push(eq(schema.browser_sessions.status, opts.status));
- }
-
- try {
- const data = await db
- .select()
- .from(schema.browser_sessions)
- .where(and(...conditions))
- .orderBy(desc(schema.browser_sessions.created_at));
- return data as BrowserSessionRow[];
- } catch (error) {
- logger.error("Failed to list browser sessions", { error, teamId });
- throw new Error(
- `Failed to list browser sessions: ${error instanceof Error ? error.message : JSON.stringify(error)}`,
- );
- }
+ return (await db
+ .select()
+ .from(schema.browser_sessions)
+ .where(
+ and(
+ eq(schema.browser_sessions.team_id, teamId),
+ opts?.status
+ ? eq(schema.browser_sessions.status, opts.status)
+ : undefined,
+ ),
+ )
+ .orderBy(desc(schema.browser_sessions.created_at))) as BrowserSessionRow[];
}
export async function listActiveBrowserSessionsForRequest(
teamId: string,
requestId: string,
): Promise<BrowserSessionRow[]> {
- try {
- const data = await db
- .select()
- .from(schema.browser_sessions)
- .where(
- and(
- eq(schema.browser_sessions.team_id, teamId),
- eq(schema.browser_sessions.request_id, requestId),
- eq(schema.browser_sessions.status, "active"),
- ),
- )
- .orderBy(desc(schema.browser_sessions.created_at));
- return data as BrowserSessionRow[];
- } catch (error) {
- logger.error("Failed to list active browser sessions for request", {
- error,
- teamId,
- requestId,
- });
- throw new Error(
- `Failed to list active browser sessions for request: ${error instanceof Error ? error.message : JSON.stringify(error)}`,
- );
- }
+ return (await db
+ .select()
+ .from(schema.browser_sessions)
+ .where(
+ and(
+ eq(schema.browser_sessions.team_id, teamId),
+ eq(schema.browser_sessions.request_id, requestId),
+ eq(schema.browser_sessions.status, "active"),
+ ),
+ )
+ .orderBy(desc(schema.browser_sessions.created_at))) as BrowserSessionRow[];
}
export async function updateBrowserSessionActivity(id: string): Promise<void> {
- try {
- await db
- .update(schema.browser_sessions)
- .set({ updated_at: new Date().toISOString() })
- .where(eq(schema.browser_sessions.id, id));
- } catch (error) {
- logger.warn("Failed to update browser session activity", { error, id });
- }
-}
-
-export async function getBrowserSessionByBrowserId(
- browserId: string,
-): Promise<BrowserSessionRow | null> {
- try {
- const [data] = await db
- .select()
- .from(schema.browser_sessions)
- .where(eq(schema.browser_sessions.browser_id, browserId))
- .limit(1);
- return (data ?? null) as BrowserSessionRow | null;
- } catch (error) {
- logger.error("Failed to get browser session by browser_id", {
- error,
- browserId,
- });
- throw new Error(
- `Failed to get browser session by browser_id: ${error instanceof Error ? error.message : JSON.stringify(error)}`,
- );
- }
-}
-
-export async function updateBrowserSessionStatus(
- id: string,
- status: BrowserSessionStatus,
-): Promise<void> {
- try {
- await db
- .update(schema.browser_sessions)
- .set({
- status,
- updated_at: new Date().toISOString(),
- deleted_at: status === "destroyed" ? new Date().toISOString() : null,
- })
- .where(eq(schema.browser_sessions.id, id));
- } catch (error) {
- logger.warn("Failed to update browser session status", { error, id });
- }
-}
-
-export async function claimBrowserSessionDestroyed(
- id: string,
-): Promise<boolean> {
- const now = new Date().toISOString();
- try {
- const data = await db
- .update(schema.browser_sessions)
- .set({
- status: "destroyed" as BrowserSessionStatus,
- updated_at: now,
- deleted_at: now,
- })
- .where(
- and(
- eq(schema.browser_sessions.id, id),
- eq(schema.browser_sessions.status, "active"),
- ),
- )
- .returning({ id: schema.browser_sessions.id });
- return data.length > 0;
- } catch (error) {
- logger.warn("Failed to claim browser session destroyed", { error, id });
- return false;
- }
+ await db
+ .update(schema.browser_sessions)
+ .set({ updated_at: new Date().toISOString() })
+ .where(eq(schema.browser_sessions.id, id));
}
export async function updateBrowserSessionScrapeId(
id: string,
scrapeId: string,
): Promise<void> {
- try {
- await db
- .update(schema.browser_sessions)
- .set({ scrape_id: scrapeId, updated_at: new Date().toISOString() })
- .where(eq(schema.browser_sessions.id, id));
- } catch (error) {
- logger.warn("Failed to update browser session scrape_id", {
- error,
- id,
- scrapeId,
- });
- }
-}
-
-export async function updateBrowserSessionCreditsUsed(
- id: string,
- creditsUsed: number,
-): Promise<void> {
- try {
- await db
- .update(schema.browser_sessions)
- .set({
- credits_used: creditsUsed,
- updated_at: new Date().toISOString(),
- })
- .where(eq(schema.browser_sessions.id, id));
- } catch (error) {
- logger.warn("Failed to update browser session credits_used", {
- error,
- id,
- creditsUsed,
- });
- }
+ await db
+ .update(schema.browser_sessions)
+ .set({ scrape_id: scrapeId, updated_at: new Date().toISOString() })
+ .where(eq(schema.browser_sessions.id, id));
}
// Records a successful save of a persistent profile. Throws on failure so the
-// browser service's webhook outbox retries the event.
+// Hangar reconciliation retries the update.
export async function upsertBrowserProfile(input: {
teamId: string;
name: string;
savedAt: string;
sizeBytes: number | undefined;
}): Promise<void> {
- const profiles = schema.browser_profiles;
- await db
- .insert(profiles)
- .values({
- team_id: input.teamId,
- name: input.name,
- saved_at: input.savedAt,
- size_bytes: input.sizeBytes ?? null,
- })
- .onConflictDoUpdate({
- target: [profiles.team_id, profiles.name],
- // Retried deliveries can arrive out of order, so an older save never
- // replaces a newer one. A save that reported no size keeps the last
- // known size rather than erasing it.
- set: {
- saved_at: sql`GREATEST(${profiles.saved_at}, excluded.saved_at)`,
- size_bytes: sql`CASE WHEN excluded.saved_at >= ${profiles.saved_at} THEN COALESCE(excluded.size_bytes, ${profiles.size_bytes}) ELSE ${profiles.size_bytes} END`,
- },
- });
+ await db.transaction(async tx => {
+ await tx.execute(
+ sql`SELECT pg_advisory_xact_lock(hashtextextended(${browserProfileDeletedKey(input.teamId, input.name)}, 0))`,
+ );
+ const deletedAt = await getBrowserProfileDeletedAt(
+ input.teamId,
+ input.name,
+ );
+ if (deletedAt && !(Date.parse(input.savedAt) > Date.parse(deletedAt)))
+ return;
+ const profiles = schema.browser_profiles;
+ await tx
+ .insert(profiles)
+ .values({
+ team_id: input.teamId,
+ name: input.name,
+ saved_at: input.savedAt,
+ size_bytes: input.sizeBytes ?? null,
+ })
+ .onConflictDoUpdate({
+ target: [profiles.team_id, profiles.name],
+ // Retried deliveries can arrive out of order, so an older save never
+ // replaces a newer one. A save that reported no size keeps the last
+ // known size rather than erasing it.
+ set: {
+ saved_at: sql`GREATEST(${profiles.saved_at}, excluded.saved_at)`,
+ size_bytes: sql`CASE WHEN excluded.saved_at >= ${profiles.saved_at} THEN COALESCE(excluded.size_bytes, ${profiles.size_bytes}) ELSE ${profiles.size_bytes} END`,
+ },
+ });
+ });
}
-// Remembers when a profile was deleted, so a profile.saved event for an
-// earlier save that is delivered late cannot relist it. Outlives the browser
-// service's retries (at most ~10 minutes).
-const PROFILE_DELETED_TTL_SECONDS = 3600;
+// Prevents late reconciliation of an earlier save from relisting a deleted
+// profile. Outlives the browser
+// metadata retention and background reconciliation window.
+const PROFILE_DELETED_TTL_SECONDS = 2 * 86400;
// Keeps the newest deletion time: responses to concurrent deletes can land
// out of order, and an older time must not shrink the window. Timestamps are
@@ -336,23 +268,39 @@ const SET_IF_NEWER_LUA = `
return 1
`;
-export async function recordBrowserProfileDeleted(
- storageId: string,
+async function recordBrowserProfileDeleted(
+ teamId: string,
+ name: string,
deletedAt: string,
): Promise<void> {
await redisRateLimitClient.eval(
SET_IF_NEWER_LUA,
1,
- browserProfileDeletedKey(storageId),
+ browserProfileDeletedKey(teamId, name),
new Date(deletedAt).toISOString(),
String(PROFILE_DELETED_TTL_SECONDS),
);
}
-export async function getBrowserProfileDeletedAt(
- storageId: string,
+async function getBrowserProfileDeletedAt(
+ teamId: string,
+ name: string,
): Promise<string | null> {
- return getValue(browserProfileDeletedKey(storageId));
+ // Keep honoring tombstones written by the previous deployment (one-hour TTL).
+ const teamHash = createHash("sha256")
+ .update(teamId)
+ .digest("hex")
+ .slice(0, 16);
+ const values = await Promise.all([
+ getValue(browserProfileDeletedKey(teamId, name)),
+ getValue(`browser-profile-deleted:${teamHash}_${name}`),
+ ]);
+ const tombstones = values.filter((value): value is string => value !== null);
+ if (tombstones.some(value => !Number.isFinite(Date.parse(value))))
+ throw new Error("Invalid browser profile deletion timestamp.");
+ return (
+ tombstones.sort((a, b) => Date.parse(a) - Date.parse(b)).at(-1) ?? null
+ );
}
// Removes a profile's listing once its saved state is deleted. Keyless callers
@@ -360,20 +308,34 @@ export async function getBrowserProfileDeletedAt(
export async function deleteBrowserProfile(
teamId: string,
name: string,
+ deletedAt: string,
): Promise<void> {
- if (!z.uuid().safeParse(teamId).success) return;
- const profiles = schema.browser_profiles;
- await db
- .delete(profiles)
- .where(and(eq(profiles.team_id, teamId), eq(profiles.name, name)));
+ if (!z.uuid().safeParse(teamId).success) {
+ await recordBrowserProfileDeleted(teamId, name, deletedAt);
+ return;
+ }
+ await db.transaction(async tx => {
+ await tx.execute(
+ sql`SELECT pg_advisory_xact_lock(hashtextextended(${browserProfileDeletedKey(teamId, name)}, 0))`,
+ );
+ await recordBrowserProfileDeleted(teamId, name, deletedAt);
+ const profiles = schema.browser_profiles;
+ await tx
+ .delete(profiles)
+ .where(
+ and(
+ eq(profiles.team_id, teamId),
+ eq(profiles.name, name),
+ sql`${profiles.saved_at} <= ${deletedAt}`,
+ ),
+ );
+ });
}
// ---------------------------------------------------------------------------
// Prompt usage tracking (Redis)
// ---------------------------------------------------------------------------
-const PROMPT_FLAG_TTL_SECONDS = 7200; // 2 hours, well beyond max session TTL
-
function promptFlagKey(sessionId: string): string {
return `browser_session:used_prompt:${sessionId}`;
}
@@ -381,48 +343,11 @@ function promptFlagKey(sessionId: string): string {
export async function markBrowserSessionUsedPrompt(
sessionId: string,
): Promise<void> {
- try {
- await setValue(promptFlagKey(sessionId), "1", PROMPT_FLAG_TTL_SECONDS);
- } catch {
- // Redis down β€” non-fatal, will fall back to standard rate at billing time
- }
+ await setValue(promptFlagKey(sessionId), "1", PROFILE_DELETED_TTL_SECONDS);
}
export async function didBrowserSessionUsePrompt(
sessionId: string,
): Promise<boolean> {
- try {
- const val = await getValue(promptFlagKey(sessionId));
- return val === "1";
- } catch {
- return false;
- }
-}
-
-export async function clearBrowserSessionPromptFlag(
- sessionId: string,
-): Promise<void> {
- try {
- await deleteKey(promptFlagKey(sessionId));
- } catch {
- // non-fatal
- }
-}
-
-// ---------------------------------------------------------------------------
-// Active session count (cached)
-// ---------------------------------------------------------------------------
-
-/**
- * Invalidate the cached active session count for a team.
- * Call after creating or destroying a session.
- */
-export async function invalidateActiveBrowserSessionCount(
- teamId: string,
-): Promise<void> {
- try {
- await deleteKey(activeBrowserCountKey(teamId));
- } catch {
- // Redis down β€” non-fatal
- }
+ return (await getValue(promptFlagKey(sessionId))) === "1";
}
diff --git a/apps/api/src/lib/concurrency-redis.ts b/apps/api/src/lib/concurrency-redis.ts
index 8b9a419eb..eccf72493 100644
--- a/apps/api/src/lib/concurrency-redis.ts
+++ b/apps/api/src/lib/concurrency-redis.ts
@@ -42,6 +42,32 @@ export async function pushConcurrencyLimitActiveJob(
);
}
+/** Admit and register a browser in the same operation as the capacity check. */
+export async function reserveConcurrencyLimitSlot(
+ teamId: string,
+ id: string,
+ timeout: number,
+ limit: number,
+): Promise<boolean> {
+ return (
+ (await getRedisConnection().eval(
+ `
+ local now = tonumber(ARGV[1])
+ if redis.call('ZSCORE', KEYS[1], ARGV[2]) then return 1 end
+ if redis.call('ZCOUNT', KEYS[1], now, '+inf') >= tonumber(ARGV[4]) then return 0 end
+ redis.call('ZADD', KEYS[1], now + tonumber(ARGV[3]), ARGV[2])
+ return 1
+ `,
+ 1,
+ constructConcurrencyLimitKey(teamId),
+ Date.now(),
+ id,
+ timeout,
+ limit,
+ )) === 1
+ );
+}
+
export async function removeConcurrencyLimitActiveJob(
team_id: string,
id: string,
diff --git a/apps/api/src/lib/hangar.ts b/apps/api/src/lib/hangar.ts
new file mode 100644
index 000000000..221a7d8d0
--- /dev/null
+++ b/apps/api/src/lib/hangar.ts
@@ -0,0 +1,275 @@
+import { config } from "../config";
+
+export interface HangarBrowser {
+ id: string;
+ status:
+ | "starting"
+ | "running"
+ | "suspending"
+ | "suspended"
+ | "resuming"
+ | "stopping"
+ | "stopped"
+ | "failed";
+ created_at: number;
+ ended_at: number | null;
+ max_expires_at: number | null;
+ recording: boolean;
+ profile_saved_at?: number | null;
+ error?: string | null;
+}
+
+interface HangarCreated extends HangarBrowser {
+ cdp_url: string;
+ view_url?: string;
+ control_url?: string;
+ playlist_url?: string;
+}
+
+export interface BrowserExecutionResult {
+ stdout: string;
+ result: string;
+ stderr: string;
+ exitCode: number;
+ killed: boolean;
+ truncated?: boolean;
+}
+
+export class HangarError extends Error {
+ constructor(
+ public status: number,
+ message: string,
+ ) {
+ super(message);
+ }
+}
+
+async function request<T>(
+ method: string,
+ path: string,
+ body?: unknown,
+ options?: {
+ key?: string;
+ timeout?: number;
+ resource?: "browsers" | "profiles";
+ },
+): Promise<T> {
+ if (!config.HANGAR_URL)
+ throw new HangarError(
+ 503,
+ "Browser feature is not configured (HANGAR_URL is missing).",
+ );
+ let response: globalThis.Response;
+ try {
+ response = await fetch(
+ `${config.HANGAR_URL.replace(/\/$/, "")}/v1/${options?.resource ?? "browsers"}${path}`,
+ {
+ method,
+ headers: {
+ "Content-Type": "application/json",
+ ...(options?.key ? { "Idempotency-Key": options.key } : {}),
+ },
+ body: body === undefined ? undefined : JSON.stringify(body),
+ signal: AbortSignal.timeout(options?.timeout ?? 40_000),
+ },
+ );
+ } catch {
+ throw new HangarError(502, "Hangar is unavailable.");
+ }
+ // Do not expose upstream bodies: creation failures can contain capability URLs.
+ if (!response.ok) {
+ await response.body?.cancel().catch(() => {});
+ throw new HangarError(
+ response.status,
+ response.status === 409
+ ? "Browser operation conflicts with the current session or profile state."
+ : "Hangar request failed.",
+ );
+ }
+ try {
+ return (await response.json()) as T;
+ } catch {
+ throw new HangarError(502, "Invalid Hangar response.");
+ }
+}
+
+export const getHangarBrowser = (id: string, wait = 0, timeout?: number) =>
+ request<HangarBrowser>(
+ "GET",
+ `/${encodeURIComponent(id)}${wait ? `?wait=${wait}` : ""}`,
+ undefined,
+ { timeout },
+ );
+export const stopHangarBrowser = (id: string) =>
+ request<HangarBrowser>("POST", `/${encodeURIComponent(id)}/stop`);
+
+export async function createHangarBrowser(
+ key: string,
+ teamId: string,
+ options: {
+ ttl: number;
+ activityTtl: number;
+ streamWebView: boolean;
+ recordSession: boolean;
+ profile?: { name: string; saveChanges: boolean };
+ },
+): Promise<HangarCreated> {
+ const body = {
+ owner: teamId,
+ max_lifetime_seconds: options.ttl,
+ idle_timeout_seconds: options.activityTtl,
+ live_view: {
+ enabled: options.streamWebView,
+ interactive: options.streamWebView,
+ },
+ recording: { enabled: options.recordSession },
+ execution: { enabled: true },
+ ...(options.profile
+ ? {
+ profile: {
+ name: options.profile.name,
+ save_changes: options.profile.saveChanges,
+ },
+ }
+ : {}),
+ };
+ let created: HangarCreated | undefined;
+ for (let attempt = 0; attempt < 3; attempt++) {
+ try {
+ created = await request<HangarCreated>("POST", "?wait=30", body, { key });
+ break;
+ } catch (error) {
+ if (
+ !(error instanceof HangarError) ||
+ error.status < 500 ||
+ attempt === 2
+ )
+ throw error;
+ }
+ }
+ if (!created?.id)
+ throw new HangarError(502, "Invalid Hangar creation response.");
+ try {
+ if (!created.cdp_url)
+ throw new HangarError(502, "Invalid Hangar creation response.");
+ let browser: HangarBrowser = created;
+ const deadline = Date.now() + 300_000;
+ while (browser.status === "starting" && Date.now() < deadline)
+ browser = await getHangarBrowser(created.id, 30);
+ if (browser.status !== "running")
+ throw new HangarError(502, "Browser failed to become ready.");
+ return { ...created, ...browser };
+ } catch (error) {
+ await stopHangarBrowser(created.id).catch(() => {});
+ throw error;
+ }
+}
+
+export async function executeHangarBrowser(
+ id: string,
+ params: {
+ code: string;
+ language: string;
+ timeout: number;
+ },
+): Promise<BrowserExecutionResult> {
+ const { code, language, timeout } = params;
+ const result = await request<
+ Omit<BrowserExecutionResult, "exitCode"> & { exit_code: number }
+ >(
+ "POST",
+ `/${encodeURIComponent(id)}/execute`,
+ { code, language, timeout },
+ { timeout: (timeout + 20) * 1000 },
+ );
+ const { exit_code, ...output } = result;
+ return { ...output, exitCode: exit_code };
+}
+
+export async function deleteHangarProfile(owner: string, name: string) {
+ const result = await request<{ deleted_at?: unknown }>(
+ "DELETE",
+ `/${encodeURIComponent(name)}?owner=${encodeURIComponent(owner)}`,
+ undefined,
+ { resource: "profiles" },
+ );
+ // Compared against Hangar save timestamps during reconciliation.
+ const deletedAt =
+ typeof result.deleted_at === "number"
+ ? new Date(result.deleted_at * 1000)
+ : new Date(NaN);
+ if (Number.isNaN(deletedAt.getTime()))
+ throw new HangarError(502, "Invalid Hangar profile deletion response.");
+ return { deletedAt: deletedAt.toISOString() };
+}
+
+/** Keep the replay API's HLS response while letting players fetch segments from Hangar. */
+export async function getHangarRecording(playlistUrl: string) {
+ const unavailable = () =>
+ new HangarError(502, "Failed to fetch session replay.");
+ let response: globalThis.Response;
+ let base: URL;
+ try {
+ base = new URL(playlistUrl);
+ if (!["http:", "https:"].includes(base.protocol)) throw unavailable();
+ response = await fetch(base.href, {
+ redirect: "error",
+ signal: AbortSignal.timeout(15_000),
+ });
+ } catch {
+ throw unavailable();
+ }
+ if (!response.ok) await response.body?.cancel().catch(() => {});
+ if ([401, 404, 409, 410].includes(response.status))
+ throw new HangarError(404, "Replay not found.");
+ if (!response.ok || !response.body) throw unavailable();
+ const reader = response.body.getReader();
+ const chunks: Uint8Array[] = [];
+ let size = 0;
+ try {
+ while (true) {
+ const { done, value } = await reader.read();
+ if (done) break;
+ size += value.byteLength;
+ if (size > 8 * 1024 * 1024) throw unavailable();
+ chunks.push(value);
+ }
+ } catch {
+ throw unavailable();
+ } finally {
+ await reader.cancel().catch(() => {});
+ }
+ const lines = Buffer.concat(chunks).toString("utf8").trim().split(/\r?\n/);
+ if (lines[0] !== "#EXTM3U") throw unavailable();
+ let durationMs = 0;
+ let pendingDuration: number | undefined;
+ let segments = 0;
+ const playlist =
+ lines
+ .map(line => {
+ if (line.startsWith("#EXTINF:")) {
+ const match = /^#EXTINF:(\d+(?:\.\d+)?),/.exec(line);
+ if (!match || pendingDuration !== undefined) throw unavailable();
+ pendingDuration = Number(match[1]) * 1000;
+ if (!Number.isFinite(pendingDuration) || pendingDuration <= 0)
+ throw unavailable();
+ } else if (line && !line.startsWith("#")) {
+ if (pendingDuration === undefined) throw unavailable();
+ let segment: URL;
+ try {
+ segment = new URL(line, base);
+ } catch {
+ throw unavailable();
+ }
+ if (segment.origin !== base.origin) throw unavailable();
+ durationMs += pendingDuration;
+ pendingDuration = undefined;
+ segments++;
+ return segment.href;
+ }
+ return line;
+ })
+ .join("\n") + "\n";
+ if (!segments || pendingDuration !== undefined) throw unavailable();
+ return { playlist, durationMs: Math.round(durationMs) };
+}
diff --git a/apps/api/src/lib/keyless.ts b/apps/api/src/lib/keyless.ts
index 7b6cd9d0a..04a91f0ba 100644
--- a/apps/api/src/lib/keyless.ts
+++ b/apps/api/src/lib/keyless.ts
@@ -319,6 +319,56 @@ return next
return Number(total);
}
+/** Absolute browser reservations, including prompt upgrades, with atomic receipts. */
+export async function updateKeylessBrowserCredits(
+ teamId: string,
+ sessionId: string,
+ credits: number,
+ finalize = false,
+): Promise<boolean> {
+ const ip = keylessIpFromTeamId(teamId);
+ if (!ip) return true;
+ const result = await redisRateLimitClient.eval(
+ `
+ local now = tonumber(ARGV[1])
+ local target = tonumber(ARGV[2])
+ local final = ARGV[3] == '1'
+ local reserved = tonumber(redis.call('HGET', KEYS[2], 'credits') or '0')
+ local deadline = tonumber(redis.call('HGET', KEYS[2], 'deadline') or '0')
+ if redis.call('HGET', KEYS[2], 'final') == '1' then
+ if final then return 1 else return 0 end
+ end
+ -- An expired budget cannot be refunded into a different day's allowance.
+ if deadline > 0 and deadline <= now then
+ if final then return 1 end
+ reserved = 0
+ deadline = 0
+ end
+ if final and deadline == 0 then return 1 end
+ local delta = target - reserved
+ if not final and delta <= 0 then return 1 end
+ local current = tonumber(redis.call('GET', KEYS[1]) or '0')
+ if not final and current + delta > tonumber(ARGV[4]) then return 0 end
+ local ttl = redis.call('PTTL', KEYS[1])
+ if ttl <= 0 then ttl = 86400000 end
+ if deadline == 0 then deadline = now + ttl end
+ redis.call('SET', KEYS[1], math.max(0, current + delta), 'PX', ttl)
+ redis.call('HSET', KEYS[2], 'credits', target, 'deadline', deadline, 'final', ARGV[3])
+ redis.call('EXPIRE', KEYS[2], 172800)
+ return 1
+ `,
+ 2,
+ creditsKey(ip),
+ `keyless_browser:${sessionId}`,
+ Date.now(),
+ Math.ceil(credits),
+ finalize ? "1" : "0",
+ KEYLESS_CREDITS_PER_DAY ?? 0,
+ );
+ if (result !== 1 && !finalize) keylessCreditBlocksTotal.inc();
+ return result === 1;
+}
+
/**
* Read-only check of whether an IP could currently use the keyless tier (no
* consumption). Used by the hosted MCP before a keyless tool call so an
diff --git a/apps/api/src/lib/scrape-interact/browser-agent.ts b/apps/api/src/lib/scrape-interact/browser-agent.ts
index d75cd63c6..d32202bdd 100644
--- a/apps/api/src/lib/scrape-interact/browser-agent.ts
+++ b/apps/api/src/lib/scrape-interact/browser-agent.ts
@@ -4,10 +4,7 @@ import path from "path";
import { tool, stepCountIs } from "ai";
import { logger as _logger } from "../logger";
import { getModel } from "../generic-ai";
-import {
- browserServiceRequest,
- BrowserServiceExecResponse,
-} from "./browser-service-client";
+import { executeHangarBrowser, BrowserExecutionResult } from "../hangar";
import { config } from "../../config";
import {
generateText,
@@ -143,7 +140,7 @@ Your final text response is what the user sees. It MUST be a clean, human-readab
// Helpers
// ---------------------------------------------------------------------------
-export interface AgentResult extends BrowserServiceExecResponse {
+export interface AgentResult extends BrowserExecutionResult {
output: string;
}
@@ -151,13 +148,12 @@ 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 },
- );
+): Promise<BrowserExecutionResult> {
+ return executeHangarBrowser(browserId, {
+ code,
+ language: "bash",
+ timeout,
+ });
}
async function getCurrentUrl(browserId: string): Promise<string> {
@@ -166,7 +162,6 @@ async function getCurrentUrl(browserId: string): Promise<string> {
browserId,
"agent-browser get url",
SNAPSHOT_TIMEOUT,
- "agent_get_url",
);
return (result.stdout || result.result || "").trim();
} catch {
@@ -180,7 +175,6 @@ async function takeSnapshot(browserId: string): Promise<string> {
browserId,
"agent-browser snapshot -i",
SNAPSHOT_TIMEOUT,
- "agent_snapshot",
);
return (result.stdout || result.result || "").slice(0, SNAPSHOT_MAX_CHARS);
} catch {
@@ -188,28 +182,40 @@ async function takeSnapshot(browserId: string): Promise<string> {
}
}
-/**
- * Keep a single foregrounded content tab, closing agent-browser's stray
- * about:blank tab (it safely falls back to the surviving tab).
- */
-async function syncTabs(browserId: string): Promise<void> {
- 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 {}
+/** Align the CLI with the replay's page without discarding the user's other tabs. */
+export async function selectBrowserAgentTab(browserId: string): Promise<void> {
+ const target = await executeHangarBrowser(browserId, {
+ code: `await (async () => {
+ for (const candidate of [page, ...context.pages().filter(p => p !== page)]) {
+ if (await candidate.evaluate(() => document.visibilityState === 'visible').catch(() => false)) {
+ page = candidate;
+ break;
+ }
+ }
+ await page.bringToFront();
+ const cdp = await context.newCDPSession(page);
+ try {
+ const { targetInfo } = await cdp.send('Target.getTargetInfo');
+ console.log(targetInfo.targetId);
+ } finally { await cdp.detach(); }
+ })()`,
+ language: "node",
+ timeout: 10,
+ });
+ const targetId = (target.stdout || target.result || "").trim();
+ if (
+ target.exitCode !== 0 ||
+ target.killed ||
+ !/^[a-f0-9]{32}$/i.test(targetId)
+ )
+ throw new Error("Could not identify the replay browser tab.");
+ const selected = await execInBrowser(
+ browserId,
+ `agent-browser tab ${targetId}`,
+ 10,
+ );
+ if (selected.exitCode !== 0 || selected.killed)
+ throw new Error("Could not select the replay browser tab.");
}
// ---------------------------------------------------------------------------
@@ -243,10 +249,7 @@ export async function executePromptViaBrowserAgent(
debugLog.add(`Prompt: ${prompt}\n`);
logger.info("Agent debug log", { path: debugLog.getPath() });
- // Prime agent-browser and consolidate tabs first: its first command of a
- // session spawns an about:blank tab that would otherwise get snapshotted.
- await getCurrentUrl(browserId);
- await syncTabs(browserId);
+ await selectBrowserAgentTab(browserId);
const [initialSnapshot, initialUrl] = await Promise.all([
takeSnapshot(browserId),
@@ -284,16 +287,10 @@ export async function executePromptViaBrowserAgent(
}
try {
- const result = await execInBrowser(
- browserId,
- code,
- stepTimeout,
- "agent_action",
- );
+ const result = await execInBrowser(browserId, code, stepTimeout);
const output = (result.stdout || result.result || "").trim();
- // Ensure only one tab exists and it's in the foreground for live view
- await syncTabs(browserId);
+ await selectBrowserAgentTab(browserId);
const elapsed = Date.now() - start;
@@ -448,16 +445,16 @@ export async function executeCodeViaBrowserSession(
origin?: string;
},
trace?: BrowserAgentTraceContext,
-): Promise<BrowserServiceExecResponse> {
+): Promise<BrowserExecutionResult> {
// Arg must be named so langsmith's traceable sees the exec params as the
// run's `inputs`; a zero-arg closure would record `{}` and strip the code,
// language, timeout, and origin from every trace.
const run = async (execParams: typeof params) =>
- browserServiceRequest<BrowserServiceExecResponse>(
- "POST",
- `/browsers/${browserId}/exec`,
- execParams,
- );
+ executeHangarBrowser(browserId, {
+ code: execParams.code,
+ language: execParams.language,
+ timeout: execParams.timeout,
+ });
if (!trace) return run(params);
diff --git a/apps/api/src/lib/scrape-interact/browser-service-client.ts b/apps/api/src/lib/scrape-interact/browser-service-client.ts
deleted file mode 100644
index fa3b1815e..000000000
--- a/apps/api/src/lib/scrape-interact/browser-service-client.ts
+++ /dev/null
@@ -1,113 +0,0 @@
-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;
- cleanupQueued: boolean;
-}
-
-// ---------------------------------------------------------------------------
-// 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>;
-}
-
-/**
- * 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/lib/scrape-interact/scrape-replay.ts b/apps/api/src/lib/scrape-interact/scrape-replay.ts
index 3d6a3ff6e..6f7fa4b3c 100644
--- a/apps/api/src/lib/scrape-interact/scrape-replay.ts
+++ b/apps/api/src/lib/scrape-interact/scrape-replay.ts
@@ -346,7 +346,7 @@ for (let i = 0; i < replay.actions.length; i += 1) {
break;
case "executeJavascript": {
const wrapped = \`(async () => { \${action.script} })()\`;
- await page.evaluate(script => (0, eval)(script), wrapped);
+ await page.evaluate(script => (0, eval)(script), wrapped, undefined, false);
break;
}
case "screenshot":
diff --git a/apps/api/src/routes/v2.ts b/apps/api/src/routes/v2.ts
index d25751954..63c6f6dca 100644
--- a/apps/api/src/routes/v2.ts
+++ b/apps/api/src/routes/v2.ts
@@ -64,17 +64,15 @@ import { agentSnapshotController } from "../controllers/v2/agent-snapshot";
import { agentSkillController } from "../controllers/v2/agent-skill";
import { agentThreadController } from "../controllers/v2/agent-thread";
import {
+ browserProfileDeleteController,
browserCreateController,
browserExecuteController,
browserDeleteController,
browserListController,
- browserProfileDeleteController,
- browserWebhookDestroyedController,
-} from "../controllers/v2/browser";
-import {
browserReplayController,
browserReplayPageController,
-} from "../controllers/v2/browser-replay";
+ browserStatusController,
+} from "../controllers/v2/browser";
import { activityController } from "../controllers/v1/activity";
import {
getTeamThreatProtectionController,
@@ -672,9 +670,10 @@ v2Router.delete(
wrap(browserDeleteController),
);
-v2Router.post(
- "/browser/webhook/destroyed",
- wrap(browserWebhookDestroyedController),
+v2Router.get(
+ ["/browser/:sessionId", "/interact/:sessionId"],
+ authMiddleware(RateLimiterMode.BrowserExecute),
+ wrap(browserStatusController),
);
// Support agent proxy β€” forwards to the support-agent service.
diff --git a/apps/api/src/scraper/scrapeURL/engines/fire-engine/index.ts b/apps/api/src/scraper/scrapeURL/engines/fire-engine/index.ts
index 3a2fe1cb7..4c533e830 100644
--- a/apps/api/src/scraper/scrapeURL/engines/fire-engine/index.ts
+++ b/apps/api/src/scraper/scrapeURL/engines/fire-engine/index.ts
@@ -58,7 +58,6 @@ 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 { browserProfileStorageId } from "../../../../lib/browser-profiles";
/** 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;
@@ -489,12 +488,10 @@ export async function scrapeURLWithFireEngineChromeCDP(
: {}),
...(shouldAllowMedia ? { blockMedia: false } : {}),
...(forceNonRender ? { forceNonRender: true } : {}),
- persistentStorage: meta.options.profile
+ profile: meta.options.profile
? {
- uniqueId: browserProfileStorageId(
- meta.internalOptions.teamId,
- meta.options.profile.name,
- ),
+ owner: meta.internalOptions.teamId,
+ name: meta.options.profile.name,
}
: undefined,
...safeModeParams(meta.internalOptions.safeMode),
@@ -507,7 +504,7 @@ export async function scrapeURLWithFireEngineChromeCDP(
request.mobileProxy = false;
}
if (sm?.disableAuthentication) {
- request.persistentStorage = undefined;
+ request.profile = undefined;
request.headers = stripCredentialHeaders(request.headers);
}
diff --git a/apps/api/src/scraper/scrapeURL/engines/fire-engine/scrape.ts b/apps/api/src/scraper/scrapeURL/engines/fire-engine/scrape.ts
index f465de8a3..d628a23c5 100644
--- a/apps/api/src/scraper/scrapeURL/engines/fire-engine/scrape.ts
+++ b/apps/api/src/scraper/scrapeURL/engines/fire-engine/scrape.ts
@@ -98,7 +98,7 @@ export type FireEngineScrapeRequestChromeCDP = {
forceNonRender?: boolean;
mobile?: boolean;
disableSmartWaitCache?: boolean;
- persistentStorage?: { uniqueId: string };
+ profile?: { owner: string; name: string };
};
export type FireEngineScrapeRequestTLSClient = {
diff --git a/apps/api/src/scraper/scrapeURL/engines/index.ts b/apps/api/src/scraper/scrapeURL/engines/index.ts
index c44ef7f77..d2207668b 100644
--- a/apps/api/src/scraper/scrapeURL/engines/index.ts
+++ b/apps/api/src/scraper/scrapeURL/engines/index.ts
@@ -932,7 +932,11 @@ export async function buildFallbackList(meta: Meta): Promise<
}
}
- if (isXTwitterUrl(meta.url) && _engines.includes("x-twitter")) {
+ if (
+ !meta.options.profile &&
+ isXTwitterUrl(meta.url) &&
+ _engines.includes("x-twitter")
+ ) {
_engines.length = 0;
_engines.push("x-twitter");
} else if (!isXTwitterUrl(meta.url)) {
@@ -961,6 +965,17 @@ export async function buildFallbackList(meta: Meta): Promise<
: _engines;
for (const engine of currentEngines) {
+ // A profile must never fall back to fetching anonymous content. File parsers
+ // may consume bytes already fetched by the authenticated browser.
+ if (
+ meta.options.profile &&
+ !engine.includes("chrome-cdp") &&
+ !(engine === "pdf" && meta.pdfPrefetch) &&
+ !(engine === "document" && meta.documentPrefetch) &&
+ !(engine === "image" && meta.imagePrefetch)
+ )
+ continue;
+
const supportedFlags = new Set([
...Object.entries(engineOptions[engine].features)
.filter(
diff --git a/apps/api/src/services/indexing/index-worker.ts b/apps/api/src/services/indexing/index-worker.ts
index 757a35805..56858d2f9 100644
--- a/apps/api/src/services/indexing/index-worker.ts
+++ b/apps/api/src/services/indexing/index-worker.ts
@@ -27,6 +27,7 @@ import { getSearchIndexClient } from "../../lib/search-index-client";
// Search indexing is now handled by the separate search service
// import { processSearchIndexJobs } from "../../lib/search-index/queue";
import { processWebhookInsertJobs } from "../webhook";
+import { reconcileBrowserSessions } from "../../lib/browser-lifecycle";
import { processBrowserSessionActivityJobs } from "../../lib/browser-session-activity";
import {
scrapeOptions as scrapeOptionsSchema,
@@ -740,6 +741,10 @@ const BROWSER_ACTIVITY_INSERT_INTERVAL = 10000;
await processWebhookInsertJobs();
}, WEBHOOK_INSERT_INTERVAL);
+ const browserReconcileInterval = setInterval(() => {
+ if (!isShuttingDown) void reconcileBrowserSessions();
+ }, 15_000);
+
const browserActivityInterval = setInterval(async () => {
if (isShuttingDown) return;
await processBrowserSessionActivityJobs();
@@ -805,6 +810,7 @@ const BROWSER_ACTIVITY_INSERT_INTERVAL = 10000;
clearInterval(indexInserterInterval);
clearInterval(webhookInserterInterval);
clearInterval(browserActivityInterval);
+ clearInterval(browserReconcileInterval);
clearInterval(omceInserterInterval);
logger.info("All workers shut down, exiting process");
})();
diff --git a/apps/api/src/services/worker/nuq-fdb/slots.ts b/apps/api/src/services/worker/nuq-fdb/slots.ts
index 4e7f3c20e..7424919ca 100644
--- a/apps/api/src/services/worker/nuq-fdb/slots.ts
+++ b/apps/api/src/services/worker/nuq-fdb/slots.ts
@@ -8,14 +8,14 @@ import {
timeBucket,
F_GATED,
normalizeOwnerId,
+ decodeI64,
} from "./keyspace";
import { bumpTeamActive, newTxContext, releaseSlotsAndPromote } from "./ops";
// External slots: capacity consumed by things that are not queue jobs (sync
-// scrapes via the team semaphore, browser sessions). They unconditionally bump
-// the team active counter -- possibly past the limit, matching the old Redis
-// behavior where sync holders were mirrored into the same ZSET -- and hand
-// their slot through the normal promotion chain on release.
+// scrapes via the team semaphore, browser sessions). Admission can enforce a
+// limit or mirror a holder admitted elsewhere. Released slots go through the
+// normal promotion chain.
type ExternalSlotRecord = {
e: number; // expiry ms
@@ -43,25 +43,30 @@ export class NuqFdbExternalSlots {
};
}
- // Acquires (or renews) an external slot. Unconditional: never blocks on the
- // team limit; the caller's own gate (Lua semaphore, session limits) decides
- // admission. Re-acquiring an existing holder just extends its expiry.
+ // With a limit, reject new holders when the team is full. Without one, the
+ // caller controls admission. Existing holders only renew their expiry.
public async acquire(
teamId: string,
holderId: string,
ttlMs: number,
- ): Promise<void> {
+ limit?: number,
+ ): Promise<boolean> {
const owner = normalizeOwnerId(teamId);
- if (owner === null) return;
+ if (owner === null) return false;
const now = Date.now();
const exp = now + ttlMs;
- await this.db.doTn(async tn => {
+ return this.db.doTn(async tn => {
const existing = decodeJson<ExternalSlotRecord>(
await tn.get(this.key(owner, holderId)),
);
if (existing) {
tn.clear(this.expiryKey(timeBucket(holderId), existing.e, holderId));
} else {
+ if (
+ limit !== undefined &&
+ decodeI64(await tn.get(this.ks.teamActive(owner))) >= limit
+ )
+ return false;
bumpTeamActive(tn, this.ks, owner, 1);
}
tn.set(
@@ -72,6 +77,7 @@ export class NuqFdbExternalSlots {
this.expiryKey(timeBucket(holderId), exp, holderId),
encodeJson({ t: owner }),
);
+ return true;
});
}
diff --git a/apps/api/src/services/worker/nuq-router.ts b/apps/api/src/services/worker/nuq-router.ts
index 07201e6c4..b296799d9 100644
--- a/apps/api/src/services/worker/nuq-router.ts
+++ b/apps/api/src/services/worker/nuq-router.ts
@@ -11,8 +11,8 @@ import { getApiKeyConcurrencyLimit } from "../../lib/api-key-concurrency";
import {
getTeamQueueLimit,
getConcurrencyLimitActiveJobsCount,
- pushConcurrencyLimitActiveJob,
removeConcurrencyLimitActiveJob,
+ reserveConcurrencyLimitSlot,
} from "../../lib/concurrency-redis";
import {
NuQJob,
@@ -193,23 +193,21 @@ function tagFdbJob<T extends object>(job: T): T & { backend: "fdb" } {
// mid-hold) self-heal: Redis entries expire by score, FDB external slots are
// reaped by the sweeper.
-export async function mirrorExternalSlotAcquire(
+export async function reserveExternalSlot(
teamId: string,
holderId: string,
ttlMs: number,
-): Promise<void> {
+ limit: number,
+): Promise<boolean> {
if (await isFdbTeam(teamId)) {
- try {
- await optionalFdb(() =>
- externalSlotsFdb.acquire(teamId, holderId, ttlMs),
- );
- return;
- } catch (error) {
- if (fdbForced()) throw error;
- logFdbFallback(_logger, "mirrorExternalSlotAcquire", error);
- }
+ const legacyActive = await getConcurrencyLimitActiveJobsCount(teamId);
+ // A timed-out write may have committed. Fail closed; the caller releases
+ // this holder from both ledgers instead of admitting it a second time.
+ return optionalFdb(() =>
+ externalSlotsFdb.acquire(teamId, holderId, ttlMs, limit - legacyActive),
+ );
}
- await pushConcurrencyLimitActiveJob(teamId, holderId, ttlMs);
+ return reserveConcurrencyLimitSlot(teamId, holderId, ttlMs, limit);
}
export async function mirrorExternalSlotRelease(
diff --git a/apps/js-sdk/firecrawl/src/v2/types.ts b/apps/js-sdk/firecrawl/src/v2/types.ts
index d10800421..fc60719ce 100644
--- a/apps/js-sdk/firecrawl/src/v2/types.ts
+++ b/apps/js-sdk/firecrawl/src/v2/types.ts
@@ -1961,11 +1961,13 @@ export interface BrowserExecuteResponse {
stderr?: string;
exitCode?: number;
killed?: boolean;
+ truncated?: boolean;
error?: string;
}
export interface BrowserDeleteResponse {
success: boolean;
+ status?: string;
sessionDurationMs?: number;
creditsBilled?: number;
error?: string;
diff --git a/apps/python-sdk/firecrawl/v2/types.py b/apps/python-sdk/firecrawl/v2/types.py
index 412c3fe21..46d8aef7d 100644
--- a/apps/python-sdk/firecrawl/v2/types.py
+++ b/apps/python-sdk/firecrawl/v2/types.py
@@ -1971,6 +1971,7 @@ class BrowserExecuteResponse(BaseModel):
stderr: Optional[str] = None
exit_code: Optional[int] = None
killed: Optional[bool] = None
+ truncated: Optional[bool] = None
error: Optional[str] = None
@@ -1978,6 +1979,7 @@ class BrowserDeleteResponse(BaseModel):
"""Response from deleting a browser session."""
success: bool
+ status: Optional[str] = None
session_duration_ms: Optional[int] = None
credits_billed: Optional[int] = None
error: Optional[str] = None