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

@@ -409,6 +409,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

@@ -301,4 +301,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 repl-help-generate repl-help-check runtime-typecheck build dev test test-unit test-runtime test-e2e clean
 
 BIN_DIR ?= $(CURDIR)/bin
 RECORDING_DIR ?= $(CURDIR)/recordings
@@ -14,7 +14,17 @@ $(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
-oapi-generate:
+runtime-typecheck:
+	npm ci --ignore-scripts --no-audit --no-fund --prefix ./runtime
+	npm run typecheck --prefix ./runtime
+
+repl-help-generate:
+	node --no-warnings ./scripts/replhelp/main.mjs
+
+repl-help-check:
+	node --no-warnings ./scripts/replhelp/main.mjs --check
+
+oapi-generate: repl-help-generate
 	pnpm i -g @apiture/openapi-down-convert
 	openapi-down-convert --input openapi.yaml --output openapi-3.0.yaml --allOf
 	go tool oapi-codegen -config ./oapi-codegen.yaml ./openapi-3.0.yaml
@@ -39,7 +49,7 @@ test-unit:
 	go vet ./...
 	go test -v -race $$(go list ./... | grep -v /e2e$$)
 
-test-runtime:
+test-runtime: runtime-typecheck repl-help-check
 	node --test runtime/*.test.ts
 
 test-e2e:

server/README.md

@@ -72,6 +72,7 @@ export OUTPUT_DIR=/tmp/recordings
 
 - **YAML Spec**: `GET /spec.yaml`
 - **JSON Spec**: `GET /spec.json`
+- **Browser REPL guide**: [`docs/repl.md`](docs/repl.md)
 
 ## 🔧 Development
 

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))
 }