@agenticmail/enterprise 0.5.77 → 0.5.79

package/src/browser/routes/dispatcher.ts

@@ -0,0 +1,126 @@
+import { escapeRegExp } from "../enterprise-compat.js";
+import type { BrowserRouteContext } from "../server-context.js";
+import { registerBrowserRoutes } from "./index.js";
+import type { BrowserRequest, BrowserResponse, BrowserRouteRegistrar } from "./types.js";
+
+type BrowserDispatchRequest = {
+  method: "GET" | "POST" | "DELETE";
+  path: string;
+  query?: Record<string, unknown>;
+  body?: unknown;
+  signal?: AbortSignal;
+};
+
+type BrowserDispatchResponse = {
+  status: number;
+  body: unknown;
+};
+
+type RouteEntry = {
+  method: BrowserDispatchRequest["method"];
+  path: string;
+  regex: RegExp;
+  paramNames: string[];
+  handler: (req: BrowserRequest, res: BrowserResponse) => void | Promise<void>;
+};
+
+function compileRoute(path: string): { regex: RegExp; paramNames: string[] } {
+  const paramNames: string[] = [];
+  const parts = path.split("/").map((part) => {
+    if (part.startsWith(":")) {
+      const name = part.slice(1);
+      paramNames.push(name);
+      return "([^/]+)";
+    }
+    return escapeRegExp(part);
+  });
+  return { regex: new RegExp(`^${parts.join("/")}$`), paramNames };
+}
+
+function createRegistry() {
+  const routes: RouteEntry[] = [];
+  const register =
+    (method: RouteEntry["method"]) => (path: string, handler: RouteEntry["handler"]) => {
+      const { regex, paramNames } = compileRoute(path);
+      routes.push({ method, path, regex, paramNames, handler });
+    };
+  const router: BrowserRouteRegistrar = {
+    get: register("GET"),
+    post: register("POST"),
+    delete: register("DELETE"),
+  };
+  return { routes, router };
+}
+
+function normalizePath(path: string) {
+  if (!path) {
+    return "/";
+  }
+  return path.startsWith("/") ? path : `/${path}`;
+}
+
+export function createBrowserRouteDispatcher(ctx: BrowserRouteContext) {
+  const registry = createRegistry();
+  registerBrowserRoutes(registry.router, ctx);
+
+  return {
+    dispatch: async (req: BrowserDispatchRequest): Promise<BrowserDispatchResponse> => {
+      const method = req.method;
+      const path = normalizePath(req.path);
+      const query = req.query ?? {};
+      const body = req.body;
+      const signal = req.signal;
+
+      const match = registry.routes.find((route) => {
+        if (route.method !== method) {
+          return false;
+        }
+        return route.regex.test(path);
+      });
+      if (!match) {
+        return { status: 404, body: { error: "Not Found" } };
+      }
+
+      const exec = match.regex.exec(path);
+      const params: Record<string, string> = {};
+      if (exec) {
+        for (const [idx, name] of match.paramNames.entries()) {
+          const value = exec[idx + 1];
+          if (typeof value === "string") {
+            params[name] = decodeURIComponent(value);
+          }
+        }
+      }
+
+      let status = 200;
+      let payload: unknown = undefined;
+      const res: BrowserResponse = {
+        status(code) {
+          status = code;
+          return res;
+        },
+        json(bodyValue) {
+          payload = bodyValue;
+        },
+      };
+
+      try {
+        await match.handler(
+          {
+            params,
+            query,
+            body,
+            signal,
+          },
+          res,
+        );
+      } catch (err) {
+        return { status: 500, body: { error: String(err) } };
+      }
+
+      return { status, body: payload };
+    },
+  };
+}
+
+export type { BrowserDispatchRequest, BrowserDispatchResponse };

package/src/browser/routes/index.ts

@@ -0,0 +1,11 @@
+import type { BrowserRouteContext } from "../server-context.js";
+import { registerBrowserAgentRoutes } from "./agent.js";
+import { registerBrowserBasicRoutes } from "./basic.js";
+import { registerBrowserTabRoutes } from "./tabs.js";
+import type { BrowserRouteRegistrar } from "./types.js";
+
+export function registerBrowserRoutes(app: BrowserRouteRegistrar, ctx: BrowserRouteContext) {
+  registerBrowserBasicRoutes(app, ctx);
+  registerBrowserTabRoutes(app, ctx);
+  registerBrowserAgentRoutes(app, ctx);
+}

package/src/browser/routes/path-output.ts

@@ -0,0 +1 @@
+export * from "../paths.js";

package/src/browser/routes/tabs.ts

@@ -0,0 +1,217 @@
+import type { BrowserRouteContext, ProfileContext } from "../server-context.js";
+import type { BrowserRequest, BrowserResponse, BrowserRouteRegistrar } from "./types.js";
+import { getProfileContext, jsonError, toNumber, toStringOrEmpty } from "./utils.js";
+
+function resolveTabsProfileContext(
+  req: BrowserRequest,
+  res: BrowserResponse,
+  ctx: BrowserRouteContext,
+) {
+  const profileCtx = getProfileContext(req, ctx);
+  if ("error" in profileCtx) {
+    jsonError(res, profileCtx.status, profileCtx.error);
+    return null;
+  }
+  return profileCtx;
+}
+
+function handleTabsRouteError(
+  ctx: BrowserRouteContext,
+  res: BrowserResponse,
+  err: unknown,
+  opts?: { mapTabError?: boolean },
+) {
+  if (opts?.mapTabError) {
+    const mapped = ctx.mapTabError(err);
+    if (mapped) {
+      return jsonError(res, mapped.status, mapped.message);
+    }
+  }
+  return jsonError(res, 500, String(err));
+}
+
+async function withTabsProfileRoute(params: {
+  req: BrowserRequest;
+  res: BrowserResponse;
+  ctx: BrowserRouteContext;
+  mapTabError?: boolean;
+  run: (profileCtx: ProfileContext) => Promise<void>;
+}) {
+  const profileCtx = resolveTabsProfileContext(params.req, params.res, params.ctx);
+  if (!profileCtx) {
+    return;
+  }
+  try {
+    await params.run(profileCtx);
+  } catch (err) {
+    handleTabsRouteError(params.ctx, params.res, err, { mapTabError: params.mapTabError });
+  }
+}
+
+async function ensureBrowserRunning(profileCtx: ProfileContext, res: BrowserResponse) {
+  if (!(await profileCtx.isReachable(300))) {
+    jsonError(res, 409, "browser not running");
+    return false;
+  }
+  return true;
+}
+
+function resolveIndexedTab(
+  tabs: Awaited<ReturnType<ProfileContext["listTabs"]>>,
+  index: number | undefined,
+) {
+  return typeof index === "number" ? tabs[index] : tabs.at(0);
+}
+
+function parseRequiredTargetId(res: BrowserResponse, rawTargetId: unknown): string | null {
+  const targetId = toStringOrEmpty(rawTargetId);
+  if (!targetId) {
+    jsonError(res, 400, "targetId is required");
+    return null;
+  }
+  return targetId;
+}
+
+async function runTabTargetMutation(params: {
+  req: BrowserRequest;
+  res: BrowserResponse;
+  ctx: BrowserRouteContext;
+  targetId: string;
+  mutate: (profileCtx: ProfileContext, targetId: string) => Promise<void>;
+}) {
+  await withTabsProfileRoute({
+    req: params.req,
+    res: params.res,
+    ctx: params.ctx,
+    mapTabError: true,
+    run: async (profileCtx) => {
+      if (!(await ensureBrowserRunning(profileCtx, params.res))) {
+        return;
+      }
+      await params.mutate(profileCtx, params.targetId);
+      params.res.json({ ok: true });
+    },
+  });
+}
+
+export function registerBrowserTabRoutes(app: BrowserRouteRegistrar, ctx: BrowserRouteContext) {
+  app.get("/tabs", async (req, res) => {
+    await withTabsProfileRoute({
+      req,
+      res,
+      ctx,
+      run: async (profileCtx) => {
+        const reachable = await profileCtx.isReachable(300);
+        if (!reachable) {
+          return res.json({ running: false, tabs: [] as unknown[] });
+        }
+        const tabs = await profileCtx.listTabs();
+        res.json({ running: true, tabs });
+      },
+    });
+  });
+
+  app.post("/tabs/open", async (req, res) => {
+    const url = toStringOrEmpty((req.body as { url?: unknown })?.url);
+    if (!url) {
+      return jsonError(res, 400, "url is required");
+    }
+
+    await withTabsProfileRoute({
+      req,
+      res,
+      ctx,
+      mapTabError: true,
+      run: async (profileCtx) => {
+        await profileCtx.ensureBrowserAvailable();
+        const tab = await profileCtx.openTab(url);
+        res.json(tab);
+      },
+    });
+  });
+
+  app.post("/tabs/focus", async (req, res) => {
+    const targetId = parseRequiredTargetId(res, (req.body as { targetId?: unknown })?.targetId);
+    if (!targetId) {
+      return;
+    }
+    await runTabTargetMutation({
+      req,
+      res,
+      ctx,
+      targetId,
+      mutate: async (profileCtx, id) => {
+        await profileCtx.focusTab(id);
+      },
+    });
+  });
+
+  app.delete("/tabs/:targetId", async (req, res) => {
+    const targetId = parseRequiredTargetId(res, req.params.targetId);
+    if (!targetId) {
+      return;
+    }
+    await runTabTargetMutation({
+      req,
+      res,
+      ctx,
+      targetId,
+      mutate: async (profileCtx, id) => {
+        await profileCtx.closeTab(id);
+      },
+    });
+  });
+
+  app.post("/tabs/action", async (req, res) => {
+    const action = toStringOrEmpty((req.body as { action?: unknown })?.action);
+    const index = toNumber((req.body as { index?: unknown })?.index);
+
+    await withTabsProfileRoute({
+      req,
+      res,
+      ctx,
+      mapTabError: true,
+      run: async (profileCtx) => {
+        if (action === "list") {
+          const reachable = await profileCtx.isReachable(300);
+          if (!reachable) {
+            return res.json({ ok: true, tabs: [] as unknown[] });
+          }
+          const tabs = await profileCtx.listTabs();
+          return res.json({ ok: true, tabs });
+        }
+
+        if (action === "new") {
+          await profileCtx.ensureBrowserAvailable();
+          const tab = await profileCtx.openTab("about:blank");
+          return res.json({ ok: true, tab });
+        }
+
+        if (action === "close") {
+          const tabs = await profileCtx.listTabs();
+          const target = resolveIndexedTab(tabs, index);
+          if (!target) {
+            return jsonError(res, 404, "tab not found");
+          }
+          await profileCtx.closeTab(target.targetId);
+          return res.json({ ok: true, targetId: target.targetId });
+        }
+
+        if (action === "select") {
+          if (typeof index !== "number") {
+            return jsonError(res, 400, "index is required");
+          }
+          const tabs = await profileCtx.listTabs();
+          const target = tabs[index];
+          if (!target) {
+            return jsonError(res, 404, "tab not found");
+          }
+          await profileCtx.focusTab(target.targetId);
+          return res.json({ ok: true, targetId: target.targetId });
+        }
+
+        return jsonError(res, 400, "unknown tab action");
+      },
+    });
+  });
+}

package/src/browser/routes/types.ts

@@ -0,0 +1,26 @@
+export type BrowserRequest = {
+  params: Record<string, string>;
+  query: Record<string, unknown>;
+  body?: unknown;
+  /**
+   * Optional abort signal for in-process dispatch. This lets callers enforce
+   * timeouts and (where supported) cancel long-running operations.
+   */
+  signal?: AbortSignal;
+};
+
+export type BrowserResponse = {
+  status: (code: number) => BrowserResponse;
+  json: (body: unknown) => void;
+};
+
+export type BrowserRouteHandler = (
+  req: BrowserRequest,
+  res: BrowserResponse,
+) => void | Promise<void>;
+
+export type BrowserRouteRegistrar = {
+  get: (path: string, handler: BrowserRouteHandler) => void;
+  post: (path: string, handler: BrowserRouteHandler) => void;
+  delete: (path: string, handler: BrowserRouteHandler) => void;
+};

package/src/browser/routes/utils.ts

@@ -0,0 +1,73 @@
+import { parseBooleanValue } from "../enterprise-compat.js";
+import type { BrowserRouteContext, ProfileContext } from "../server-context.js";
+import type { BrowserRequest, BrowserResponse } from "./types.js";
+
+/**
+ * Extract profile name from query string or body and get profile context.
+ * Query string takes precedence over body for consistency with GET routes.
+ */
+export function getProfileContext(
+  req: BrowserRequest,
+  ctx: BrowserRouteContext,
+): ProfileContext | { error: string; status: number } {
+  let profileName: string | undefined;
+
+  // Check query string first (works for GET and POST)
+  if (typeof req.query.profile === "string") {
+    profileName = req.query.profile.trim() || undefined;
+  }
+
+  // Fall back to body for POST requests
+  if (!profileName && req.body && typeof req.body === "object") {
+    const body = req.body as Record<string, unknown>;
+    if (typeof body.profile === "string") {
+      profileName = body.profile.trim() || undefined;
+    }
+  }
+
+  try {
+    return ctx.forProfile(profileName);
+  } catch (err) {
+    return { error: String(err), status: 404 };
+  }
+}
+
+export function jsonError(res: BrowserResponse, status: number, message: string) {
+  res.status(status).json({ error: message });
+}
+
+export function toStringOrEmpty(value: unknown) {
+  if (typeof value === "string") {
+    return value.trim();
+  }
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value).trim();
+  }
+  return "";
+}
+
+export function toNumber(value: unknown) {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return value;
+  }
+  if (typeof value === "string" && value.trim()) {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+  }
+  return undefined;
+}
+
+export function toBoolean(value: unknown) {
+  return parseBooleanValue(value, {
+    truthy: ["true", "1", "yes"],
+    falsy: ["false", "0", "no"],
+  });
+}
+
+export function toStringArray(value: unknown): string[] | undefined {
+  if (!Array.isArray(value)) {
+    return undefined;
+  }
+  const strings = value.map((v) => toStringOrEmpty(v)).filter(Boolean);
+  return strings.length ? strings : undefined;
+}

package/src/browser/screenshot.ts

@@ -0,0 +1,54 @@
+import { IMAGE_REDUCE_QUALITY_STEPS, buildImageResizeSideGrid, getImageMetadata, resizeToJpeg } from "./enterprise-compat.js";
+
+
+export const DEFAULT_BROWSER_SCREENSHOT_MAX_SIDE = 2000;
+export const DEFAULT_BROWSER_SCREENSHOT_MAX_BYTES = 5 * 1024 * 1024;
+
+export async function normalizeBrowserScreenshot(
+  buffer: Buffer,
+  opts?: {
+    maxSide?: number;
+    maxBytes?: number;
+  },
+): Promise<{ buffer: Buffer; contentType?: "image/jpeg" }> {
+  const maxSide = Math.max(1, Math.round(opts?.maxSide ?? DEFAULT_BROWSER_SCREENSHOT_MAX_SIDE));
+  const maxBytes = Math.max(1, Math.round(opts?.maxBytes ?? DEFAULT_BROWSER_SCREENSHOT_MAX_BYTES));
+
+  const meta = await getImageMetadata(buffer);
+  const width = Number(meta?.width ?? 0);
+  const height = Number(meta?.height ?? 0);
+  const maxDim = Math.max(width, height);
+
+  if (buffer.byteLength <= maxBytes && (maxDim === 0 || (width <= maxSide && height <= maxSide))) {
+    return { buffer };
+  }
+
+  const sideStart = maxDim > 0 ? Math.min(maxSide, maxDim) : maxSide;
+  const sideGrid = buildImageResizeSideGrid(maxSide, sideStart);
+
+  let smallest: { buffer: Buffer; size: number } | null = null;
+
+  for (const side of sideGrid) {
+    for (const quality of IMAGE_REDUCE_QUALITY_STEPS) {
+      const out = await resizeToJpeg({
+        buffer,
+        maxSide: side,
+        quality,
+        withoutEnlargement: true,
+      });
+
+      if (!smallest || out.byteLength < smallest.size) {
+        smallest = { buffer: out, size: out.byteLength };
+      }
+
+      if (out.byteLength <= maxBytes) {
+        return { buffer: out, contentType: "image/jpeg" };
+      }
+    }
+  }
+
+  const best = smallest?.buffer ?? buffer;
+  throw new Error(
+    `Browser screenshot could not be reduced below ${(maxBytes / (1024 * 1024)).toFixed(0)}MB (got ${(best.byteLength / (1024 * 1024)).toFixed(2)}MB)`,
+  );
+}