AkurAI Build
Sign in with AkurAI ID
Menu

popagent

public

Latest change 248b7c0673ea9d544f9e4738ee4d3e8ec2925924 - Add native BifrOSt Navigator browser provider with per-browser status LEDs by AkurAI Build

# Browser automation

Providers: open-source `@mastra/agent-browser` in fixed headless mode, plus an explicitly operator-assigned bridge to the user's visible local BifrOSt Navigator through its mode-0600 Unix MCP socket. Browser changes preserve request authentication, agent access classes, network policy, workspace containment, encrypted-profile handling, and lifecycle cleanup.

## Configuration and access

- `popagent_browser_settings` is the persisted source for global enablement, thread/shared scope, viewport and operation limits, idle/concurrency bounds, screencast, recording retention, capability groups, and host policy. Changes apply immediately without restart.
- Per-agent access in `popagent_agents` is `interactive`, `read-only`, or `none`.
- Read-only agents do not receive click, form/keyboard, close, tab-management, dialog, drag, evaluation, recording, or admin-input capabilities. Headless operation and these exclusions are fixed server boundaries, not writable settings.
- `POPAGENT_BROWSER_ALLOW` and `POPAGENT_BROWSER_DENY` optionally add environment-level host rules. Persisted policy remains canonical for user-managed rules.
- Trusted `executionSource='self-update'` receives no browser instance or browser
  tools regardless of persisted global or role access. Its forked supervisor and
  specialists explicitly clear prior browser bindings, and fixed tool policy
  rejects browser and `useBrowserSecret` calls below prompt and managed-hook
  control.
- `popagent_browser_settings.provider` selects the agent browser: `agent-browser` (default, headless `@mastra/agent-browser`) or `bifrost-navigator` (the user's visible local BifrOSt Navigator on this host). Under `bifrost-navigator` no headless browser is launched or attached, `useBrowserSecret` has no interactive browser to fill, the runtime/capability/recording/profile settings apply only to the headless provider, and `configuredTools` grants `bifrostNavigator` to every role whose persisted `browserAccess` is not `none` (still excluded under contained autonomy). Under `agent-browser` the tool is never assigned by default; an operator may explicitly add it to a profile only for work concerning the user's visible BifrOSt browser. In both cases it is available only to roles whose `browserAccess` is not `none`; read-only roles may call only non-mutating BifrOSt operations. `/api/browser/health` reports every provider's readiness (`providers[]`, rendered as green/red LEDs in Settings → Browser and re-polled every 15 s while that section is open): the headless provider is ready when its Playwright Chromium build exists; BifrOSt is ready when its socket answers `tools/list` with at least one tool (a socket that answers with zero tools means BifrOSt was started without `--allow-mcp-capability`). `/api/browser/test` exercises the selected provider; under BifrOSt it calls `browser_current_page`. It connects to `BIFROST_MCP_SOCKET` or `$XDG_RUNTIME_DIR/bifrost-navigator.sock`, optionally authenticates with `BIFROST_MCP_TOKEN`, preserves the MCP content envelope, aborts with the agent turn, and never starts or owns the desktop browser. Trusted self-update receives no BifrOSt tool.

## Network safety

Every browser request is intercepted before loading. Direct navigation, clicks, new tabs, history, and final redirects receive the same scheme, explicit deny/allow, private-address, DNS-resolution, and rebinding checks. Never weaken this boundary for a test or authenticated profile. A profile authenticates the browser to a destination; it does not authorize that destination through network policy.

## Sessions and APIs

Sessions are tracked per Mastra thread, bounded by concurrency and idle limits, and closed on permanent chat deletion or terminal task completion. Browser APIs cover persisted settings, provider health/test, active sessions, close/takeover/input, screencast, encrypted profiles, retained recordings, and metadata-only origin-bound credential management. API authentication applies to every route.

The chat panel is view-only until explicit takeover of an interactive session. Hiding it disables takeover. Desktop keeps browser and transcript side by side; mobile uses a focus-trapped full-screen dialog.

## Credentials, profiles, and recordings

Operator-provisioned credentials are encrypted in `popagent_secrets`; exact HTTPS
origin bindings are metadata in `popagent_secret_bindings`. `useBrowserSecret`
resolves plaintext only inside the server-side browser adapter, verifies both
the current page and target frame origin, fills the referenced element, and
returns metadata only. Interactive browser access and form capability are
required. Read-only roles, redirects to another origin, cross-origin frames,
stale refs, unbound credentials, and non-HTTPS origins fail closed.

Playwright storage-state profiles are encrypted in `popagent_secrets`; APIs expose metadata only. The active profile is materialized in a mode-0600 temporary directory for browser launch and removed when the runtime is replaced. Beta AVI recordings stay under `POPAGENT_DATA_DIR`, are path-contained, and are bounded by configured age and count. They may contain sensitive page content and are never committed.

Remote CDP providers and richer recording-to-thread/task/agent metadata are deliberately deferred until a concrete provider or stable Mastra lifecycle contract exists. Do not add hosted Browserbase, Stagehand, or Firecrawl dependencies speculatively.

## Contract ownership

- `src/browser-policy.test.ts` — host, private-address, DNS, redirect, and rebinding policy.
- `src/browser-settings.test.ts` and `src/settings-migrations.test.ts` — singleton configuration and migration semantics.
- `src/browser-sessions.test.ts` and `src/browser-api.test.ts` — lifecycle,
  access, screencast, takeover, cleanup, routes, and metadata-only secret APIs.
- `src/tools/secrets.test.ts` — encrypted bindings, strict origin validation,
  and model-invisible browser consumption.
- `src/tools/bifrost.test.ts` — local Unix transport, bounded MCP response handling, and role access enforcement.
- `src/browser-profiles.test.ts` — encryption, metadata-only APIs, and temporary materialization.
- `src/browser-recordings.test.ts` — containment and retention.
- `src/ui/browser-stream.test.ts` — client stream parsing and cancellation.

Browser UI changes additionally require the desktop/mobile browser gates in `AGENTS_RULES.md`. Browser security changes use `.agents/skills/popagent-browser-security/SKILL.md`.