Add persistent Browser REPL API

[rgarcia]

A persistent JavaScript control plane for every Kernel browser

This PR adds POST /repl: a stateful Browser REPL that lives alongside Chromium inside each browser VM.

Instead of sending a complete automation program on every call—or rebuilding state from serialized results—an agent can teach the browser instance reusable JavaScript once, call it incrementally, inspect rendered state, and keep going:

const browser = await kernel.browsers.create();

await browser.repl({
  code: `
    async function search(query) {
      await fillInput('input[aria-label="Search"]', query);
      await pressKey("ENTER");
      if (!await waitForElement("main", {state: "visible", timeoutSec: 15})) {
        throw new Error("results did not render");
      }
    }
  `,
});

await browser.repl({code: `await search("Kernel browsers")`});

The result is a compact, agent-native control surface with:

• persistent JavaScript declarations and closures across calls
• direct browser interaction without requiring a separate automation framework
• exact-once page-function evaluation
• semantic waits and actionability-aware input
• unrestricted CDP, tab, target, iframe, filesystem, process, and network access
• deterministic lifecycle and failure semantics

The API

POST /repl
Content-Type: application/json

{
  "code": "const info = await pageInfo(); repl.write(info.title)",
  "timeout_sec": 60,
  "reset": false
}

Successful responses identify the exact state-holding process and contain ordered, typed output:

{
  "success": true,
  "repl_id": "<cuid2>",
  "duration_ms": 12,
  "content_truncated": false,
  "content": [
    {
      "type": "text",
      "channel": "write",
      "text": "Example Domain"
    }
  ]
}

The endpoint is scoped to an individual browser instance, so the intended generated SDK surface is:

await browser.repl({code});

rather than exposing details of the instance transport.

Why persistence matters

Each request is evaluated as a fresh JavaScript module cell, while top-level bindings remain live across subsequent cells:

// Cell 1
let searches = 0;
const selectors = {
  query: 'input[aria-label="Search"]',
  results: "main",
};

async function runSearch(query) {
  searches++;
  await fillInput(selectors.query, query);
  await pressKey("ENTER");
  return waitForElement(selectors.results, {
    state: "visible",
    timeoutSec: 15,
  });
}

// Cell 2
const ready = await runSearch("cloud browser");
repl.write(JSON.stringify({ready, searches}));

The runtime preserves var, let, const, function, and class bindings; mutation; closures; timers; destructuring; function hoisting; TDZ behavior; and partial initialization semantics. Top-level await and dynamic import() are supported.

This is deliberately JavaScript-only. TypeScript, static imports/exports, and top-level return are rejected.

Browser control built in

Helpers are available as bare globals and through the frozen browser namespace:

await gotoUrl("https://example.com");
await browser.gotoUrl("https://example.com");

The surface covers:

Area	Helpers
Navigation and state	gotoUrl, pageInfo, waitForLoad, waitForNetworkIdle
Interaction	click, fillInput, typeText, pressKey, scroll, dispatchKey
Page evaluation	js
Tabs and targets	listTabs, currentTab, switchTab, newTab, closeTab, ensureRealTab, iframeTarget
Inspection and escape hatches	cdp, drainEvents, captureScreenshot, uploadFile, httpGet

WebMCP first, direct control when needed

The same frozen browser-wide client is available as webmcp and browser.webmcp:

const tools = await webmcp.listTools();
const search = tools.find(tool => tool.name === "search");

if (search) {
  const result = await webmcp.invokeTool(
    search.tool_ref,
    {query: "CVG to SFO"},
    {timeoutSec: 30},
  );
  repl.write(JSON.stringify(result));
}

This delegates to the existing Go WebMCP manager, which discovers native tools across every tab and embedded frame, owns live tool_ref routing, and preserves awaiting_submission and outcome_unknown safety. Frame-provided tools do not require switching the REPL's attached target.

WebMCP calls are scoped to the originating cell with AsyncLocalStorage and an execution-specific abort signal. HTTP waits are clamped below the destructive cell deadline, and finishing a cell aborts unfinished requests, so an unawaited invocation cannot leak into a later execution.

The intended automation ladder is: use page-declared WebMCP tools when available, semantic selector control otherwise, opt into Playwright Core when its broader API helps, use coordinates for visual interaction, and keep unrestricted CDP as the final escape hatch.

Playwright Core is an opt-in persistent library

The REPL ships a lockfile-pinned playwright-core package without downloading another browser. Users can dynamically import it, connect to the image's existing Chromium, and retain ordinary Playwright objects across cells:

var pw = await import("playwright-core");
var pwBrowser = await pw.chromium.connectOverCDP(process.env.CDP_ENDPOINT);
var pwContext = pwBrowser.contexts()[0];
var pwPage = pwContext.pages()[0] ?? await pwContext.newPage();

await pwPage.goto("https://example.com");
repl.write(await pwPage.title());

The native frozen browser namespace remains the default, so imported connections use names such as pwBrowser. Imported Playwright connections become stale when Chromium restarts and can reconnect explicitly within the same REPL while all other JavaScript state survives. Reset, timeout, crash, or API restart clears the connection and bindings with the rest of the REPL process.

One click API: semantic or coordinate

await click('button[aria-label="Search"]');
await click({x: 420, y: 315});

Selector clicks wait for one visible, enabled, stable, unobscured match, scroll it into view, hit-test it, and dispatch physical mouse input through Chromium. Coordinate clicks remain the direct computer-use escape hatch. Options support button, clickCount, and selector-only timeoutSec.

Semantic synchronization instead of blind sleeps

const ready = await waitForElement(
  '[role="option"][aria-label*="(SFO)"]',
  {state: "visible", timeoutSec: 10},
);

if (!ready) throw new Error("SFO option did not appear");

waitForElement() supports attached, detached, visible, and hidden. It considers all matches, so hidden responsive duplicates cannot mask visible controls. Expected polling timeouts return false; protocol and high-level contract failures throw.

Fast, exact-once page JavaScript

js() supports both direct expressions and serialized page functions:

const title = await js("document.title");

const data = await js(
  async ({selector, limit}) => {
    await Promise.resolve();
    return document.querySelector(selector)?.innerText.slice(0, limit) ?? null;
  },
  {arg: {selector: "main", limit: 1000}},
);

A submitted expression or function is invoked once—there is no parse-error fallback that can repeat side effects. Function mode naturally supports statements, await, and return. Arguments and results preserve arrays, plain objects, bigint, NaN, infinities, and -0.

Page functions do not capture Browser REPL closures; data crosses explicitly through options.arg.

Cross-origin and nested iframe control

Same-origin frames are available through iframe.contentDocument. Cross-site frames commonly run as separate Chromium targets and can be inspected without relying on top-page same-origin access:

const frame = await iframeTarget("checkout.example");
if (!frame) throw new Error("checkout frame not found");

const heading = await js(
  () => document.querySelector("h1")?.textContent,
  {targetId: frame.targetId},
);

For physical selector interaction, attach to that target and restore the parent afterward:

const parent = await currentTab();
const frame = await iframeTarget("checkout.example");

try {
  await switchTab(frame.targetId);
  await fillInput('input[name="cardholder"]', "Jane Doe");
  await click('button[aria-label="Continue"]');
} finally {
  await switchTab(parent.targetId);
}

For lower-level frame cases, callers retain unrestricted access to Page.getFrameTree, Page.createIsolatedWorld, Runtime.evaluate, and the rest of CDP.

Output is explicit, optional, and ordered

Expression values are intentionally ignored. Successful code may produce no output or combine several channels:

repl.write("structured answer");
console.log("diagnostic output");
console.error("warning output");

const path = await captureScreenshot("/tmp/page.png");
await repl.emitImage({path});

The response preserves call order across:

• write text
• captured stdout
• captured stderr
• PNG, JPEG, or WebP image content

Screenshots remain file-oriented unless explicitly emitted. Output and protocol limits are bounded, and truncation is reported with content_truncated.

Failure and lifecycle contract

The API process directly owns one lazily started Node child and is its sole supervisor.

Event	JavaScript state	repl_id
Successful call	Preserved	Unchanged
Syntax error or ordinary exception	Preserved	Unchanged
Chromium restart	Preserved; browser reconnects lazily	Unchanged
Explicit reset	Cleared	Replaced
Execution timeout	Child process group destroyed	Replaced on next request
Crash, OOM, uncaught asynchronous exception, or protocol corruption	Child process group destroyed	Replaced on next request

Timeouts are destructive because abandoned JavaScript cannot safely coexist with a later cell. A destructive failure response carries the terminated repl_id; the replacement process starts only on the next request.

Calls are serialized so executions cannot interleave. Clients that require a specific sequence should await each call because strict request-arrival FIFO ordering is not part of the public contract.

Architecture

SDK / HTTP client
      │
      ▼
POST /repl
      │
      ▼
kernel-images API ── owns lifecycle, timeout, reset, serialization
      │ Unix socket / newline-delimited JSON
      ▼
persistent Node runtime
      │
      ├── vm.SourceTextModule cells + live context-global bindings
      ├── explicit text/image output collection
      └── persistent CDP client
              │
              ▼
       DevTools proxy :9222 → Chromium :9223

Meriyah analyzes declarations and binding patterns. Each cell is lowered to live context-global accessors, preserving binding identity rather than copying snapshots between modules. vm.SyntheticModule adapts dynamic imports into the cell context.

Chromium connectivity is lazy: pure Node code still works while the browser is unavailable, and a Chromium restart does not discard JavaScript state.

Security model

This endpoint is deliberately unrestricted remote code execution inside the browser VM.

vm.Context is a state container, not a sandbox. Code can access Node built-ins, installed packages, files, environment variables, processes, the network, and unrestricted CDP.

Integrity comes from process and protocol boundaries rather than pretending evaluation is isolated:

• API-owned process groups and Linux parent-death signaling
• destructive recovery after unsafe failures
• strict request decoding and bounded request/response sizes
• private serializer references resilient to prototype pollution
• heap limits and explicit output caps
• protocol traffic kept off process stdout

Validation

Automated coverage includes:

• declaration persistence, mutation, redeclaration, TDZ, closures, destructuring, partial failure, top-level await, dynamic import, and reset
• stable/new repl_id behavior across normal calls, browser restart, timeout, crash, OOM, and API shutdown
• zero-output execution, ordered mixed content, image handling, pollution resistance, and output limits
• exact-once js() execution and page-value serialization
• keyboard normalization through a self-contained US layout
• actionability-aware selector clicking and filling with hidden responsive duplicates
• attached, detached, visible, and hidden waits
• nested cross-origin iframe target evaluation and physical selector input
• browser-wide WebMCP discovery/invocation delegation, shared frozen namespace identity, and per-execution cancellation
• pinned Playwright Core import, live CDP control, cross-cell object identity, and explicit reconnection after Chromium restart
• tabs, dialogs, browser reconnects, uploads, screenshots, network idle, raw CDP, and event draining
• OpenAPI generation with SSE regression checks
• both Chromium image variants

Commands run locally after synchronizing with current main:

cd server && make test-runtime
cd server && go test ./cmd/api/api ./lib/oapi -count=1
cd server && go vet ./...
cd server && go test ./e2e -run '^$'

Live Docker E2E also passed for the Browser REPL suite, including selector actions, wait states, Chromium restart recovery, and cross-origin iframe control.

Three independent agents additionally completed rendered Google Flights searches through /repl, extracting and validating visible flight results without entering a booking flow.

Review map

• Public contract: server/openapi.yaml
• API ownership and lifecycle: server/cmd/api/api/browser_repl.go
• Persistent evaluator: server/runtime/browser-repl.ts, cell-runtime.ts, cell-analysis.ts
• Browser/CDP surface: server/runtime/browser-cdp-client.ts, browser-helpers.ts
• Page-function serialization: server/runtime/page-evaluation.ts
• Keyboard fidelity: server/runtime/us-keyboard-layout.ts
• Complete behavior reference: server/docs/repl.md
• Agent operational guidance: server/docs/repl-agent-guidance.md
• Architecture and invariants: plans/persistent-browser-repl.md

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	npm/​playwright-core@​1.62.1
	npm/​@​types/​node@​22.15.21
	npm/​sharp@​0.34.5
	npm/​typescript@​5.6.3
	npm/​meriyah@​7.3.1

View full report

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 9249def. Configure here.}