Forge Integration

Forge should consume @cmmd-center/agent-browser as a private package. It should not vendor package source or bind Forge UI code to package internals.

Correct Boundary

Forge Browser UI
  -> EnvironmentApi.browser
  -> Forge browser manager
  -> createHostBrowserBridge
  -> Agent Browser backend

Forge owns the product experience: thread identity, sidebar state, permissions, Browser panel layout, persistence, and user-visible lifecycle. Agent Browser owns reusable browser control, backend adapters, events, artifacts, safety primitives, and client/server contracts.

Integration Steps

1. Install @cmmd-center/agent-browser from GitHub Packages.
2. Add a Forge-side EnvironmentApi.browser adapter.
3. Back that adapter with createHostBrowserBridge.
4. Map Forge thread/session IDs to Agent Browser session IDs.
5. Route sidebar Browser commands through bridge.command.
6. Subscribe to bridge events and update Forge browser state stores.
7. Store events and screenshots durably when thread replay matters.
8. Add Forge tests around session ownership, tab routing, event cleanup, and adapter errors.

Do This

import { createHostBrowserBridge } from "@cmmd-center/agent-browser/host";

const bridge = createHostBrowserBridge({
  runtime,
  browserId: "forge-browser",
  defaultSessionId: threadId
});

environmentApi.browser = {
  openSession: (input) => bridge.openSession(input),
  closeSession: (input) => bridge.closeSession(input),
  command: (input) => bridge.command(input),
  onEvent: (filter, listener) => bridge.onEvent(filter, listener)
};

Avoid This

• Do not import files from packages/agent-browser/src.
• Do not copy Agent Browser code into Forge.
• Do not expose embedded transport methods directly to untrusted page JavaScript.
• Do not use /preview as the production Forge Browser panel.
• Do not let commands run without threadId, sessionId, or browserId scoping.

Testing Focus

Forge integration tests should prove:

• opening a browser session creates the correct Forge sidebar state,
• commands route to the intended browser session,
• events update the right thread and do not cross sessions,
• closing a thread/session unsubscribes listeners and releases browser resources,
• safety failures and invalid commands surface visible errors,
• durable event/screenshot stores can replay browser state after reload.

The package tests prove the reusable contracts. Forge tests still need to prove Forge-specific wiring, UI state, and lifecycle behavior.