popagent

Latest change da13a7bebe63bf4b2693180d2d4850aabeaa0807 - Add autonomous evolution and self-healing by AkurAI Build

# Browser automation

Provider: open-source `@mastra/agent-browser`, fixed headless mode. 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.

## 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/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`.