agentmb 0.3.1 → 0.3.2

package/skills/agentmb/references/authentication.md

@@ -0,0 +1,180 @@
+# Authentication — Deep Reference
+
+---
+
+## Human Login Handoff
+
+Switch a headless session to headed (visible) mode, log in manually, then return to headless automation with the same cookies and storage intact.
+
+```bash
+# Step 1: Start daemon and create a session (can be existing profile)
+agentmb session new --profile myaccount
+
+# Step 2: Open the browser window for manual login
+agentmb login <session-id>
+# → browser window opens
+# → navigate to the site and log in manually
+# → press Enter in terminal when done
+# → session returns to headless mode with cookies preserved
+```
+
+Python SDK:
+```python
+sess = client.sessions.create(profile="myaccount", headless=False)
+# ... navigate to the site manually via headed browser ...
+# (no SDK equivalent for the interactive login flow — use CLI `agentmb login`)
+```
+
+After login, subsequent sessions created with the same `--profile` name automatically have the saved cookies.
+
+---
+
+## Profile Persistence
+
+### Agent Workspace (Named Profile)
+
+Cookies, localStorage, IndexedDB, and browser state are saved to `AGENTMB_DATA_DIR/profiles/<name>/`.
+
+```bash
+agentmb session new --profile gmail-account
+# cookies and state saved to ~/.agentmb/profiles/gmail-account/
+```
+
+Reuse in future runs:
+```bash
+agentmb session new --profile gmail-account   # cookies already there
+agentmb navigate <sid> https://mail.google.com  # logged in automatically
+```
+
+### Pure Sandbox (Ephemeral)
+
+No state persisted. Auto-deleted on `close()`.
+
+```bash
+agentmb session new --ephemeral
+```
+
+---
+
+## Storage Export / Import
+
+Export auth state from one session and import into another (e.g., from manual login to automated session).
+
+```bash
+agentmb storage-export <session-id> -o myaccount-state.json
+# → saves Playwright storageState format (cookies + origins)
+
+agentmb storage-import <new-session-id> myaccount-state.json
+# → restores cookies; origins_skipped count returned
+```
+
+Python SDK:
+```python
+# After manual login — export the state
+sess.storage_export("myaccount-state.json")
+sess.close()
+
+# New automated session — import the state
+sess2 = client.sessions.create(profile="myaccount")
+result = sess2.storage_import("myaccount-state.json")
+print(result.origins_skipped)  # number of origins skipped (cross-origin restrictions)
+```
+
+Use case: login once (headless or manual), export, share across sessions or agents.
+
+---
+
+## Cookie Management
+
+```bash
+agentmb cookie-list <session-id>              # list all cookies
+agentmb cookie-clear <session-id>             # clear all cookies
+agentmb cookie-delete <session-id> <name>     # delete specific cookie
+agentmb cookie-delete <session-id> session_token --domain .example.com
+```
+
+Python SDK:
+```python
+# List cookies
+cookies = sess.cookie_list()
+
+# Clear all
+sess.cookie_clear()
+
+# Delete specific cookie (domain filter optional)
+result = sess.delete_cookie("session_token")
+result = sess.delete_cookie("tracker", domain=".example.com")
+print(result.removed, result.remaining)
+```
+
+---
+
+## Profile Encryption
+
+Browser profiles (cookies, storage) can be encrypted at rest using AES-256-GCM.
+
+```bash
+# Generate a 32-byte key
+export AGENTMB_ENCRYPTION_KEY="$(openssl rand -base64 32)"
+# Start daemon with key set
+agentmb start
+```
+
+```python
+import os
+os.environ["AGENTMB_ENCRYPTION_KEY"] = "your-32-byte-key-base64-or-hex"
+```
+
+**Important**: Profiles written without a key cannot be read with one, and vice versa. Keep the key consistent across daemon restarts.
+
+---
+
+## API Token Authentication
+
+When `AGENTMB_API_TOKEN` is set, all endpoints except `/health` require the token.
+
+```bash
+export AGENTMB_API_TOKEN="my-secret-token"
+agentmb start
+```
+
+Send the token in requests:
+```bash
+# Via header
+curl -H "X-API-Token: my-secret-token" http://127.0.0.1:19315/health
+
+# Via Authorization Bearer
+curl -H "Authorization: Bearer my-secret-token" http://127.0.0.1:19315/health
+```
+
+Python SDK:
+```python
+client = BrowserClient(base_url="http://127.0.0.1:19315", api_token="my-secret-token")
+```
+
+Requests without a valid token return `401 Unauthorized`.
+
+---
+
+## Multi-Site Auth Pattern
+
+For workflows that require multiple site logins:
+
+```bash
+# Login to site A
+agentmb session new --profile site-a-account
+agentmb login <sid-a>      # manual login
+agentmb storage-export <sid-a> -o site-a-state.json
+agentmb session rm <sid-a>
+
+# Login to site B
+agentmb session new --profile site-b-account
+agentmb login <sid-b>
+agentmb storage-export <sid-b> -o site-b-state.json
+agentmb session rm <sid-b>
+
+# Automation session with pre-loaded auth
+agentmb session new --profile site-a-account
+agentmb storage-import <sid> site-a-state.json
+agentmb navigate <sid> https://site-a.example.com   # already logged in
+```

package/skills/agentmb/references/browser-modes.md

@@ -0,0 +1,167 @@
+# Browser Modes — Deep Reference
+
+agentmb supports three browser running modes, differing in **which binary is used and how it is connected**.
+
+| Mode | Browser | How Connected | Profile Persistence |
+|---|---|---|---|
+| **1. Managed Chromium** | Playwright-bundled Chromium | agentmb spawns & owns | Persistent or ephemeral |
+| **2. Managed Chrome Stable** | System Chrome / Edge | agentmb spawns & owns | Persistent or ephemeral |
+| **3. CDP Attach** | Any running Chrome-compatible | agentmb attaches via CDP | Owned by external process |
+
+---
+
+## Mode 1 — Managed Chromium (default)
+
+agentmb spawns the **Playwright-bundled Chromium** binary. No system Chrome required. Works in headless (CI) and headed modes.
+
+```bash
+agentmb session new --profile demo             # named profile (persistent)
+agentmb session new --ephemeral                # temp profile (auto-deleted)
+agentmb session new --profile demo --headed    # visible window
+```
+
+```python
+sess = client.sessions.create(profile="demo")
+sess = client.sessions.create(ephemeral=True)
+sess = client.sessions.create(profile="demo", headless=False)
+```
+
+**Use when**: default automation, CI pipelines, no system Chrome required, any OS.
+
+---
+
+## Mode 2 — Managed Chrome Stable
+
+agentmb spawns **system-installed Chrome or Edge** via Playwright. Chrome Stable or Edge must be installed on the host.
+
+```bash
+agentmb session new --browser-channel chrome         # system Chrome Stable
+agentmb session new --browser-channel msedge         # system Edge
+agentmb session new --executable-path /path/to/chrome  # custom binary
+```
+
+```python
+sess = client.sessions.create(browser_channel="chrome")           # Chrome Stable
+sess = client.sessions.create(browser_channel="msedge")           # Edge
+sess = client.sessions.create(executable_path="/usr/bin/chromium") # custom path
+```
+
+Valid `browser_channel` values: `chromium` (default), `chrome`, `msedge`.
+`browser_channel` and `executable_path` are mutually exclusive — using both returns `400 preflight_failed`.
+
+**Use when**: you need Chrome-specific behavior, extensions, or site compatibility that differs from bundled Chromium.
+
+---
+
+## Mode 3 — CDP Attach
+
+agentmb **attaches to an already-running Chrome** process via the Chrome DevTools Protocol. The external browser is **not terminated** on `close()` — only the Playwright connection is dropped.
+
+### Three Profile Variants
+
+| Variant | `--user-data-dir` | State | Typical Use |
+|---|---|---|---|
+| **A. Sandbox** | temp dir (auto) | ephemeral | clean CI, throwaway sessions |
+| **B. Dedicated Profile** | custom persistent dir | persistent, isolated | automation account, persistent login |
+| **C. User Chrome** | your real Chrome profile | inherits cookies & extensions | leverage personal login state |
+
+#### Variant A: Sandbox (temp profile, via browser-launch)
+
+`agentmb browser-launch` starts Chrome with an auto-created temp profile. Clean slate every time.
+
+```bash
+agentmb browser-launch --port 9222
+# → Chrome launched at ws://127.0.0.1:9222 with temp --user-data-dir
+
+agentmb session new --launch-mode attach --cdp-url http://127.0.0.1:9222
+```
+
+```python
+sess = client.sessions.create(launch_mode="attach", cdp_url="http://127.0.0.1:9222")
+sess.navigate("https://example.com")
+sess.close()  # only disconnects — Chrome stays alive
+```
+
+#### Variant B: Dedicated Profile (persistent, isolated)
+
+Pass a fixed `--user-data-dir` to Chrome at startup. State persists across restarts. Completely isolated from personal Chrome.
+
+```bash
+# macOS / Linux
+/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
+  --remote-debugging-port=9222 \
+  --user-data-dir="$HOME/.agentmb-profiles/my-automation-profile" \
+  --no-first-run --no-default-browser-check
+
+# Windows
+"C:\Program Files\Google\Chrome\Application\chrome.exe" ^
+  --remote-debugging-port=9222 ^
+  --user-data-dir="%APPDATA%\agentmb-profiles\my-automation-profile"
+```
+
+```python
+sess = client.sessions.create(launch_mode="attach", cdp_url="http://127.0.0.1:9222")
+```
+
+#### Variant C: User Chrome (reuse personal profile)
+
+Point Chrome at your existing user profile to inherit all logged-in sessions, saved passwords, and installed extensions. **Chrome must not be running** with that profile when you launch it with remote debugging.
+
+```bash
+# macOS — close Chrome first, then:
+/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
+  --remote-debugging-port=9222 \
+  --user-data-dir="$HOME/Library/Application Support/Google/Chrome"
+
+# Linux
+google-chrome --remote-debugging-port=9222 \
+  --user-data-dir="$HOME/.config/google-chrome"
+
+# Windows
+"C:\Program Files\Google\Chrome\Application\chrome.exe" ^
+  --remote-debugging-port=9222 ^
+  --user-data-dir="%LOCALAPPDATA%\Google\Chrome\User Data"
+```
+
+```python
+sess = client.sessions.create(launch_mode="attach", cdp_url="http://127.0.0.1:9222")
+# → all cookies, extensions, and login state from personal Chrome are available
+```
+
+**Warning**: actions will affect your real Chrome profile. Use Variant B when in doubt.
+
+### CDP Attach Notes
+
+- `close()` only drops the Playwright connection. Chrome process stays alive.
+- CDP attach gives agentmb control over **all tabs** in the connected browser.
+- `launch_mode=attach` is incompatible with `browser_channel` and `executable_path` (preflight returns `400`).
+- Lower `navigator.webdriver` fingerprint than managed modes.
+- Supports real browser extensions.
+
+Attach command (all variants):
+```bash
+agentmb session new --launch-mode attach --cdp-url http://127.0.0.1:9222
+```
+
+---
+
+## Preflight Validation
+
+The session creation endpoint validates parameters before launching. Returns `400 preflight_failed` for:
+- `browser_channel` + `executable_path` used together
+- `browser_channel` not in `['chromium', 'chrome', 'msedge']`
+- `launch_mode=attach` without `cdp_url`
+- `cdp_url` with invalid URL format
+- `launch_mode=attach` combined with `browser_channel` or `executable_path`
+
+---
+
+## Mode Selection Summary
+
+| Need | Mode |
+|---|---|
+| Default CI automation, no system Chrome | Mode 1 (Managed Chromium) |
+| Chrome-specific rendering or extensions | Mode 2 (Managed Chrome Stable) |
+| Clean-slate session, real Chrome binary | Mode 3 Variant A (CDP Attach + browser-launch) |
+| Persistent automation account (isolated) | Mode 3 Variant B (CDP Attach + dedicated profile) |
+| Reuse personal login state | Mode 3 Variant C (CDP Attach + user profile) |

package/skills/agentmb/references/commands.md

@@ -0,0 +1,231 @@
+# CLI Commands — Full Reference
+
+All commands follow the pattern: `agentmb <command> <session-id> [args] [flags]`
+
+Use `agentmb --help` and `agentmb <command> --help` for full flag lists.
+
+---
+
+## Daemon
+
+| Command | Notes |
+|---|---|
+| `agentmb start` | Start daemon; `-p <port>` (default 19315), `-d <data-dir>` |
+| `agentmb stop` | Stop daemon |
+| `agentmb status` | Show daemon status (sessions, uptime) |
+| `agentmb browser-launch` | Launch Chrome with CDP remote debugging (for CDP Attach mode) |
+
+`browser-launch` flags: `--port <n>` (CDP port, default 9222), `--user-data-dir <dir>`, `--channel chrome|msedge`.
+
+---
+
+## Session
+
+| Command | Notes |
+|---|---|
+| `agentmb session new` | Create session; returns `<session-id>` |
+| `agentmb session list` | List all active sessions |
+| `agentmb session get <sid>` | Show session details |
+| `agentmb session rm <sid>` | Close and delete session |
+| `agentmb session seal <sid>` | Seal session (prevent deletion; 423 on rm) |
+| `agentmb settings <sid>` | Show session settings (viewport, headless, url, profile) |
+
+`session new` flags:
+
+| Flag | Default | Notes |
+|---|---|---|
+| `--profile <name>` | — | Named persistent profile |
+| `--ephemeral` | false | Temp profile (auto-deleted on close) |
+| `--headless` | true | Run headless |
+| `--headed` | — | Run headed (visible window) |
+| `--browser-channel <ch>` | `chromium` | `chromium` / `chrome` / `msedge` |
+| `--executable-path <path>` | — | Custom browser binary |
+| `--launch-mode attach` | — | CDP Attach mode |
+| `--cdp-url <url>` | — | Required with `--launch-mode attach` |
+| `--accept-downloads` | false | Enable file downloads |
+| `--policy <profile>` | `safe` | `safe` / `permissive` / `disabled` |
+
+---
+
+## Navigation
+
+| Command | Notes |
+|---|---|
+| `agentmb navigate <sid> <url>` | Navigate; `--wait-until load\|networkidle\|commit` |
+| `agentmb back <sid>` | Browser back |
+| `agentmb forward <sid>` | Browser forward |
+| `agentmb reload <sid>` | Reload page |
+| `agentmb wait-url <sid> <pattern>` | Wait for URL match (glob pattern) |
+| `agentmb wait-load-state <sid>` | Wait for load state |
+| `agentmb wait-function <sid> <expr>` | Wait for JS expression to return truthy |
+| `agentmb wait-text <sid> <text>` | Wait for text to appear in DOM |
+| `agentmb wait-stable <sid>` | Network idle + DOM quiet + optional overlay clear |
+
+---
+
+## Locator / Scan
+
+| Command | Notes |
+|---|---|
+| `agentmb element-map <sid>` | Inject element_ids; return labeled element list |
+| `agentmb element-map <sid> --include-unlabeled` | Include icon-only elements (fallback label: `[tag @ x,y]`) |
+| `agentmb snapshot-map <sid>` | Server-side snapshot; returns ref_id per element |
+| `agentmb snapshot-map <sid> --include-unlabeled` | Include unlabeled in snapshot |
+| `agentmb find <sid> <type> <query>` | Semantic find: `type` = `text\|role\|label\|placeholder\|alt_text` |
+
+---
+
+## Read / Assert
+
+| Command | Notes |
+|---|---|
+| `agentmb get <sid> <prop> <sel-or-eid>` | Read: `text\|html\|value\|attr\|count\|box` |
+| `agentmb assert <sid> <prop> <sel-or-eid>` | Assert: `visible\|enabled\|checked` |
+| `agentmb extract <sid> <selector>` | Extract all matching elements as list; `--attribute <attr>` |
+| `agentmb eval <sid> <expr>` | Evaluate JavaScript; returns raw result |
+
+---
+
+## Element Interaction
+
+| Command | Notes |
+|---|---|
+| `agentmb click <sid> <sel-or-eid>` | Click; `--element-id` or `--ref-id`; `422` with `recovery_hint` on failure |
+| `agentmb dblclick <sid> <sel-or-eid>` | Double-click |
+| `agentmb fill <sid> <sel-or-eid> <value>` | Fast fill (replace); `--fill-strategy normal\|type`, `--char-delay-ms <ms>` |
+| `agentmb type <sid> <sel-or-eid> <text>` | Type char by char; `--delay-ms <ms>` |
+| `agentmb press <sid> <sel-or-eid> <key>` | Key / combo: `Enter`, `Tab`, `Control+a` |
+| `agentmb select <sid> <sel> <value...>` | Select `<option>` by value/label |
+| `agentmb hover <sid> <sel-or-eid>` | Hover |
+| `agentmb focus <sid> <sel-or-eid>` | Focus element |
+| `agentmb check <sid> <sel-or-eid>` | Check checkbox / radio |
+| `agentmb uncheck <sid> <sel-or-eid>` | Uncheck |
+| `agentmb drag <sid> <source> <target>` | Drag-and-drop; `--source-ref-id` / `--target-ref-id` |
+
+---
+
+## Scroll
+
+| Command | Notes |
+|---|---|
+| `agentmb scroll <sid> <sel-or-eid>` | Scroll element; direction `up\|down\|left\|right`; `--amount <px>` |
+| `agentmb scroll-into-view <sid> <sel-or-eid>` | Scroll element into viewport |
+| `agentmb scroll-until <sid>` | Scroll until condition; `--stop-selector`, `--stop-text`, `--max-scrolls`, `--step-delay-ms` |
+| `agentmb load-more-until <sid> <btn-sel> <item-sel>` | Click load-more repeatedly |
+
+`scroll` response: `{ "scrolled": bool, "warning": "...", "scrollable_hint": [...] }`
+If `scrolled=false`, use selectors from `scrollable_hint` for the next scroll call.
+
+---
+
+## Coordinate / Low-Level
+
+| Command | Notes |
+|---|---|
+| `agentmb click-at <sid> <x> <y>` | Click at absolute page coordinates |
+| `agentmb bbox <sid> <sel-or-eid>` | Bounding box + center_x/center_y; accepts `--element-id` / `--ref-id` |
+| `agentmb mouse-move <sid> [x] [y]` | Move mouse; or `--selector`/`--element-id`/`--ref-id`; `--steps <n>` |
+| `agentmb mouse-down <sid>` / `mouse-up <sid>` | Mouse button press/release |
+| `agentmb key-down <sid> <key>` / `key-up <sid> <key>` | Raw key press/release |
+| `agentmb wheel <sid> --dx <n> --dy <n>` | Low-level wheel event |
+| `agentmb insert-text <sid> <text>` | Insert text into focused element (no keyboard simulation) |
+
+---
+
+## File Transfer
+
+| Command | Notes |
+|---|---|
+| `agentmb upload <sid> <selector> <file>` | Upload from disk; `--mime-type` to override auto-detection |
+| `agentmb download <sid> <sel-or-eid> -o <file>` | Download triggered by element; session must have `--accept-downloads` |
+
+`download` also accepts `--element-id` / `--ref-id`. Without `accept_downloads=True`, returns `422 download_not_enabled`.
+
+---
+
+## Cookies / Storage
+
+| Command | Notes |
+|---|---|
+| `agentmb cookie-list <sid>` | List all cookies |
+| `agentmb cookie-clear <sid>` | Clear all cookies |
+| `agentmb cookie-delete <sid> <name>` | Delete cookie by name; `--domain`, `--path`, `--url` filters |
+| `agentmb storage-export <sid> -o state.json` | Export Playwright storageState (cookies + origins) |
+| `agentmb storage-import <sid> state.json` | Restore cookies from storageState |
+
+---
+
+## Observability
+
+| Command | Notes |
+|---|---|
+| `agentmb screenshot <sid> -o out.png` | Screenshot; `--full-page`, `--format png\|jpeg` |
+| `agentmb annotated-screenshot <sid>` | Screenshot with element overlays; `--highlight <sel>` |
+| `agentmb logs <sid>` | Session audit log; `--tail <n>` |
+| `agentmb console-log <sid>` | Browser console entries; `--tail <n>` |
+| `agentmb page-errors <sid>` | Uncaught JS errors |
+| `agentmb dialogs <sid>` | Auto-dismissed dialog history (alert/confirm/prompt) |
+| `agentmb trace start <sid>` | Start Playwright trace recording |
+| `agentmb trace stop <sid> -o trace.zip` | Stop trace and save; view with `npx playwright show-trace trace.zip` |
+
+---
+
+## Browser Controls
+
+| Command | Notes |
+|---|---|
+| `agentmb set-viewport <sid> <w> <h>` | Resize viewport |
+| `agentmb clipboard-write <sid> <text>` | Write to clipboard |
+| `agentmb clipboard-read <sid>` | Read from clipboard |
+| `agentmb policy <sid>` | Get current policy profile |
+| `agentmb policy <sid> <profile>` | Set policy: `safe\|permissive\|disabled` |
+| `agentmb policy <sid> safe --allow-sensitive` | Safe + allow sensitive actions |
+| `agentmb cdp-ws <sid>` | Print browser-level CDP WebSocket URL |
+| `agentmb set-network <sid>` | Network throttling; `--latency-ms`, `--download-kbps`, `--upload-kbps`, `--offline` |
+| `agentmb reset-network <sid>` | Restore normal network conditions |
+
+---
+
+## Multi-Page (Tabs)
+
+| Command | Notes |
+|---|---|
+| `agentmb pages list <sid>` | List all open tabs |
+| `agentmb pages new <sid>` | Open a new blank tab; returns `<page-id>` |
+| `agentmb pages switch <sid> <page-id>` | Make tab the active target |
+| `agentmb pages close <sid> <page-id>` | Close tab (last tab protected — 409) |
+
+---
+
+## Routes (Network Mocks)
+
+| Command | Notes |
+|---|---|
+| `agentmb route list <sid>` | List active route mocks |
+| `agentmb route add <sid> <pattern>` | Add mock; `--status`, `--body`, `--content-type` |
+| `agentmb route rm <sid> <pattern>` | Remove mock |
+
+Mocks persist across page navigations within the session.
+
+---
+
+## CDP
+
+| Command | Notes |
+|---|---|
+| `agentmb cdp-ws <sid>` | Print `ws://` browser-level CDP endpoint |
+
+REST:
+```
+GET  /api/v1/sessions/:id/cdp          → session CDP info
+POST /api/v1/sessions/:id/cdp          → send CDP method: {"method": "...", "params": {...}}
+```
+
+---
+
+## Health
+
+```
+GET /health
+→ { "status": "ok", "version": "0.3.1", "uptime_s": N, "sessions_active": N }
+```