Skip to content

Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. 🔥

10.7 KB
Raw Blame
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 {
  KEYLESS_FREE_TIER_LIMIT_MESSAGE,
  keylessLimitPromptForTeam,
} from "../../lib/keyless";
import { z } from "zod";
import { config } from "../../config";
import { countryLocationSchema, RequestWithAuth } from "./types";
import { integrationSchema } from "../../utils/integration";
import { isAgentInteropSecretValid } from "../../lib/agent-interop";
import {
  getBrowserSession,
  listBrowserSessions,
  updateBrowserSessionActivity,
} from "../../lib/browser-sessions";
import {
  createBrowserSession,
  getBrowserZDR,
  BrowserSessionError,
  browserSessionLinks,
  stopBrowserSession,
  settleBrowserSession,
} from "../../lib/browser-lifecycle";
import {
  executeHangarBrowser,
  getHangarBrowser,
  getHangarRecording,
  HangarError,
} from "../../lib/hangar";
import { enqueueBrowserSessionActivity } from "../../lib/browser-session-activity";
import { browserProfileNameSchema } from "../../lib/browser-profiles";
import { withZeroDataRetention } from "../../lib/otel-tracer";
import { UsOnlyUnavailableError } from "../../scraper/scrapeURL/error";

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(false),
  zeroDataRetention: z.boolean().optional(),
  integration: integrationSchema.optional().transform(value => value || null),
  blockAds: z.boolean().default(true),
  profile: z
    .object({
      name: browserProfileNameSchema,
      saveChanges: z.boolean().default(true),
    })
    .optional(),
  location: countryLocationSchema.optional(),
  __agentInterop: z
    .object({
      auth: z.string(),
      requestId: z.string().uuid(),
      shouldBill: z.boolean(),
      hostedMcp: z.boolean().optional(),
    })
    .optional(),
});

const browserExecuteRequestSchema = z.object({
  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().int().min(1).max(300).default(30),
  origin: z.string().optional(),
});

export function browserError(
  res: Response,
  error: unknown,
  req?: RequestWithAuth<any, any, any>,
) {
  // Keyless browser budget exhaustion: give the caller its own signup link.
  if (
    req &&
    error instanceof BrowserSessionError &&
    error.status === 429 &&
    error.message === KEYLESS_FREE_TIER_LIMIT_MESSAGE
  ) {
    const prompt = keylessLimitPromptForTeam(req.auth.team_id, req);
    return res.status(429).json({
      success: false,
      error: prompt.error,
      signup_url: prompt.signup_url,
    });
  }
  if (error instanceof UsOnlyUnavailableError) {
    return res.status(403).json({
      success: false,
      code: error.code,
      error: error.message,
    });
  }
  const knownError =
    error instanceof BrowserSessionError || error instanceof HangarError;
  return res.status(knownError ? error.status : 502).json({
    success: false,
    ...(error instanceof BrowserSessionError && error.code
      ? { code: error.code }
      : {}),
    error: knownError ? error.message : "Browser operation failed.",
  });
}

export async function browserCreateController(
  req: RequestWithAuth<{}, any, any>,
  res: Response,
) {
  const body = browserCreateRequestSchema.parse(req.body);
  if (getSafeMode(req.acuc?.flags)) {
    return res
      .status(403)
      .json({ success: false, error: SAFE_MODE_BROWSER_UNSUPPORTED_MESSAGE });
  }
  req.body = body;
  if (
    body.__agentInterop &&
    (!config.AGENT_INTEROP_SECRET ||
      !isAgentInteropSecretValid(body.__agentInterop.auth))
  ) {
    return res
      .status(403)
      .json({ success: false, error: "Invalid agent interop." });
  }
  try {
    const { session, expiresAt } = await createBrowserSession(req, {
      ...body,
      shouldBill: body.__agentInterop?.shouldBill,
      requestId: body.__agentInterop?.requestId,
    });
    return res.json({
      success: true,
      id: session.id,
      ...browserSessionLinks(session),
      expiresAt,
    });
  } catch (error) {
    return browserError(res, error, req);
  }
}

async function resolveBrowserSession(
  req: RequestWithAuth<{ sessionId: string }, any, any>,
  res: Response,
) {
  const session = await getBrowserSession(req.params.sessionId);
  if (!session) {
    res
      .status(404)
      .json({ success: false, error: "Browser session not found." });
    return;
  }
  if (session.team_id !== req.auth.team_id) {
    res.status(403).json({ success: false, error: "Forbidden." });
    return;
  }
  return session;
}

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 });
  }
  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 {
    const zeroDataRetention = getBrowserZDR(req, session);
    return await withZeroDataRetention(zeroDataRetention, async () => {
      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, req);
  }
}

// DELETE /v2/browser/profiles/:name
// Deletes a persistent profile's saved state and its listing. Deleting a
// profile that has no saved state succeeds.
export async function browserProfileDeleteController(
  req: RequestWithAuth<{ name: string }, { success: boolean; error?: string }>,
  res: Response<{ success: boolean; error?: string }>,
) {
  if (getSafeMode(req.acuc?.flags)) {
    return res
      .status(403)
      .json({ success: false, error: SAFE_MODE_BROWSER_UNSUPPORTED_MESSAGE });
  }
  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 UTF-8 bytes.",
    });
  }
  try {
    const { deletedAt } = await deleteHangarProfile(
      req.auth.team_id,
      name.data,
    );
    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.",
      });
    }
    return browserError(res, error, req);
  }
}

export async function browserDeleteController(
  req: RequestWithAuth<{ sessionId: string }, any, any>,
  res: Response,
) {
  const session = await resolveBrowserSession(req, res);
  if (!session) return;
  try {
    return res.json(await stopBrowserSession(session));
  } catch (error) {
    return browserError(res, error, req);
  }
}

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,
      id: session.id,
      status: browser.status,
      ...browserSessionLinks(session),
      ...billing,
      error: browser.error ?? undefined,
    });
  } catch (error) {
    return browserError(res, error, req);
  }
}

export async function browserListController(
  req: RequestWithAuth<{}, any, any>,
  res: Response,
) {
  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: sessions.map(session => ({
      id: session.id,
      status: session.status,
      ...browserSessionLinks(session),
      streamWebView: session.stream_web_view,
      createdAt: session.created_at,
      lastActivity: session.updated_at,
    })),
  });
}

export async function browserReplayController(
  req: RequestWithAuth<{ sessionId: string }, any, any>,
  res: Response,
) {
  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,
    });
  } catch (error) {
    return browserError(res, error, req);
  }
}

export async function browserReplayPageController(
  req: RequestWithAuth<{ sessionId: string; pageId: string }, any, any>,
  res: Response,
) {
  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, req);
  }
}