feat(sparsekernel): wire browser broker client

Author: AbrahamGreenman

docs/architecture/browser-broker.md

@@ -13,7 +13,7 @@ The v0 daemon exposes broker endpoints to acquire, release, and list browser con
 
 V0 also has a concrete local-browser attachment point: callers may register and probe an existing loopback CDP endpoint such as `http://127.0.0.1:9222`. The broker validates that CDP endpoints are loopback-only, probes `/json/version`, stores the endpoint on the trust-zone pool, and records audit events. It still does not return raw CDP or Playwright handles to agents.
 
-The `@openclaw/sparsekernel-browser-broker` adapter materializes the ledger lease into a real CDP browser context with `Target.createBrowserContext`, creates a target for the task/session, captures screenshots through `Page.captureScreenshot`, and writes screenshots/downloads through the SparseKernel artifact API. Download capture uses CDP download events and the content-addressed artifact store rather than exposing arbitrary download paths to agents.
+The `@openclaw/sparsekernel-browser-broker` adapter materializes the ledger lease into a real CDP browser context with `Target.createBrowserContext`, creates a target for the task/session, captures screenshots through `Page.captureScreenshot`, and writes screenshots/downloads through the SparseKernel artifact API. Callers can construct it directly with a kernel-shaped client or use `createSparseKernelCdpBrowserBroker` to wire it to `sparsekerneld`. Download capture uses CDP download events and the content-addressed artifact store rather than exposing arbitrary download paths to agents.
 
 The current daemon does not launch or supervise a Playwright browser process yet. The next backend should:
 

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

@@ -7,7 +7,11 @@ import type {
   SparseKernelCreateArtifactInput,
 } from "../../sparsekernel-client/src/index.js";
 import type { CdpTransport, SparseKernelBrowserKernelClient } from "./index.js";
-import { normalizeLoopbackCdpEndpoint, SparseKernelCdpBrowserBroker } from "./index.js";
+import {
+  createSparseKernelCdpBrowserBroker,
+  normalizeLoopbackCdpEndpoint,
+  SparseKernelCdpBrowserBroker,
+} from "./index.js";
 
 class FakeKernel implements SparseKernelBrowserKernelClient {
   readonly artifactInputs: SparseKernelCreateArtifactInput[] = [];
@@ -264,4 +268,77 @@ describe("@openclaw/sparsekernel-browser-broker", () => {
       retention_policy: "durable",
     });
   });
+
+  it("constructs from the SparseKernel daemon client", async () => {
+    const calls: Array<{ url: string; body?: unknown }> = [];
+    const transport = new FakeCdpTransport();
+    const broker = createSparseKernelCdpBrowserBroker({
+      baseUrl: "http://127.0.0.1:8765",
+      fetchImpl: async (input, init) => {
+        const url = input.toString();
+        const body =
+          typeof init?.body === "string" ? (JSON.parse(init.body) as Record<string, string>) : {};
+        calls.push({ url, body });
+        if (url.endsWith("/browser/pools/probe")) {
+          return Response.json({
+            endpoint: body.cdp_endpoint,
+            reachable: true,
+            status_code: 200,
+          });
+        }
+        if (url.endsWith("/browser/contexts/acquire")) {
+          return Response.json({
+            id: "browser_ctx_client",
+            pool_id: "browser_pool_public_web",
+            profile_mode: "ephemeral",
+            status: "active",
+            created_at: "2026-04-27T00:00:00Z",
+          });
+        }
+        if (url.endsWith("/json/version")) {
+          return Response.json({
+            webSocketDebuggerUrl: "ws://127.0.0.1/devtools/browser/test",
+          });
+        }
+        if (url.endsWith("/artifacts/create")) {
+          return Response.json({
+            id: "artifact_client",
+            sha256: "sha_client",
+            size_bytes: Buffer.from(body.content_base64, "base64").length,
+            storage_ref: "sha256/aa/bb/sha_client",
+            mime_type: body.mime_type,
+            retention_policy: body.retention_policy,
+            created_at: "2026-04-27T00:00:00Z",
+          });
+        }
+        if (url.endsWith("/browser/contexts/release")) {
+          return Response.json({ released: true });
+        }
+        return Response.json({ error: "not found" }, { status: 404 });
+      },
+      transportFactory: async () => transport,
+    });
+
+    const context = await broker.acquireContext({
+      trust_zone_id: "public_web",
+      cdp_endpoint: "http://127.0.0.1:9222",
+    });
+    const screenshot = await broker.captureScreenshotArtifact(context.ledger_context.id);
+    await expect(broker.releaseContext(context.ledger_context.id)).resolves.toBe(true);
+
+    expect(screenshot.artifact.id).toBe("artifact_client");
+    expect(calls.map((call) => new URL(call.url).pathname)).toEqual(
+      expect.arrayContaining([
+        "/browser/pools/probe",
+        "/browser/contexts/acquire",
+        "/json/version",
+        "/artifacts/create",
+        "/browser/contexts/release",
+      ]),
+    );
+    expect(calls.find((call) => call.url.endsWith("/artifacts/create"))?.body).toMatchObject({
+      content_base64: Buffer.from("pixels").toString("base64"),
+      mime_type: "image/png",
+    });
+  });
 });

packages/browser-broker/src/index.ts

@@ -2,7 +2,18 @@ import { mkdtemp, readFile, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import WebSocket, { type RawData } from "ws";
-import type {
+import {
+  SparseKernelClient,
+  type SparseKernelClientOptions,
+  type SparseKernelAcquireBrowserContextInput,
+  type SparseKernelArtifact,
+  type SparseKernelArtifactSubject,
+  type SparseKernelBrowserContext,
+  type SparseKernelBrowserEndpointProbe,
+  type SparseKernelCreateArtifactInput,
+} from "../../sparsekernel-client/src/index.js";
+
+export type {
   SparseKernelAcquireBrowserContextInput,
   SparseKernelArtifact,
   SparseKernelArtifactSubject,
@@ -38,6 +49,10 @@ export type SparseKernelBrowserBrokerOptions = {
   transportFactory?: CdpTransportFactory;
 };
 
+export type SparseKernelCdpBrowserBrokerFactoryOptions = SparseKernelClientOptions & {
+  transportFactory?: CdpTransportFactory;
+};
+
 export type AcquireMaterializedBrowserContextInput = {
   agent_id?: string | null;
   session_id?: string | null;
@@ -81,6 +96,17 @@ export type BrowserArtifactResult = {
   source_url?: string;
 };
 
+export function createSparseKernelCdpBrowserBroker(
+  options: SparseKernelCdpBrowserBrokerFactoryOptions = {},
+): SparseKernelCdpBrowserBroker {
+  const client = new SparseKernelClient(options);
+  return new SparseKernelCdpBrowserBroker({
+    kernel: client,
+    fetchImpl: options.fetchImpl,
+    transportFactory: options.transportFactory,
+  });
+}
+
 type CdpResponseWaiter = {
   resolve: (value: unknown) => void;
   reject: (error: Error) => void;