Add persistent Browser REPL API

README.md

@@ -98,7 +98,7 @@ Deployed successfully!
 
 ## Connect to the browser via Chrome DevTools Protocol
 
-Port `9222` is exposed via `ncat`, allowing you to connect Chrome DevTools Protocol-based browser frameworks like Playwright and Puppeteer (and CDP-based SDKs like Browser Use). You can use these frameworks to drive the browser in the cloud. You can also disconnect from the browser and reconnect to it.
+Port `9222` is exposed via `ncat`, allowing you to connect Chrome DevTools Protocol-based browser frameworks like Playwright and Puppeteer. You can use these frameworks to drive the browser in the cloud. You can also disconnect from the browser and reconnect to it.
 
 First, fetch the browser's CDP websocket endpoint:
 

images/chromium-headful/Dockerfile

@@ -389,6 +389,21 @@ RUN esbuild /tmp/playwright-daemon.ts \
     --external:esbuild \
     && rm /tmp/playwright-daemon.ts /tmp/page-target-id-cache.ts /tmp/webmcp.ts
 
+# Copy and install the browser REPL's pinned runtime dependencies before bundling.
+COPY server/runtime/ /tmp/browser-repl/
+RUN npm ci --ignore-scripts --no-audit --no-fund --omit=dev --prefix /tmp/browser-repl \
+    && mkdir -p /usr/local/lib/browser-repl \
+    && cp -a /tmp/browser-repl/node_modules /usr/local/lib/browser-repl/node_modules \
+    && esbuild /tmp/browser-repl/browser-repl.ts \
+      --bundle \
+      --platform=node \
+      --target=node22 \
+      --format=cjs \
+      --supported:dynamic-import=true \
+      --external:sharp \
+      --outfile=/usr/local/lib/browser-repl/browser-repl.js \
+    && rm -rf /tmp/browser-repl
+
 RUN useradd -m -s /bin/bash kernel
 
 # Bake the envoy forward-proxy CA cert into the image (system trust store +

images/chromium-headless/image/Dockerfile

@@ -285,4 +285,19 @@ RUN esbuild /tmp/playwright-daemon.ts \
     --external:esbuild \
     && rm /tmp/playwright-daemon.ts /tmp/page-target-id-cache.ts /tmp/webmcp.ts
 
+# Copy and install the browser REPL's pinned runtime dependencies before bundling.
+COPY server/runtime/ /tmp/browser-repl/
+RUN npm ci --ignore-scripts --no-audit --no-fund --omit=dev --prefix /tmp/browser-repl \
+    && mkdir -p /usr/local/lib/browser-repl \
+    && cp -a /tmp/browser-repl/node_modules /usr/local/lib/browser-repl/node_modules \
+    && esbuild /tmp/browser-repl/browser-repl.ts \
+      --bundle \
+      --platform=node \
+      --target=node22 \
+      --format=cjs \
+      --supported:dynamic-import=true \
+      --external:sharp \
+      --outfile=/usr/local/lib/browser-repl/browser-repl.js \
+    && rm -rf /tmp/browser-repl
+
 ENTRYPOINT [ "/wrapper" ]

server/Makefile

@@ -1,5 +1,5 @@
 SHELL := /bin/bash
-.PHONY: oapi-generate build dev test test-unit test-runtime test-e2e clean
+.PHONY: oapi-generate runtime-typecheck build dev test test-unit test-runtime test-e2e clean
 
 BIN_DIR ?= $(CURDIR)/bin
 RECORDING_DIR ?= $(CURDIR)/recordings
@@ -14,6 +14,10 @@ $(RECORDING_DIR):
 # 1. Convert 3.1 → 3.0 since oapi-codegen doesn't support 3.1 yet (https://github.com/oapi-codegen/oapi-codegen/issues/373)
 # 2. Run oapi-codegen with our config (version pinned via go.mod tool directive)
 # 3. go mod tidy to pull deps
+runtime-typecheck:
+	npm ci --ignore-scripts --no-audit --no-fund --prefix ./runtime
+	npm run typecheck --prefix ./runtime
+
 oapi-generate:
 	pnpm i -g @apiture/openapi-down-convert
 	openapi-down-convert --input openapi.yaml --output openapi-3.0.yaml --allOf
@@ -39,7 +43,7 @@ test-unit:
 	go vet ./...
 	go test -v -race $$(go list ./... | grep -v /e2e$$)
 
-test-runtime:
+test-runtime: runtime-typecheck
 	node --test runtime/*.test.ts
 
 test-e2e:

server/README.md

@@ -73,6 +73,77 @@ export OUTPUT_DIR=/tmp/recordings
 - **YAML Spec**: `GET /spec.yaml`
 - **JSON Spec**: `GET /spec.json`
 
+### Browser REPL
+
+`POST /repl` evaluates JavaScript in the Browser REPL, a persistent Node.js
+runtime preloaded with browser-control helpers and an unrestricted `cdp()`
+escape hatch. See [`docs/repl.md`](docs/repl.md) for the execution model,
+output guidance, examples, failure semantics, limits, and a reference for every
+helper.
+
+- The runtime starts lazily on the first request and is owned directly by the
+  API process. API restart/shutdown kills it (with Linux parent-death
+  signaling as a backstop); an API restart therefore loses all REPL state.
+- Each REPL process gets a CUID2 `repl_id`, returned in every response. It is
+  stable across calls and Chromium reconnects, and changes after an API
+  restart, `reset: true`, an execution timeout, or a REPL crash.
+- Top-level `await`, persistent `let`/`const`/`var`/function/class bindings,
+  and dynamic `import()` are supported.
+  Persistent names are live context-global accessors, so closures and timers
+  observe later-cell assignments. Function declarations are lowered through
+  those accessors too, including same-cell closures and assignments. `var`
+  declarations in top-level nested statements persist, including object/array
+  rest destructuring and `for...of` declaration heads; locals inside functions
+  or nested lexical blocks do not.
+  Braceless multi-declarator `var` statements retain their single-statement
+  control-flow semantics. Lexical names are reserved after linking: retry a
+  failed declaration with a new name or use `reset: true`. Function `.name` is
+  preserved; `Function.prototype.toString()` may expose the generated internal
+  alias. Static top-level imports are rejected; use dynamic `import()` instead.
+  Expression values are not returned automatically: use `repl.write(...)` for
+  final text and `repl.emitImage(...)` for images. Console methods are captured
+  for debugging and intermediate values. Top-level `return` is rejected.
+- A timeout is destructive (JavaScript cannot be interrupted safely): the API
+  kills the REPL process group and responds with `repl_terminated: true` and
+  the terminated REPL's ID. The next request lazily starts a fresh REPL.
+- Output is an ordered `content` array of typed items: text (`write` =
+  `repl.write`, `stdout` = `console.log/info/debug/dir/table`, `stderr` =
+  `console.warn/error/trace`) and images (`repl.emitImage`, base64 with MIME
+  sniffing). Limits: 8 MiB per image, 16 MiB aggregate image data, and 256 KiB
+  combined text per response. An oversized individual image throws; aggregate
+  output truncation sets `content_truncated`. Stray
+  output, including images emitted between executions, is capped at 1,000
+  items and reports `content_truncated` when older items are discarded.
+  Request bodies are limited to 8 MiB before strict decoding, and the API
+  rejects any marshaled daemon request that would exceed
+  the daemon's 8 MiB newline-delimited request-line limit without terminating
+  the REPL. HTML-sensitive code is sent without JSON HTML escaping.
+- `captureScreenshot()` stays file-oriented (returns a VM path); emit it
+  explicitly with `await repl.emitImage({ path })`.
+- Helpers are exposed as bare globals and on the frozen `browser` namespace.
+  See [`docs/repl.md`](docs/repl.md#browser-helpers) for every helper's
+  signature and behavior.
+- Pinned `patchright` and `playwright-core` packages are available through
+  dynamic `import()`. Patchright matches the image's default Playwright
+  execution engine. Connect either package to `process.env.CDP_ENDPOINT` to
+  use ordinary browser, context, and page objects as persistent REPL bindings;
+  reconnect those objects explicitly after Chromium restarts. Other packages
+  installed through `/process/exec` with `npm install -g package@version` are
+  available to bare dynamic `import("package")` calls.
+- The REPL connects to the browser through the DevTools proxy on
+  `ws://127.0.0.1:9222`, lazily on the first browser helper call; pure
+  Node.js code runs fine while Chromium is down, and the connection is
+  re-established automatically after a Chromium restart.
+
+**Security**: this endpoint is unrestricted code execution inside the browser
+VM (filesystem, network, processes, environment), equivalent in trust level
+to the process and Playwright execution APIs. The `vm` context is a state
+container, not a sandbox.
+
+The daemon sources live in `server/runtime/` (`browser-repl.ts`,
+`browser-cdp-client.ts`, `browser-helpers.ts`) and are bundled to
+`/usr/local/lib/browser-repl.js` in both browser images.
+
 ## 🔧 Development
 
 ### Code Generation

server/cmd/api/api/api.go

@@ -84,6 +84,8 @@ type ApiService struct {
 	// playwrightDaemonCmd holds the daemon process for cleanup
 	playwrightDaemonCmd *exec.Cmd
 
+	browserRepl *browserReplManager
+
 	webmcp webMCPClient
 
 	// policy management
@@ -169,6 +171,7 @@ func New(
 		cdpMonitor:        mon,
 		otlpExport:        otlpExport,
 		webmcp:            webmcpclient.NewManager(upstreamMgr),
+		browserRepl:       newBrowserReplManager(),
 		lifecycleCtx:      ctx,
 		lifecycleCancel:   cancel,
 	}, nil
@@ -431,6 +434,8 @@ func (s *ApiService) ListRecorders(ctx context.Context, _ oapi.ListRecordersRequ
 }
 
 func (s *ApiService) Shutdown(ctx context.Context) error {
+	replErr := s.browserRepl.Shutdown(ctx)
+
 	_ = s.webmcp.Close()
 	s.monitorMu.Lock()
 	s.lifecycleCancel()
@@ -439,5 +444,5 @@ func (s *ApiService) Shutdown(ctx context.Context) error {
 	s.monitorMu.Unlock()
 	// The OTLP export sink is stopped by main after the servers drain, so any
 	// events they emit on the way down are still exported (mirrors s2Writer).
-	return s.recordManager.StopAll(ctx)
+	return errors.Join(replErr, s.recordManager.StopAll(ctx))
 }