@arnilo/prism-tools 0.0.0-stage → 0.13.1

package/browser/src/actions/wait.ts

@@ -0,0 +1,45 @@
+import { setTimeout as sleep } from "node:timers/promises";
+import { BrowserError } from "../errors.js";
+import type { BrowserActRequest, BrowserActResult } from "../types.js";
+import type { ActionContext, RunSession } from "./types.js";
+
+export async function wait(
+  ctx: ActionContext,
+  session: RunSession,
+  request: BrowserActRequest,
+  signal: AbortSignal | undefined,
+): Promise<BrowserActResult> {
+  ctx.chargeAction(session);
+  const page = ctx.resolvePage(session, request.pageId);
+  const timeout = clampTimeout(request.timeoutMs, ctx.limits.waitTimeoutMs);
+  if (typeof request.url === "string" && request.url) {
+    ctx.assertInputBytes(request.url);
+    if (!page.page.waitForURL) {
+      throw new BrowserError("ERR_PRISM_BROWSER", "Page does not support waitForURL");
+    }
+    await page.page.waitForURL(request.url, { timeout });
+  } else if (typeof request.text === "string" && request.text) {
+    ctx.assertInputBytes(request.text);
+    const locator = page.page.getByText(request.text, { exact: false });
+    const start = Date.now();
+    while (Date.now() - start < timeout) {
+      ctx.throwIfAborted(signal);
+      if ((await locator.count()) > 0) break;
+      await sleep(50);
+    }
+    if ((await locator.count()) === 0) {
+      throw new BrowserError("ERR_PRISM_BROWSER", `wait text not found within ${timeout}ms`);
+    }
+  } else {
+    await sleep(Math.min(timeout, ctx.limits.waitTimeoutMs));
+  }
+  return ctx.resultFor(session, "wait", page);
+}
+
+function clampTimeout(value: number | undefined, hard: number): number {
+  if (value === undefined) return hard;
+  if (!Number.isSafeInteger(value) || value < 1 || value > hard) {
+    throw new BrowserError("ERR_PRISM_BROWSER_LIMIT", `timeoutMs must be 1..${hard}`);
+  }
+  return value;
+}

package/browser/src/browser.ts

@@ -0,0 +1,197 @@
+export {
+  type CdpExceptionDetails,
+  type CdpMode,
+  type CdpRemoteObject,
+  type CdpRuntimeEvaluateResponse,
+  cdpAvailable,
+  cdpEmulationClearDeviceMetrics,
+  cdpEmulationSetDeviceMetrics,
+  cdpEmulationSetUserAgent,
+  cdpNetworkEmulateConditions,
+  cdpNetworkEnable,
+  cdpNetworkSetBlockedUrls,
+  cdpRuntimeEnable,
+  cdpRuntimeEvaluate,
+  createPageCdpSession,
+  resolveCdpMode,
+} from "./cdp.js";
+export {
+  type BrowserCheckpoint,
+  type BrowserCheckpointInput,
+  type BrowserCheckpointLedger,
+  type BrowserCheckpointLimitOptions,
+  type BrowserCheckpointLimits,
+  createBrowserCheckpointLedger,
+  DEFAULT_MAX_CHECKPOINT_URL_BYTES,
+  DEFAULT_MAX_CHECKPOINTS_PER_RUN,
+  DEFAULT_MAX_DOMAIN_STATE_HASH_BYTES,
+  DEFAULT_MAX_HOST_DATA_REF_BYTES,
+  HARD_MAX_CHECKPOINT_URL_BYTES,
+  HARD_MAX_CHECKPOINTS_PER_RUN,
+  HARD_MAX_DOMAIN_STATE_HASH_BYTES,
+  HARD_MAX_HOST_DATA_REF_BYTES,
+  resolveBrowserCheckpointLimits,
+} from "./checkpoint.js";
+export {
+  type BrowserDownloadOptions,
+  cleanupDownloads,
+  createDownloadBudget,
+  type DownloadBudget,
+  type DownloadMetadata,
+  quarantineDownload,
+  releaseDownload,
+  sanitizeDownloadName,
+} from "./downloads.js";
+export { BrowserError, type BrowserErrorCode } from "./errors.js";
+export { boundedJson, type EvaluateBounds, type EvaluateOutcome, evaluateInPage } from "./evaluate.js";
+export {
+  type BrowserLimitOptions,
+  DEFAULT_ACTION_TIMEOUT_MS,
+  DEFAULT_BROWSER_LIMITS,
+  DEFAULT_CLOSE_GRACE_MS,
+  DEFAULT_IDLE_RUN_TTL_MS,
+  DEFAULT_MAX_ACTION_INPUT_BYTES,
+  DEFAULT_MAX_ACTIONS,
+  DEFAULT_MAX_BLOCKED_URL_PATTERNS,
+  DEFAULT_MAX_CONSOLE_ENTRIES,
+  DEFAULT_MAX_DIALOGS,
+  DEFAULT_MAX_DOWNLOAD_AGGREGATE_BYTES,
+  DEFAULT_MAX_DOWNLOAD_BYTES,
+  DEFAULT_MAX_DOWNLOADS,
+  DEFAULT_MAX_EVALUATE_RESULT_BYTES,
+  DEFAULT_MAX_LISTENERS,
+  DEFAULT_MAX_NETWORK_REQUESTS,
+  DEFAULT_MAX_PAGES,
+  DEFAULT_MAX_POPUPS,
+  DEFAULT_MAX_QUEUED_ACTIONS,
+  DEFAULT_MAX_REDIRECTS_PER_REQUEST,
+  DEFAULT_MAX_SCREENSHOT_BYTES,
+  DEFAULT_MAX_SCREENSHOT_MEGAPIXELS,
+  DEFAULT_MAX_SCREENSHOTS,
+  DEFAULT_MAX_SNAPSHOT_BYTES,
+  DEFAULT_MAX_SNAPSHOT_DEPTH,
+  DEFAULT_MAX_SNAPSHOT_REFS,
+  DEFAULT_MAX_UPLOAD_AGGREGATE_BYTES,
+  DEFAULT_MAX_UPLOAD_BYTES,
+  DEFAULT_MAX_UPLOADS,
+  DEFAULT_MAX_WEBSOCKETS,
+  DEFAULT_NAVIGATION_TIMEOUT_MS,
+  DEFAULT_RUN_WALL_TIME_MS,
+  DEFAULT_WAIT_TIMEOUT_MS,
+  HARD_ACTION_TIMEOUT_MS,
+  HARD_BROWSER_LIMITS,
+  HARD_CLOSE_GRACE_MS,
+  HARD_IDLE_RUN_TTL_MS,
+  HARD_MAX_ACTION_INPUT_BYTES,
+  HARD_MAX_ACTIONS,
+  HARD_MAX_BLOCKED_URL_PATTERNS,
+  HARD_MAX_CONSOLE_ENTRIES,
+  HARD_MAX_DEVICE_SCALE_FACTOR,
+  HARD_MAX_DIALOGS,
+  HARD_MAX_DOWNLOAD_AGGREGATE_BYTES,
+  HARD_MAX_DOWNLOAD_BYTES,
+  HARD_MAX_DOWNLOADS,
+  HARD_MAX_EMULATE_DIMENSION,
+  HARD_MAX_EMULATE_UA_BYTES,
+  HARD_MAX_EVALUATE_RESULT_BYTES,
+  HARD_MAX_LISTENERS,
+  HARD_MAX_NETWORK_REQUESTS,
+  HARD_MAX_PAGES,
+  HARD_MAX_POPUPS,
+  HARD_MAX_QUEUED_ACTIONS,
+  HARD_MAX_REDIRECTS_PER_REQUEST,
+  HARD_MAX_SCREENSHOT_BYTES,
+  HARD_MAX_SCREENSHOT_MEGAPIXELS,
+  HARD_MAX_SCREENSHOTS,
+  HARD_MAX_SNAPSHOT_BYTES,
+  HARD_MAX_SNAPSHOT_DEPTH,
+  HARD_MAX_SNAPSHOT_REFS,
+  HARD_MAX_THROTTLE_KBPS,
+  HARD_MAX_THROTTLE_LATENCY_MS,
+  HARD_MAX_UPLOAD_AGGREGATE_BYTES,
+  HARD_MAX_UPLOAD_BYTES,
+  HARD_MAX_UPLOADS,
+  HARD_MAX_WEBSOCKETS,
+  HARD_NAVIGATION_TIMEOUT_MS,
+  HARD_RUN_WALL_TIME_MS,
+  HARD_WAIT_TIMEOUT_MS,
+  type ResolvedBrowserLimits,
+  resolveBrowserLimits,
+} from "./limits.js";
+export { type BrowserManager, type CreateBrowserManagerOptions, createBrowserManager } from "./manager.js";
+export {
+  assertBrowserUrlAllowed,
+  type BrowserNetworkPolicy,
+  type BrowserUrlDecision,
+  classifyBrowserUrl,
+  classifyHost,
+  createNetworkBudget,
+  installNetworkRouting,
+  type NetworkBudget,
+} from "./network.js";
+export { createObservationRing, installCdpObservation, type ObservationRing } from "./observe.js";
+export {
+  type BrowserEffectClass,
+  type BrowserOperationClass,
+  type BrowserRisk,
+  classifyBrowserOperation,
+  classifyBrowserToolEffect,
+  isSideEffectAction,
+} from "./policy.js";
+export {
+  type CaptureScreenshotOptions,
+  captureBoundedScreenshot,
+  createScreenshotBudget,
+  type ScreenshotBudget,
+  type ScreenshotResult,
+} from "./screenshot.js";
+export {
+  createSharedSandboxBrowserOptions,
+  type SharedSandboxBrowserAlignment,
+  type SharedSandboxBrowserOptions,
+} from "./shared-sandbox.js";
+export { captureAriaSnapshot, createSnapshotId, type LiveSnapshot, toSnapshotResult } from "./snapshot.js";
+export {
+  assertValidRef,
+  normalizeTarget,
+  parseSnapshotRefs,
+  requireUniqueLocator,
+  resolveTargetLocator,
+} from "./targets.js";
+export { type BrowserToolsOptions, createBrowserTools, getBrowserManagerFromTools } from "./tools.js";
+export type {
+  BrowserActionName,
+  BrowserActRequest,
+  BrowserActResult,
+  BrowserCdpOptions,
+  BrowserDownloadInfo,
+  BrowserEvaluateRequest,
+  BrowserEvaluateResult,
+  BrowserObserveResult,
+  BrowserOpenResult,
+  BrowserPageInfo,
+  BrowserSnapshotResult,
+  BrowserTarget,
+  CdpConsoleEntry,
+  CdpNetworkEntry,
+  PlaywrightBrowser,
+  PlaywrightBrowserContext,
+  PlaywrightCdpSession,
+  PlaywrightDialog,
+  PlaywrightDownload,
+  PlaywrightLocator,
+  PlaywrightPage,
+  PlaywrightRequest,
+  PlaywrightRoute,
+  SnapshotRefInfo,
+} from "./types.js";
+export {
+  type ApprovedUploadFile,
+  approveUploadPaths,
+  type BrowserUploadOptions,
+  createUploadBudget,
+  resolveUploadCandidate,
+  type UploadBudget,
+} from "./uploads.js";
+
+export const packageName = "@arnilo/prism-tools/browser";

package/browser/src/cdp.ts

@@ -0,0 +1,178 @@
+/**
+ * Chrome DevTools Protocol session layer (0.1.4, plan 016 Task 4).
+ * Rides playwright-core's existing CDP transport (context.newCDPSession(page)) —
+ * zero new dependencies, host-supplied Chromium browser only, Prism never
+ * launches or downloads browsers. Domain allowlist: Runtime, Network, Emulation.
+ * No cookies/tracing/IndexedDB/worker-attach domains in 0.1.4.
+ */
+import { BrowserError } from "./errors.js";
+import type { BrowserCdpOptions, PlaywrightBrowser, PlaywrightBrowserContext, PlaywrightCdpSession, PlaywrightPage } from "./types.js";
+
+export type CdpMode = "auto" | "on" | "off";
+
+export function resolveCdpMode(options?: BrowserCdpOptions): CdpMode {
+  return options?.mode ?? "auto";
+}
+
+/**
+ * Chromium-only capability signal. Playwright exposes page-level CDP sessions
+ * only for Chromium; belt-and-braces: version() strings prefixed firefox-/webkit-
+ * are treated as non-CDP even if a host layered newCDPSession on them.
+ */
+export function cdpAvailable(browser: PlaywrightBrowser, context: PlaywrightBrowserContext): boolean {
+  if (typeof context.newCDPSession !== "function") return false;
+  const version = browser.version?.() ?? "";
+  if (/^(firefox|webkit)-/u.test(version)) return false;
+  return true;
+}
+
+/** Create a page-level CDP session or throw ERR_PRISM_BROWSER_CDP_UNAVAILABLE. */
+export async function createPageCdpSession(
+  browser: PlaywrightBrowser,
+  context: PlaywrightBrowserContext,
+  page: PlaywrightPage,
+): Promise<PlaywrightCdpSession> {
+  if (!cdpAvailable(browser, context)) {
+    throw new BrowserError(
+      "ERR_PRISM_BROWSER_CDP_UNAVAILABLE",
+      "CDP requires a Chromium-based host browser whose contexts expose newCDPSession(page)",
+    );
+  }
+  try {
+    const session = await context.newCDPSession!(page);
+    if (!session || typeof session.send !== "function") {
+      throw new BrowserError("ERR_PRISM_BROWSER_CDP_UNAVAILABLE", "Host newCDPSession did not return a usable CDP session");
+    }
+    return session;
+  } catch (error) {
+    if (error instanceof BrowserError) throw error;
+    throw new BrowserError(
+      "ERR_PRISM_BROWSER_CDP_UNAVAILABLE",
+      `CDP session creation failed: ${error instanceof Error ? error.message.slice(0, 256) : String(error).slice(0, 256)}`,
+    );
+  }
+}
+
+/** Bounded JSON-serializable value carried by a CDP RemoteObject. */
+export interface CdpRemoteObject {
+  readonly type?: string;
+  readonly subtype?: string;
+  readonly value?: unknown;
+  readonly description?: string;
+}
+
+export interface CdpExceptionDetails {
+  readonly text?: string;
+  readonly url?: string;
+  readonly lineNumber?: number;
+  readonly columnNumber?: number;
+  readonly exception?: CdpRemoteObject;
+}
+
+export interface CdpRuntimeEvaluateResponse {
+  readonly result?: CdpRemoteObject;
+  readonly exceptionDetails?: CdpExceptionDetails;
+}
+
+export async function cdpRuntimeEvaluate(
+  session: PlaywrightCdpSession,
+  params: {
+    expression: string;
+    awaitPromise?: boolean;
+    returnByValue?: boolean;
+    userGesture?: boolean;
+    timeout?: number;
+  },
+): Promise<CdpRuntimeEvaluateResponse> {
+  try {
+    return await session.send<CdpRuntimeEvaluateResponse>("Runtime.evaluate", {
+      expression: params.expression,
+      awaitPromise: params.awaitPromise === true,
+      returnByValue: params.returnByValue === true,
+      userGesture: params.userGesture === true,
+      ...(params.timeout !== undefined ? { timeout: params.timeout } : {}),
+    });
+  } catch (error) {
+    throw cdpSendError(error);
+  }
+}
+
+export async function cdpRuntimeEnable(session: PlaywrightCdpSession): Promise<void> {
+  try {
+    await session.send("Runtime.enable");
+  } catch (error) {
+    throw cdpSendError(error);
+  }
+}
+
+export async function cdpNetworkEnable(session: PlaywrightCdpSession): Promise<void> {
+  try {
+    await session.send("Network.enable");
+  } catch (error) {
+    throw cdpSendError(error);
+  }
+}
+
+export async function cdpNetworkSetBlockedUrls(session: PlaywrightCdpSession, urls: readonly string[]): Promise<void> {
+  try {
+    await session.send("Network.setBlockedURLs", { urls: [...urls] });
+  } catch (error) {
+    throw cdpSendError(error);
+  }
+}
+
+export async function cdpNetworkEmulateConditions(
+  session: PlaywrightCdpSession,
+  params: { offline: boolean; latencyMs: number; downloadThroughputBps: number; uploadThroughputBps: number },
+): Promise<void> {
+  try {
+    await session.send("Network.emulateNetworkConditions", {
+      offline: params.offline,
+      latency: params.latencyMs,
+      downloadThroughput: params.downloadThroughputBps,
+      uploadThroughput: params.uploadThroughputBps,
+    });
+  } catch (error) {
+    throw cdpSendError(error);
+  }
+}
+
+export async function cdpEmulationSetDeviceMetrics(
+  session: PlaywrightCdpSession,
+  params: { width: number; height: number; mobile: boolean; deviceScaleFactor: number },
+): Promise<void> {
+  try {
+    await session.send("Emulation.setDeviceMetricsOverride", {
+      width: params.width,
+      height: params.height,
+      mobile: params.mobile,
+      deviceScaleFactor: params.deviceScaleFactor,
+    });
+  } catch (error) {
+    throw cdpSendError(error);
+  }
+}
+
+export async function cdpEmulationSetUserAgent(session: PlaywrightCdpSession, userAgent: string): Promise<void> {
+  try {
+    await session.send("Emulation.setUserAgentOverride", { userAgent });
+  } catch (error) {
+    throw cdpSendError(error);
+  }
+}
+
+export async function cdpEmulationClearDeviceMetrics(session: PlaywrightCdpSession): Promise<void> {
+  try {
+    await session.send("Emulation.clearDeviceMetricsOverride");
+  } catch (error) {
+    throw cdpSendError(error);
+  }
+}
+
+function cdpSendError(error: unknown): BrowserError {
+  if (error instanceof BrowserError) return error;
+  return new BrowserError(
+    "ERR_PRISM_BROWSER_CDP",
+    `CDP send failed: ${error instanceof Error ? error.message.slice(0, 256) : String(error).slice(0, 256)}`,
+  );
+}

package/browser/src/checkpoint.ts

@@ -0,0 +1,189 @@
+/**
+ * Verified-state browser checkpoints (Task 6).
+ *
+ * A checkpoint records verified navigation state — URL, a domain-state hash,
+ * and host-owned data refs — never serialized browser internals (cookies,
+ * storage, contexts), which are fragile and secret-bearing. After any resume or
+ * interruption the ledger requires a reload + verify before the first mutating
+ * action, so side effects never replay on stale/unverified state (fail closed).
+ * Checkpoints are run-scoped; a conversation thread composes through the run it
+ * owns, reusing the manager's existing sandbox/egress/approval/limit policy.
+ */
+import { BrowserError } from "./errors.js";
+
+/** Checkpoint URL: 8 KiB default / 16 KiB hard. */
+export const DEFAULT_MAX_CHECKPOINT_URL_BYTES = 8 * 1024;
+export const HARD_MAX_CHECKPOINT_URL_BYTES = 16 * 1024;
+/** Domain state hash: 256 B default / 1 KiB hard. */
+export const DEFAULT_MAX_DOMAIN_STATE_HASH_BYTES = 256;
+export const HARD_MAX_DOMAIN_STATE_HASH_BYTES = 1024;
+/** Host data ref (ref only, never a body): 2 KiB default / 8 KiB hard. */
+export const DEFAULT_MAX_HOST_DATA_REF_BYTES = 2 * 1024;
+export const HARD_MAX_HOST_DATA_REF_BYTES = 8 * 1024;
+/** Checkpoints retained per run: 16 default / 64 hard (oldest evicted). */
+export const DEFAULT_MAX_CHECKPOINTS_PER_RUN = 16;
+export const HARD_MAX_CHECKPOINTS_PER_RUN = 64;
+
+export interface BrowserCheckpoint {
+  readonly checkpointId: string;
+  readonly runId: string;
+  readonly url: string;
+  readonly domainStateHash: string;
+  /** Host-owned data reference only — never a serialized browser internal or body. */
+  readonly hostDataRef?: string;
+  readonly createdAt: string;
+  readonly verified: boolean;
+}
+
+export interface BrowserCheckpointLimits {
+  readonly maxUrlBytes: number;
+  readonly maxDomainStateHashBytes: number;
+  readonly maxHostDataRefBytes: number;
+  readonly maxCheckpointsPerRun: number;
+}
+
+export interface BrowserCheckpointLimitOptions {
+  readonly maxUrlBytes?: number;
+  readonly maxDomainStateHashBytes?: number;
+  readonly maxHostDataRefBytes?: number;
+  readonly maxCheckpointsPerRun?: number;
+}
+
+export interface BrowserCheckpointInput {
+  readonly runId: string;
+  readonly url: string;
+  readonly domainStateHash: string;
+  readonly hostDataRef?: string;
+}
+
+export interface BrowserCheckpointLedger {
+  readonly limits: BrowserCheckpointLimits;
+  /** Record verified state during normal operation. */
+  checkpoint(input: BrowserCheckpointInput): BrowserCheckpoint;
+  list(runId: string): readonly BrowserCheckpoint[];
+  /** Mark a run's state stale after resume/interruption; verify required before side effect. */
+  markResumed(runId: string): void;
+  /** Reload + verify completed; clears the verify gate and records a fresh verified checkpoint. */
+  verify(input: BrowserCheckpointInput): BrowserCheckpoint;
+  /** Fail closed unless the run holds verified state (reload+verify before any mutating action). */
+  assertVerifiedBeforeSideEffect(runId: string): void;
+}
+
+function validateBytes(name: string, value: string | undefined, max: number, required: boolean): string | undefined {
+  if (value === undefined) {
+    if (required) throw new BrowserError("ERR_PRISM_BROWSER_INPUT", `${name} is required`);
+    return undefined;
+  }
+  if (typeof value !== "string" || value.length === 0) {
+    throw new BrowserError("ERR_PRISM_BROWSER_INPUT", `${name} must be a non-empty string`);
+  }
+  if (Buffer.byteLength(value, "utf8") > max) {
+    throw new BrowserError("ERR_PRISM_BROWSER_LIMIT", `${name} exceeds ${max} bytes`);
+  }
+  return value;
+}
+
+function validateCount(name: string, value: number | undefined, def: number, hard: number): number {
+  const resolved = value ?? def;
+  if (!Number.isSafeInteger(resolved) || resolved < 1 || resolved > hard) {
+    throw new BrowserError("ERR_PRISM_BROWSER_LIMIT", `${name} must be a positive safe integer at most ${hard}`);
+  }
+  return resolved;
+}
+
+export function resolveBrowserCheckpointLimits(input: BrowserCheckpointLimitOptions = {}): BrowserCheckpointLimits {
+  return {
+    maxUrlBytes: validateCount("maxUrlBytes", input.maxUrlBytes, DEFAULT_MAX_CHECKPOINT_URL_BYTES, HARD_MAX_CHECKPOINT_URL_BYTES),
+    maxDomainStateHashBytes: validateCount(
+      "maxDomainStateHashBytes",
+      input.maxDomainStateHashBytes,
+      DEFAULT_MAX_DOMAIN_STATE_HASH_BYTES,
+      HARD_MAX_DOMAIN_STATE_HASH_BYTES,
+    ),
+    maxHostDataRefBytes: validateCount(
+      "maxHostDataRefBytes",
+      input.maxHostDataRefBytes,
+      DEFAULT_MAX_HOST_DATA_REF_BYTES,
+      HARD_MAX_HOST_DATA_REF_BYTES,
+    ),
+    maxCheckpointsPerRun: validateCount(
+      "maxCheckpointsPerRun",
+      input.maxCheckpointsPerRun,
+      DEFAULT_MAX_CHECKPOINTS_PER_RUN,
+      HARD_MAX_CHECKPOINTS_PER_RUN,
+    ),
+  };
+}
+
+interface RunCheckpointState {
+  readonly checkpoints: BrowserCheckpoint[];
+  needsVerify: boolean;
+}
+
+let checkpointSeq = 0;
+function nextCheckpointId(): string {
+  checkpointSeq += 1;
+  return `bcp_${checkpointSeq}`;
+}
+
+export function createBrowserCheckpointLedger(options: BrowserCheckpointLimitOptions = {}): BrowserCheckpointLedger {
+  const limits = resolveBrowserCheckpointLimits(options);
+  const runs = new Map<string, RunCheckpointState>();
+
+  function record(input: BrowserCheckpointInput): BrowserCheckpoint {
+    const runId = validateBytes("runId", input.runId, 256, true)!;
+    const url = validateBytes("url", input.url, limits.maxUrlBytes, true)!;
+    const domainStateHash = validateBytes("domainStateHash", input.domainStateHash, limits.maxDomainStateHashBytes, true)!;
+    const hostDataRef = validateBytes("hostDataRef", input.hostDataRef, limits.maxHostDataRefBytes, false);
+    const checkpoint: BrowserCheckpoint = {
+      checkpointId: nextCheckpointId(),
+      runId,
+      url,
+      domainStateHash,
+      ...(hostDataRef ? { hostDataRef } : {}),
+      createdAt: new Date().toISOString(),
+      verified: true,
+    };
+    let state = runs.get(runId);
+    if (!state) {
+      state = { checkpoints: [], needsVerify: false };
+      runs.set(runId, state);
+    }
+    state.checkpoints.push(checkpoint);
+    // Bounded retention: evict oldest beyond the per-run cap.
+    while (state.checkpoints.length > limits.maxCheckpointsPerRun) {
+      state.checkpoints.shift();
+    }
+    return checkpoint;
+  }
+
+  return {
+    limits,
+    checkpoint: (input) => record(input),
+    list: (runId) => runs.get(runId)?.checkpoints ?? [],
+    markResumed(runId) {
+      validateBytes("runId", runId, 256, true);
+      let state = runs.get(runId);
+      if (!state) {
+        // Resuming an unknown run is unverified state — fail closed until verify.
+        state = { checkpoints: [], needsVerify: true };
+        runs.set(runId, state);
+      } else {
+        state.needsVerify = true;
+      }
+    },
+    verify(input) {
+      const checkpoint = record(input);
+      const state = runs.get(checkpoint.runId)!;
+      state.needsVerify = false;
+      return checkpoint;
+    },
+    assertVerifiedBeforeSideEffect(runId) {
+      validateBytes("runId", runId, 256, true);
+      const state = runs.get(runId);
+      if (!state || state.needsVerify || state.checkpoints.length === 0) {
+        throw new BrowserError("ERR_PRISM_BROWSER_STATE", "browser side effect requires reload + verify after resume/interruption");
+      }
+    },
+  };
+}

package/browser/src/config.ts

@@ -0,0 +1,72 @@
+import type { JsonSchema } from "@arnilo/prism";
+
+/** Host attestation that real egress is forced through an isolated proxy/firewall. */
+export interface ToolsBrowserProxyConfig {
+  readonly proxyEndpoint: string;
+  readonly denyDirectEgress: true;
+}
+
+/** Validated `packageConfig` for `@arnilo/prism-tools/browser`. */
+export interface ToolsBrowserConfig {
+  /** Launch a headless Chromium through `playwright-core` (default `true`). */
+  readonly headless?: boolean;
+  /** Absolute path to a host-pinned browser binary passed to `chromium.launch`. */
+  readonly executablePath?: string;
+  /** Playwright channel (for example `"chromium"` or `"chrome"`) passed to `chromium.launch`. */
+  readonly channel?: string;
+  /**
+   * Origin allowlist. When set, navigation and subrequests to any other origin are hard-denied.
+   * Omit to leave origin decisions to `containedProxy` and the default scheme/host denies.
+   */
+  readonly allowOrigins?: readonly string[];
+  /** Host contained-proxy attestation; without it every external request is denied (fail closed). */
+  readonly containedProxy?: ToolsBrowserProxyConfig;
+  /** Allow loopback destinations (default `false`). */
+  readonly allowLoopback?: boolean;
+  /** Allow private/link-local/ULA destinations (default `false`). */
+  readonly allowPrivateHosts?: boolean;
+  /** Absolute roots uploads may read from (realpath-contained; symlink escapes rejected). */
+  readonly uploadRoots?: readonly string[];
+  /** Absolute quarantine directory; enables download support when set. */
+  readonly quarantine?: string;
+  /** CDP capability gating: `"auto"` (default), `"on"`, or `"off"`. */
+  readonly cdp?: "auto" | "on" | "off";
+}
+
+const originList: JsonSchema = {
+  type: "array",
+  items: { type: "string", minLength: 1, maxLength: 4096 },
+  maxItems: 64,
+};
+
+const pathList: JsonSchema = {
+  type: "array",
+  items: { type: "string", minLength: 1, maxLength: 4096 },
+  maxItems: 64,
+};
+
+/** The config schema. Every undeclared key fails closed. */
+export const toolsBrowserConfigSchema: JsonSchema = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    headless: { type: "boolean", default: true },
+    executablePath: { type: "string", minLength: 1, maxLength: 4096 },
+    channel: { type: "string", minLength: 1, maxLength: 128 },
+    allowOrigins: originList,
+    containedProxy: {
+      type: "object",
+      additionalProperties: false,
+      required: ["proxyEndpoint", "denyDirectEgress"],
+      properties: {
+        proxyEndpoint: { type: "string", minLength: 1, maxLength: 4096 },
+        denyDirectEgress: { type: "boolean", enum: [true] },
+      },
+    },
+    allowLoopback: { type: "boolean", default: false },
+    allowPrivateHosts: { type: "boolean", default: false },
+    uploadRoots: pathList,
+    quarantine: { type: "string", minLength: 1, maxLength: 4096 },
+    cdp: { type: "string", enum: ["auto", "on", "off"], default: "auto" },
+  },
+};