fix(agent): ensure calls receive isolated browsers handle

[andyMrtnzP]

Summary by CodeRabbit

• Bug Fixes
  • Improved browser session isolation so separate calls no longer unintentionally share an existing browser.
  • Preserved browser continuity when using the correct task-specific session handle.
  • Added clearer session handles for all connection types, including stdio.
  • Improved handling of concurrent calls and session-specific tokens.
  • Prevented inactive or unrelated sessions from being adopted by new calls.

[coderabbitai]

Walkthrough

The change gives bare calls unique task-specific session handles, prevents orphan-session adoption, and preserves browser reuse when callers echo a handle. Session messages now expose handles for stdio and other transports. Tests cover isolation, reuse, token scoping, concurrency, and response formatting.

Changes

Session Isolation and Continuity

Layer / File(s)	Summary
Task-specific handle generation and lookup src/lib/agent-client.ts, test/lib/agent-client.spec.ts	The client prefers echoed or attached handles and otherwise creates a UUID. Exact-key lookup replaces orphan adoption. Tests cover isolation, reuse, token scoping, concurrency, and profile sessions.
Transport-independent session messaging src/tools/agent.ts, test/tools/agent.spec.ts	Session handles now appear in open-session, error, and batch-result messages for all transports. Tests require an s: handle that differs from the MCP session ID.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Caller
  participant AgentTool
  participant AgentClient
  participant Browser
  Caller->>AgentTool: Submit call with or without echoed handle
  AgentTool->>AgentClient: Request browser session
  AgentClient->>Browser: Create or resume exact session
  AgentClient-->>AgentTool: Return task-specific handle
  AgentTool-->>Caller: Return handle and continuation instructions

Loading

Possibly related PRs

• browserless/browserless-mcp#177: Both changes modify agent session handling and tool behavior, but this change addresses session isolation rather than client-source headers.
• browserless/browserless-mcp#218: This change refines the session-handle and session-cache logic introduced there.
• browserless/browserless-mcp#222: This change revises the session-keying and orphan-adoption behavior introduced there.

Poem

A rabbit hops through handles bright,
Bare calls keep their browsers right.
Echoed tokens find their way,
Across each transport, night and day.
No orphan hops into the play!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	No pull request description was provided, so the required summary, changes, test plan, and checklist are missing.	Add a description using the repository template, including the change summary, related issues, test results, and completed checklist items.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly identifies the agent fix for isolated browser handling, which matches the main change.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/parallel-agents

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (2)

src/lib/agent-client.ts (2)

662-672: 🎯 Functional Correctness | 🟠 Major | 🏗️ Heavy lift

Resume echoed handles without requiring creation options.

The lookup key includes proxy, profile, createProfile, and attachSessionId. A caller can open a profile session, then follow the returned instruction and send only sessionId. The second call has no profile suffix, so sessions.get(key) misses and opens a new browser.

Use a token-scoped handle lookup for echoed handles. Preserve the initial session configuration or reject conflicting configuration. Add a test that resumes a profile session with only sessionId.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/lib/agent-client.ts` around lines 662 - 672, Update the session lookup
around getSessionKey and sessions.get so echoed sessionId handles first resolve
through a token-scoped handle index, without requiring proxy, profile,
createProfile, or attachSessionId options. Preserve the original session
configuration when resuming, and reject requests whose supplied configuration
conflicts with that existing session. Add coverage for opening a profile session
and resuming it using only sessionId.

---

657-672: 🩺 Stability & Availability | 🟡 Minor | ⚡ Quick win

Pass the minted handle to cleanup. When echoedSessionId is absent, getOrCreateSession stores the session under a key containing its generated handle. destroySession and closeSession rebuild the key with undefined, so they do not find that session. Pass agentSession.handle to these cleanup calls to prevent failed or closed bare calls from leaving live WebSockets in sessions.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/lib/agent-client.ts` around lines 657 - 672, Update the cleanup calls in
the agent session lifecycle to pass agentSession.handle to destroySession and
closeSession instead of leaving the handle undefined. Ensure cleanup rebuilds
the same session key created by getOrCreateSession, including for bare calls
where handle is generated.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@src/lib/agent-client.ts`:
- Around line 662-672: Update the session lookup around getSessionKey and
sessions.get so echoed sessionId handles first resolve through a token-scoped
handle index, without requiring proxy, profile, createProfile, or
attachSessionId options. Preserve the original session configuration when
resuming, and reject requests whose supplied configuration conflicts with that
existing session. Add coverage for opening a profile session and resuming it
using only sessionId.
- Around line 657-672: Update the cleanup calls in the agent session lifecycle
to pass agentSession.handle to destroySession and closeSession instead of
leaving the handle undefined. Ensure cleanup rebuilds the same session key
created by getOrCreateSession, including for bare calls where handle is
generated.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 80283f2f-c49e-436f-bbb6-07b2dafb7544

📥 Commits

Reviewing files that changed from the base of the PR and between 2a043e6 and b215ea5.

📒 Files selected for processing (4)

• src/lib/agent-client.ts
• src/tools/agent.ts
• test/lib/agent-client.spec.ts
• test/tools/agent.spec.ts