Host Bridge

Use createHostBrowserBridge when the product owns the visible browser surface. This is the right pattern for Forge-style apps, Electron shells, Tauri shells, and web apps with a dedicated browser panel.

Production Shape

Product UI
  -> host bridge
  -> embedded/CDP/extension/Playwright backend
  -> agent runtime
  -> event and artifact stores

The host app owns identity, permissions, layout, tabs, persistence, and teardown. Agent Browser owns the stable browser API and backend adapter contract.

Bridge Setup

import { createAgentBrowserRuntime } from "@cmmd-center/agent-browser";
import { EmbeddedBrowserBackend } from "@cmmd-center/agent-browser/embedded";
import { createEmbeddedBrowserHost } from "@cmmd-center/agent-browser/embedded-host";
import { createHostBrowserBridge } from "@cmmd-center/agent-browser/host";

const embeddedHost = createEmbeddedBrowserHost({ backend: appOwnedBrowserBackend });

const runtime = createAgentBrowserRuntime({
  backends: {
    embedded: new EmbeddedBrowserBackend({ transport: embeddedHost })
  }
});

const bridge = createHostBrowserBridge({
  runtime,
  browserId: "embedded",
  defaultSessionId: "default",
  onVisibilityChange: ({ sessionId, visibility }) => {
    browserPanelStore.setVisibility(sessionId, visibility);
  }
});

Session Flow

const session = await bridge.openSession({
  sessionId: "thread-123",
  initialUrl: "https://docs.cmmd.ai",
  visibility: "visible"
});

const unsubscribe = bridge.onEvent(
  { sessionId: session.sessionId },
  (event) => browserPanelStore.apply(event)
);

await bridge.command({
  sessionId: session.sessionId,
  command: { type: "navigate", url: "https://example.com" }
});

unsubscribe();
await bridge.closeSession({ sessionId: session.sessionId });

Commands

The bridge supports normal browser chrome controls, page actions, observation commands, and session UI commands:

Command	Use
navigate, reload, goBack, goForward	Browser navigation.
newTab, activateTab, closeTab	Tab lifecycle.
snapshot, screenshot, consoleLogs	Observation and artifacts.
click, type, scroll	Page actions.
setViewport, resetViewport	Viewport control.
setVisibility, nameSession	Product session state.
clearBrowsingData	Cache and cookie cleanup.

Events

The bridge emits session lifecycle, screenshot, snapshot, console log, and failed command events. UI consumers should subscribe by sessionId so one thread cannot accidentally receive another thread’s browser events.

Production hosts should use durable stores when sessions need replay across process restarts.