feat(sparsekernel): guard brokered browser navigation

Author: AbrahamGreenman

docs/architecture/browser-broker.md

@@ -19,8 +19,8 @@ When `OPENCLAW_RUNTIME_BROWSER_BROKER=cdp` and `OPENCLAW_SPARSEKERNEL_BROWSER_CD
 
 Set `OPENCLAW_RUNTIME_BROWSER_BROKER=native` to let SparseKernel launch and supervise a local Chromium-compatible process pool by trust zone and profile. The native pool uses a loopback-only remote debugging endpoint, a runtime-owned browser profile directory, and pooled process refcounts; the leased CDP context is released first, then the browser process is stopped after the pool idle timeout. Use `OPENCLAW_SPARSEKERNEL_BROWSER_EXECUTABLE` when Chrome/Chromium is not discoverable on `PATH` or a common platform path. Headless mode is on by default. `OPENCLAW_SPARSEKERNEL_BROWSER_NO_SANDBOX=1` is an explicit opt-out and should only be used when the host environment cannot run Chromium's sandbox.
 
-Supported v0 actions (`status`, `doctor`, `profiles`, `tabs`, `open`, `navigate`, `focus`, `close`, `snapshot`, `console`, `screenshot`, `pdf`, direct file-input `upload`, `dialog`, and brokered `act`) operate against the leased CDP context. Brokered `act` covers the OpenClaw action contract for click, coordinate click, type, press, hover, scroll, drag, select, fill, resize, wait, evaluate, close, and batch using CDP input events plus bounded DOM evaluation. Selector-backed actions retry inside the leased page until their action timeout, and `wait --load networkidle` uses CDP Network events plus a quiet window rather than only checking `document.readyState`. Snapshots use a bounded CDP `Runtime.evaluate` DOM read, actions resolve refs from the latest brokered snapshot where needed, console output is captured from CDP runtime/log events, and screenshot/PDF output is captured as SparseKernel artifacts, read back through artifact access, and converted to existing tool result formats for compatibility. The context is retained for the active embedded run and released during broker cleanup, not opened and closed for every browser tool call.
+Supported v0 actions (`status`, `doctor`, `profiles`, `tabs`, `open`, `navigate`, `focus`, `close`, `snapshot`, `console`, `screenshot`, `pdf`, direct file-input `upload`, `dialog`, and brokered `act`) operate against the leased CDP context. Brokered `act` covers the OpenClaw action contract for click, coordinate click, type, press, hover, scroll, drag, select, fill, resize, wait, evaluate, close, and batch using CDP input events plus bounded DOM evaluation. Selector-backed actions retry inside the leased page until their action timeout, and `wait --load networkidle` uses CDP Network events plus a quiet window rather than only checking `document.readyState`. Actions that can change page state are followed by a broker-side navigation check: same-target navigations are accepted only when the resulting URL stays inside the context's allowed-origin policy, while new tabs/windows are closed and rejected in v0 because they are unleased targets. Snapshots use a bounded CDP `Runtime.evaluate` DOM read, actions resolve refs from the latest brokered snapshot where needed, console output is captured from CDP runtime/log events, and screenshot/PDF output is captured as SparseKernel artifacts, read back through artifact access, and converted to existing tool result formats for compatibility. The context is retained for the active embedded run and released during broker cleanup, not opened and closed for every browser tool call.
 
 BrowserContext isolation is session isolation, not host isolation. Playwright route blocking is useful request control, not a hard security boundary.
 
-The brokered CDP action engine is intentionally implemented inside the broker boundary, but it is not a byte-for-byte Playwright clone. Behaviors that depend on Playwright's full actionability checks, locator retry model, navigation guard, or network-idle semantics should still be covered by targeted tests before relying on them for critical automations. Set `OPENCLAW_SPARSEKERNEL_BROWSER_LIVE=1` when running `src/local-kernel/browser-cdp-live.test.ts` to exercise the native pool and brokered actions against a real local Chromium-compatible browser.
+The brokered CDP action engine is intentionally implemented inside the broker boundary, but it is not a byte-for-byte Playwright clone. Behaviors that depend on Playwright's full actionability checks, locator retry model, popup ownership, or network-idle semantics should still be covered by targeted tests before relying on them for critical automations. Set `OPENCLAW_SPARSEKERNEL_BROWSER_LIVE=1` when running `src/local-kernel/browser-cdp-live.test.ts` to exercise the native pool and brokered actions against a real local Chromium-compatible browser.

docs/architecture/local-agent-kernel.md

@@ -96,7 +96,7 @@ The browser broker model is:
 
 Important boundary: BrowserContext isolation is session isolation, not host isolation. Playwright route blocking and SSRF guards are useful controls, but they are not hard security boundaries.
 
-The broker applies configured trust-zone network policy to explicit allowed origins before allocating a context. This is an egress guard for brokered contexts, not a kernel or VM boundary. Set `OPENCLAW_RUNTIME_BROWSER_BROKER=cdp` and `OPENCLAW_SPARSEKERNEL_BROWSER_CDP_ENDPOINT=<loopback endpoint>` to make the OpenClaw browser tool acquire a real SparseKernel CDP context for the active run. Set `OPENCLAW_RUNTIME_BROWSER_BROKER=managed` to use the existing OpenClaw browser control service as the managed process owner and let SparseKernel lease CDP contexts from its reported endpoint. Set `OPENCLAW_RUNTIME_BROWSER_BROKER=native` to let SparseKernel launch and supervise a local Chromium-compatible process pool keyed by trust zone/profile, with process lifetime tied to brokered context leases and idle timeout. The runtime injects an internal browser proxy for supported navigation, tab, snapshot, console, screenshot, PDF, direct file-input upload, dialog, and action routes instead of exposing raw CDP to the agent. Brokered actions cover the OpenClaw action contract with CDP input events, bounded DOM evaluation, selector retry, and CDP-backed network-idle waiting; screenshot and PDF outputs go through the artifact store.
+The broker applies configured trust-zone network policy to explicit allowed origins before allocating a context. This is an egress guard for brokered contexts, not a kernel or VM boundary. Set `OPENCLAW_RUNTIME_BROWSER_BROKER=cdp` and `OPENCLAW_SPARSEKERNEL_BROWSER_CDP_ENDPOINT=<loopback endpoint>` to make the OpenClaw browser tool acquire a real SparseKernel CDP context for the active run. Set `OPENCLAW_RUNTIME_BROWSER_BROKER=managed` to use the existing OpenClaw browser control service as the managed process owner and let SparseKernel lease CDP contexts from its reported endpoint. Set `OPENCLAW_RUNTIME_BROWSER_BROKER=native` to let SparseKernel launch and supervise a local Chromium-compatible process pool keyed by trust zone/profile, with process lifetime tied to brokered context leases and idle timeout. The runtime injects an internal browser proxy for supported navigation, tab, snapshot, console, screenshot, PDF, direct file-input upload, dialog, and action routes instead of exposing raw CDP to the agent. Brokered actions cover the OpenClaw action contract with CDP input events, bounded DOM evaluation, selector retry, CDP-backed network-idle waiting, and post-action navigation checks. Same-target action navigations must stay inside the context's allowed origins when a policy is configured; new tabs/windows are closed and rejected until the broker owns a multi-tab lease model. Screenshot and PDF outputs go through the artifact store.
 
 ## Sandbox broker
 
@@ -138,7 +138,7 @@ Session metadata writes are mirrored into the runtime ledger by default. Set `OP
 ## Current limitations
 
 - Full transcript ownership is still staged: session metadata can run with SQLite as primary, assistant transcript mirrors and import/export are ledger-backed, and the pi session manager still appends JSONL.
-- Native browser process pooling exists for loopback CDP contexts, but it is still a small supervisor around Chromium. Brokered actions now cover selector retry and CDP-backed network-idle waits, but the engine is still not a full Playwright-equivalent process manager and does not provide host isolation.
+- Native browser process pooling exists for loopback CDP contexts, but it is still a small supervisor around Chromium. Brokered actions now cover selector retry, CDP-backed network-idle waits, and post-action navigation checks, but the engine is still not a full Playwright-equivalent process manager and does not provide host isolation.
 - Sandbox allocation records requested bwrap/minijail/Docker backends and checks availability, but local/no-isolation still does not harden execution.
 - Native plugins still execute in process; tool invocation is brokered and audited but untrusted plugin isolation is a later process-boundary change.
 - Network policy enforcement currently exists where brokers call it; host-level egress proxying is still future work.

packages/browser-broker/src/index.test.ts

@@ -65,6 +65,8 @@ class FakeCdpTransport implements CdpTransport {
   private readonly errorListeners: Array<(error: Error) => void> = [];
   private downloadPath: string | undefined;
   private currentUrl = "about:blank";
+  private nextActionNavigationUrl: string | undefined;
+  private nextActionNewTarget: { targetId: string; url: string } | undefined;
 
   send(data: string): void {
     const message = JSON.parse(data) as {
@@ -89,6 +91,7 @@ class FakeCdpTransport implements CdpTransport {
       case "Runtime.enable":
       case "Network.enable":
       case "Log.enable":
+      case "Target.setDiscoverTargets":
         this.respond(message.id, {});
         break;
       case "Browser.setDownloadBehavior":
@@ -189,6 +192,14 @@ class FakeCdpTransport implements CdpTransport {
     });
   }
 
+  queueActionNavigation(url: string): void {
+    this.nextActionNavigationUrl = url;
+  }
+
+  queueActionNewTarget(url: string, targetId = "target-popup"): void {
+    this.nextActionNewTarget = { targetId, url };
+  }
+
   private respondRuntimeEvaluate(message: { id: number; params?: Record<string, unknown> }): void {
     const expression = String(message.params?.expression ?? "");
     if (expression.includes("const links =")) {
@@ -237,6 +248,22 @@ class FakeCdpTransport implements CdpTransport {
       });
       return;
     }
+    if (expression.includes("waitForActionTarget")) {
+      const navigationUrl = this.nextActionNavigationUrl;
+      const newTarget = this.nextActionNewTarget;
+      this.nextActionNavigationUrl = undefined;
+      this.nextActionNewTarget = undefined;
+      this.respond(message.id, {
+        result: { value: { ok: true } },
+      });
+      if (navigationUrl) {
+        setTimeout(() => this.emitFrameNavigation(navigationUrl), 0);
+      }
+      if (newTarget) {
+        setTimeout(() => this.emitNewTarget(newTarget.targetId, newTarget.url), 0);
+      }
+      return;
+    }
     this.respond(message.id, {
       result: { value: { ok: true } },
     });
@@ -295,6 +322,41 @@ class FakeCdpTransport implements CdpTransport {
       });
     }, 0);
   }
+
+  private emitFrameNavigation(url: string): void {
+    this.currentUrl = url;
+    this.emit({
+      method: "Page.frameNavigated",
+      params: {
+        frame: {
+          id: "frame-1",
+          url,
+        },
+      },
+      sessionId: "session-1",
+    });
+    setTimeout(() => {
+      this.emit({
+        method: "Page.loadEventFired",
+        params: {},
+        sessionId: "session-1",
+      });
+    }, 0);
+  }
+
+  private emitNewTarget(targetId: string, url: string): void {
+    this.emit({
+      method: "Target.targetCreated",
+      params: {
+        targetInfo: {
+          targetId,
+          type: "page",
+          browserContextId: "cdp-context-1",
+          url,
+        },
+      },
+    });
+  }
 }
 
 describe("@openclaw/sparsekernel-browser-broker", () => {
@@ -623,6 +685,106 @@ describe("@openclaw/sparsekernel-browser-broker", () => {
     );
   });
 
+  it("accepts same-origin post-action navigation within the context policy", async () => {
+    const kernel = new FakeKernel();
+    const transport = new FakeCdpTransport();
+    const broker = new SparseKernelCdpBrowserBroker({
+      kernel,
+      fetchImpl: async () =>
+        Response.json({
+          webSocketDebuggerUrl: "ws://127.0.0.1/devtools/browser/test",
+        }),
+      transportFactory: async () => transport,
+    });
+
+    const context = await broker.acquireContext({
+      trust_zone_id: "public_web",
+      cdp_endpoint: "http://127.0.0.1:9222",
+      initial_url: "https://example.com/start",
+      allowed_origins: ["https://example.com"],
+    });
+    transport.queueActionNavigation("https://example.com/next");
+
+    await expect(
+      broker.actContext(context.ledger_context.id, {
+        kind: "click",
+        selector: "#continue",
+      }),
+    ).resolves.toMatchObject({ ok: true, kind: "click" });
+    await expect(broker.listTabs(context.ledger_context.id)).resolves.toEqual([
+      expect.objectContaining({ url: "https://example.com/next" }),
+    ]);
+  });
+
+  it("releases a context when post-action navigation leaves the allowed origins", async () => {
+    const kernel = new FakeKernel();
+    const transport = new FakeCdpTransport();
+    const broker = new SparseKernelCdpBrowserBroker({
+      kernel,
+      fetchImpl: async () =>
+        Response.json({
+          webSocketDebuggerUrl: "ws://127.0.0.1/devtools/browser/test",
+        }),
+      transportFactory: async () => transport,
+    });
+
+    const context = await broker.acquireContext({
+      trust_zone_id: "public_web",
+      cdp_endpoint: "http://127.0.0.1:9222",
+      initial_url: "https://example.com/start",
+      allowed_origins: ["https://example.com"],
+    });
+    transport.queueActionNavigation("https://blocked.example/next");
+
+    await expect(
+      broker.actContext(context.ledger_context.id, {
+        kind: "click",
+        selector: "#escape",
+      }),
+    ).rejects.toThrow(/post-action navigation blocked by allowed origins/);
+    await expect(broker.listTabs(context.ledger_context.id)).rejects.toThrow(/not materialized/);
+    expect(kernel.releasedContextIds).toEqual(["browser_ctx_1"]);
+  });
+
+  it("closes new tabs opened by brokered actions instead of accepting unleased targets", async () => {
+    const kernel = new FakeKernel();
+    const transport = new FakeCdpTransport();
+    const broker = new SparseKernelCdpBrowserBroker({
+      kernel,
+      fetchImpl: async () =>
+        Response.json({
+          webSocketDebuggerUrl: "ws://127.0.0.1/devtools/browser/test",
+        }),
+      transportFactory: async () => transport,
+    });
+
+    const context = await broker.acquireContext({
+      trust_zone_id: "public_web",
+      cdp_endpoint: "http://127.0.0.1:9222",
+      initial_url: "https://example.com/start",
+      allowed_origins: ["https://example.com"],
+    });
+    transport.queueActionNewTarget("https://example.com/popup", "target-popup");
+
+    await expect(
+      broker.actContext(context.ledger_context.id, {
+        kind: "click",
+        selector: "#popup",
+      }),
+    ).rejects.toThrow(/opened a new tab\/window/);
+    expect(transport.sent).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          method: "Target.closeTarget",
+          params: expect.objectContaining({ targetId: "target-popup" }),
+        }),
+      ]),
+    );
+    await expect(broker.listTabs(context.ledger_context.id)).resolves.toEqual([
+      expect.objectContaining({ targetId: "target-1" }),
+    ]);
+  });
+
   it("performs the broader brokered action contract against the leased context", async () => {
     const kernel = new FakeKernel();
     const transport = new FakeCdpTransport();
@@ -740,7 +902,10 @@ describe("@openclaw/sparsekernel-browser-broker", () => {
         (message as { method?: unknown }).method === "Runtime.evaluate" &&
         typeof (message as { params?: { expression?: unknown } }).params?.expression === "string",
     );
-    const actionExpression = runtimeEvaluations.at(-1)?.params.expression ?? "";
+    const actionExpression =
+      runtimeEvaluations.find((message) =>
+        message.params.expression.includes("waitForActionTarget"),
+      )?.params.expression ?? "";
     expect(actionExpression).toContain("waitForActionTarget");
     expect(actionExpression).toContain("const timeoutMs = 1234");
     expect(actionExpression).toContain("document.querySelector(selector)");