Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. π₯
TypeScript aiai-agentsai-crawlerai-scrapingai-searchcrawlerdata-extractionhtml-to-markdownllmmarkdownscraperscrapingweb-crawlerweb-dataweb-data-extractionweb-scraperweb-scrapingweb-searchwebscraping
feat: migrate browser and interact APIs to Hangar (#4757)
tomsideguidee26b2d80c795
diff --git a/.github/workflows/test-server.yml b/.github/workflows/test-server.ymlindex 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 testsruns-on: blacksmith-4vcpu-ubuntu-2404+ services:+ redis:+ image: redis+ ports:+ - 6379:6379env:FDB_VERSION: 7.3.63steps:diff --git a/.gitignore b/.gitignoreindex 3c9c83018..425e61b4a 100644--- a/.gitignore+++ b/.gitignore@@ -65,3 +65,5 @@ apps/api/src/lib/scrape-interact/*.md# stray test runner logsvitest.out++tmp/\ No newline at end of filediff --git a/apps/api/requests/v2/browser.requests.http b/apps/api/requests/v2/browser.requests.httpindex 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/jsonGET {{baseUrl}}/v2/interact/{{sessionId}}/replay HTTP/1.1Authorization: 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.1Authorization: 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 recordingPOST {{baseUrl}}/v2/browser HTTP/1.1Authorization: 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.1Authorization: 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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 = 11expect(- 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.tsindex 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.tsindex 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.tsdeleted file mode 100644index 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.tsindex 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 Supabasetry {- 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.tsindex 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.tsindex 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 = zexport 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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 idworkspace_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 URLstream_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.tsindex 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.tsnew file mode 100644index 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.tsindex 7b6cd9d0a..04a91f0ba 100644--- a/apps/api/src/lib/keyless.ts+++ b/apps/api/src/lib/keyless.ts@@ -319,6 +319,56 @@ return nextreturn 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 andiff --git a/apps/api/src/lib/scrape-interact/browser-agent.ts b/apps/api/src/lib/scrape-interact/browser-agent.tsindex 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.tsdeleted file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.pyindex 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] = Noneexit_code: Optional[int] = Nonekilled: Optional[bool] = None+ truncated: Optional[bool] = Noneerror: Optional[str] = None@@ -1978,6 +1979,7 @@ class BrowserDeleteResponse(BaseModel):"""Response from deleting a browser session."""success: bool+ status: Optional[str] = Nonesession_duration_ms: Optional[int] = Nonecredits_billed: Optional[int] = Noneerror: Optional[str] = None