AkurAI Build
Sign in with AkurAI ID
Menu

popagent

public

Latest change 8828a8233b015e0c6e7896c3e9ba8b060bd3ce5c - Add BifrOSt Navigator agent tool by Ólafur Búi Ólafsson

# Browser automation

Providers: open-source `@mastra/agent-browser` in fixed headless mode, plus 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.
- `bifrostNavigator` is available only to roles whose persisted `browserAccess` is not `none`; read-only roles may call only non-mutating BifrOSt operations. 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`.