browser-act--skills/docs/concurrency.md

Concurrency & Isolation

Browsers are identities. Sessions are workspaces. State never bleeds between them.

Every agent gets its own lane. Multi-agent multi-task parallel runs don't contaminate each other or get correlated by sites.

Three Concurrency Models

Model	Isolation	Shares	Typical use
Cross-browser parallel	Browser-level	Nothing (independent fingerprint/IP/cookies)	Multi-account monitoring, multi-identity ops
Same-browser multi-session	Session-level	Login state	Parallel tasks under the same account
Privacy mode zero-residue	Session-level	Nothing (fresh start each time)	One-off collection, high anonymity

Cross-Browser Parallel (Independent Identity)

Run any number of browsers simultaneously, each with independent cookies / fingerprint / proxy / login state. Sites cannot correlate them.

# Each session name must be globally unique — even when pointing to different browsers
browser-act --session monitor-shop-a browser open competitor1 https://shop-a.com
browser-act --session monitor-shop-b browser open competitor2 https://shop-b.com
browser-act --session monitor-shop-c browser open competitor3 https://shop-c.com

Properties:

• Each stealth browser is an independent identity
• Zero state cross-contamination
• Monitor a competitor with one identity while running internal automation with another — they don't interfere

Use cases: Multi-account monitoring, multi-store ops, batch identity isolation.

Same-Browser Multi-Session (Shared Login State)

One browser, multiple sessions. Shared login state, independent execution.

# Two parallel tasks on the same browser
browser-act --session task-a browser open <browser-id> https://site.com/page1
browser-act --session task-b browser open <browser-id> https://site.com/page2

Properties:

• Shared cookies / login state
• Each session has its own navigation, network capture, dialog handling
• Two agents can work on different email threads in the same Gmail account without blocking each other
• Session ownership is enforced by the explicit-naming model

Use cases: Multiple subtasks under the same account.

Naming Parallel Sessions (Globally Unique)

In a parallel setup every --session <name> must be globally unique — names cannot collide even across different browsers. Pick names that reflect each session's purpose:

# Same browser, multiple sessions: distinguish subtasks by name
browser-act --session monitor-prices browser open shop1 https://shop.com
browser-act --session track-orders browser open shop1 https://shop.com/orders

Privacy Mode (Zero Residue)

Each session uses a fresh fingerprint and profile, with nothing persisted at the end. Zero residue between sessions.

# Create a stealth browser with privacy mode enabled
browser-act browser create --type stealth --name "ephemeral" \
  --desc "One-off collection" --private true

Properties:

• stealth browsers only
• Fresh fingerprint per session, avoiding fingerprint accumulation
• Suitable for one-off collection, or any multi-account scenario where state leakage is a risk

See Anti-Blocking → Privacy Mode.

Session Model

What Is a Session

A session is a standalone browser window bound to a name. All interaction commands require the --session flag:

browser-act --session my-task browser open <id> https://example.com
browser-act --session my-task state
browser-act --session my-task click 2
browser-act session close my-task

The session name is your handle to a specific browser context, and persists until explicitly closed.

Why Explicit Sessions

Reason	Explanation
Parallel safety	Multiple agents (or conversations) can operate simultaneously without conflicts
Clear ownership	Each session belongs to the agent that created it
Controlled lifecycle	Open with intent, close when done
Multi-browser targeting	Different sessions can point to different browsers

Session Lifecycle

Create (browser open) → Use (state/click/input/...) → Close (session close)

• The first browser open with a --session name starts the session
• The same --session name reuses the existing session, no duplicates
• Close after the work is done: session close <name>

Session Ownership

• A session belongs to the agent / conversation that created it
• An agent should not reuse sessions it didn't create
• Existing sessions from other conversations are treated as "someone else's"
• New work always creates a new session

Auto-Reclamation

Sessions that receive no commands for 8 hours are automatically reclaimed. No need to worry about forgotten sessions permanently consuming resources.

Listing and Closing

browser-act session list             # List all active sessions
browser-act session close <name>     # Close a specific session
browser-act session close            # Close the current session

Session-to-Browser Relationship

┌── Browser A (chrome) ───────────────────┐
│  Session "search"  → google.com        │
│  Session "monitor" → analytics.com     │
└────────────────────────────────────────┘

┌── Browser B (stealth) ─────────────────┐
│  Session "scrape"  → target-site.com   │
└────────────────────────────────────────┘

• A session belongs to exactly one browser
• A browser can host multiple sessions
• Sessions on the same browser share cookies/login but navigate independently

Commands That Don't Need a Session

Browser-management or system-level commands don't require --session:

• browser list, browser create, browser delete, browser update
• browser regions, browser list-profiles
• session list
• auth login, auth poll, auth set, auth clear
• get-skills, report-log, feedback
• stealth-extract (creates and tears down its own temporary context)

Best Practices

Practice	Note
Descriptive names	check-price, not s1
Close when done	Don't leave sessions hanging
One browser, many sessions	Prefer parallel sessions over duplicate browsers
Globally unique names	Parallel session names must not collide, even across different browsers
One task, one session	One logical task = one session

Next Steps

• Browser Modes — Browser choice determines isolation granularity
• Agent Design — Design philosophy, automation capabilities, secure by default