feat(sparsekernel): own brokered browser popups

Author: AbrahamGreenman

docs/architecture/browser-broker.md

@@ -19,7 +19,7 @@ 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`. 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.
+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, same-policy popups are attached as broker-owned targets, and disallowed popups are closed. 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.
 

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, 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.
+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; same-policy popups are attached as broker-owned targets and disallowed popups are closed. Screenshot and PDF outputs go through the artifact store.
 
 ## Sandbox broker
 

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

@@ -746,7 +746,7 @@ describe("@openclaw/sparsekernel-browser-broker", () => {
     expect(kernel.releasedContextIds).toEqual(["browser_ctx_1"]);
   });
 
-  it("closes new tabs opened by brokered actions instead of accepting unleased targets", async () => {
+  it("attaches same-policy tabs opened by brokered actions", async () => {
     const kernel = new FakeKernel();
     const transport = new FakeCdpTransport();
     const broker = new SparseKernelCdpBrowserBroker({
@@ -771,7 +771,39 @@ describe("@openclaw/sparsekernel-browser-broker", () => {
         kind: "click",
         selector: "#popup",
       }),
-    ).rejects.toThrow(/opened a new tab\/window/);
+    ).resolves.toMatchObject({ ok: true, kind: "click" });
+    await expect(broker.listTabs(context.ledger_context.id)).resolves.toEqual([
+      expect.objectContaining({ targetId: "target-1" }),
+      expect.objectContaining({ targetId: "target-popup" }),
+    ]);
+  });
+
+  it("closes new tabs that violate 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.queueActionNewTarget("https://blocked.example/popup", "target-popup");
+
+    await expect(
+      broker.actContext(context.ledger_context.id, {
+        kind: "click",
+        selector: "#popup",
+      }),
+    ).rejects.toThrow(/popup navigation blocked by allowed origins/);
     expect(transport.sent).toEqual(
       expect.arrayContaining([
         expect.objectContaining({

packages/browser-broker/src/index.ts

@@ -286,6 +286,11 @@ type CdpEventMessage = {
   sessionId?: string;
 };
 
+type LiveBrowserPage = {
+  target_id: string;
+  page_session_id: string;
+};
+
 type LiveBrowserContext = MaterializedBrowserContext & {
   connection: CdpConnection;
   page_session_id: string;
@@ -296,6 +301,7 @@ type LiveBrowserContext = MaterializedBrowserContext & {
   network_request_ids: Set<string>;
   last_network_activity_at: number;
   allowed_origins: string[];
+  pages: Map<string, LiveBrowserPage>;
 };
 
 const NETWORK_IDLE_QUIET_MS = 500;
@@ -393,6 +399,7 @@ export class SparseKernelCdpBrowserBroker {
         network_request_ids: new Set(),
         last_network_activity_at: Date.now(),
         allowed_origins: allowedOrigins,
+        pages: new Map([[targetId, { target_id: targetId, page_session_id: sessionId }]]),
       };
       connection.onEvent((event) => {
         recordConsoleEvent(materialized, event);
@@ -556,8 +563,8 @@ export class SparseKernelCdpBrowserBroker {
   ): Promise<{ ok: true; targetId: string }> {
     const context = this.requireContext(contextId);
     const targetId = input.target_id?.trim();
-    if (targetId && targetId !== context.target_id) {
-      throw new Error(`SparseKernel CDP browser context does not own target: ${targetId}`);
+    if (targetId) {
+      this.activateTarget(context, targetId);
     }
     if (input.paths.length === 0) {
       throw new Error("SparseKernel browser upload requires at least one file path.");
@@ -607,7 +614,21 @@ export class SparseKernelCdpBrowserBroker {
   }
 
   async listTabs(contextId: string): Promise<SparseKernelBrowserTab[]> {
-    return [await this.describeContextTab(this.requireContext(contextId))];
+    const context = this.requireContext(contextId);
+    const tabs: SparseKernelBrowserTab[] = [];
+    for (const page of context.pages.values()) {
+      tabs.push(await this.describePageTab(context, page));
+    }
+    return tabs;
+  }
+
+  async focusContext(
+    contextId: string,
+    input: { target_id: string },
+  ): Promise<SparseKernelBrowserTab> {
+    const context = this.requireContext(contextId);
+    this.activateTarget(context, input.target_id);
+    return await this.describeContextTab(context);
   }
 
   async snapshotContext(
@@ -670,8 +691,8 @@ export class SparseKernelCdpBrowserBroker {
     const context = this.requireContext(contextId);
     const targetId =
       "targetId" in request && typeof request.targetId === "string" ? request.targetId : undefined;
-    if (targetId && targetId !== context.target_id) {
-      throw new Error(`SparseKernel CDP browser context does not own target: ${targetId}`);
+    if (targetId) {
+      this.activateTarget(context, targetId);
     }
     switch (request.kind) {
       case "click":
@@ -898,7 +919,9 @@ export class SparseKernelCdpBrowserBroker {
     }
     this.contexts.delete(contextId);
     try {
-      await context.connection.command("Target.closeTarget", { targetId: context.target_id });
+      for (const targetId of context.pages.keys()) {
+        await context.connection.command("Target.closeTarget", { targetId }).catch(() => {});
+      }
       await context.connection.command("Target.disposeBrowserContext", {
         browserContextId: context.cdp_browser_context_id,
       });
@@ -919,6 +942,15 @@ export class SparseKernelCdpBrowserBroker {
     return context;
   }
 
+  private activateTarget(context: LiveBrowserContext, targetId: string): void {
+    const page = context.pages.get(targetId);
+    if (!page) {
+      throw new Error(`SparseKernel CDP browser context does not own target: ${targetId}`);
+    }
+    context.target_id = page.target_id;
+    context.page_session_id = page.page_session_id;
+  }
+
   private async navigate(
     context: LiveBrowserContext,
     url: string,
@@ -1057,12 +1089,22 @@ export class SparseKernelCdpBrowserBroker {
     observation: PostActionNavigationObservation | undefined,
   ): Promise<void> {
     if (observation?.kind === "new-target") {
-      await context.connection
-        .command("Target.closeTarget", { targetId: observation.targetId })
-        .catch(() => {});
-      throw new Error(
-        `SparseKernel browser action opened a new tab/window (${observation.targetId}); new targets are not accepted by the v0 broker.`,
-      );
+      try {
+        if (observation.url) {
+          assertUrlAllowedByOrigins(observation.url, context.allowed_origins, "popup navigation");
+        } else if (context.allowed_origins.length > 0) {
+          throw new Error(
+            `SparseKernel browser popup navigation blocked by allowed origins: target ${observation.targetId} did not report a URL`,
+          );
+        }
+      } catch (error) {
+        await context.connection
+          .command("Target.closeTarget", { targetId: observation.targetId })
+          .catch(() => {});
+        throw error;
+      }
+      await this.attachNewTarget(context, observation.targetId);
+      return;
     }
     if (observation?.kind === "same-target") {
       await context.connection
@@ -1089,7 +1131,40 @@ export class SparseKernelCdpBrowserBroker {
     return (await this.describeContextTab(context)).url;
   }
 
+  private async attachNewTarget(context: LiveBrowserContext, targetId: string): Promise<void> {
+    const existing = context.pages.get(targetId);
+    if (existing) {
+      this.activateTarget(context, targetId);
+      return;
+    }
+    const { sessionId } = await context.connection.command<{ sessionId: string }>(
+      "Target.attachToTarget",
+      {
+        flatten: true,
+        targetId,
+      },
+    );
+    await context.connection.command("Page.enable", {}, sessionId);
+    await context.connection.command("Runtime.enable", {}, sessionId);
+    await context.connection.command("Network.enable", {}, sessionId).catch(() => {});
+    await context.connection.command("Log.enable", {}, sessionId).catch(() => {});
+    context.pages.set(targetId, { target_id: targetId, page_session_id: sessionId });
+    context.target_id = targetId;
+    context.page_session_id = sessionId;
+    context.snapshot_refs = new Map();
+  }
+
   private async describeContextTab(context: LiveBrowserContext): Promise<SparseKernelBrowserTab> {
+    return await this.describePageTab(context, {
+      target_id: context.target_id,
+      page_session_id: context.page_session_id,
+    });
+  }
+
+  private async describePageTab(
+    context: LiveBrowserContext,
+    page: LiveBrowserPage,
+  ): Promise<SparseKernelBrowserTab> {
     let title: string | undefined;
     let url: string | undefined;
     try {
@@ -1101,7 +1176,7 @@ export class SparseKernelCdpBrowserBroker {
           expression: "JSON.stringify({ title: document.title, url: location.href })",
           returnByValue: true,
         },
-        context.page_session_id,
+        page.page_session_id,
       );
       const raw = evaluated.result?.value;
       if (typeof raw === "string") {
@@ -1113,8 +1188,8 @@ export class SparseKernelCdpBrowserBroker {
       // Best-effort tab metadata; target id is the durable handle for the lease.
     }
     return {
-      targetId: context.target_id,
-      suggestedTargetId: context.target_id,
+      targetId: page.target_id,
+      suggestedTargetId: page.target_id,
       ...(title ? { title } : {}),
       ...(url ? { url } : {}),
       type: "page",