popagent

Latest change 98a9a832366ede73ff5e61d826d68af4f775db92 - Add safe autonomous deployment and complete project guidance 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.

## 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, and retained recordings. 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.

## Profiles and recordings

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, and routes.
- `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`.