fix: close one-shot agent sessions after command batches

[artiom]

Summary

Adds an optional keepSessionAlive flag to browserless_agent, defaulting to true on both standard and compliant surfaces. Set it to false to close the browser used by a successful command batch after results and downloads have been collected.

The close targets the stored session handle, including calls that did not supply a session ID. Profile-creation and attached sessions retain their existing lifetime. Default multi-turn pooling is unchanged.

Test plan

• npm test: 1,040 passing, including session-cache and package-integrity coverage.
• npm run lint: passed.
• Prettier checks: passed.
• New regression tests first failed without the implementation, then passed for schema validation, bare and echoed teardown, download ordering, result preservation, default pooling, profile/attach guards, and token isolation.
• Failed automatic download drains report an error and retain eligible one-shot sessions for recovery; regression coverage also verifies unchanged pooled behavior.

Live-browser acceptance

Passed against real Chromium with a fresh signup identity and local mock entitlement; no live Stripe calls:

• Unchanged baseline retained one active browser 1.2 seconds after command completion.
• One-shot command results were preserved; the active-session count returned to zero 288 ms after the response on the final fix.
• Two default-mode calls, echoing the returned handle, preserved the cookie and page text with one active browser.
• Explicit cleanup returned the active-session count to zero.

These checks verify browser-session lifecycle, not payment/subscription behavior.

Checklist

• Conventional commit title.
• Parameter documentation included in the tool schema.
• No new dependencies.
• Live-browser acceptance complete.

Summary by CodeRabbit

• New Features

  • Added an optional setting to control whether browser sessions remain open after command execution.
  • Sessions remain open by default, while one-time sessions can now close automatically after downloads are completed.
  • Profile creation and sessions attached to an existing browser remain unaffected.

• Bug Fixes

  • Improved session cleanup to ensure only the requesting session is closed.

• Tests

  • Added coverage for session lifetime defaults, validation, compliant-mode behavior, downloads, and session reuse.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Team

Run ID: bb180cba-948c-4fba-9645-e3d879f4e79f

📥 Commits

Reviewing files that changed from the base of the PR and between f4943fa and a41b016.

📒 Files selected for processing (2)

• src/tools/agent.ts
• test/tools/agent.spec.ts

Included review availability: 0 reviews are currently available. Your included PR review attempts over the past 7 days set your current allowance at 2 reviews per hour.

---

Walkthrough

The agent tools accept keepSessionAlive. When it is false, eligible sessions close after command and download processing. Profile-creation and attached sessions remain open. Download failures preserve session access for recovery.

Changes

Agent session lifetime

Layer / File(s)	Summary
Session lifetime contract src/tools/schemas.ts, test/tools/compliance-mode.spec.ts	Agent and compliant agent schemas accept optional boolean keepSessionAlive, defaulting to true. Tests verify the compliant schema allowlist.
Session cleanup flow src/tools/agent.ts	The tool tracks the active session, handles download collection failures, and closes eligible sessions when keepSessionAlive is false.
Session lifetime validation test/tools/agent.spec.ts	Tests cover parsing, invalid values, session reuse, download recovery, cleanup exceptions, and token-scoped cleanup.

Priority: ⬇️ Low

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

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant AgentTool
  participant runCommands
  participant BrowserSession
  AgentTool->>runCommands: execute command batch
  runCommands-->>AgentTool: return active session
  AgentTool->>BrowserSession: collect downloads
  AgentTool->>BrowserSession: close eligible session when keepSessionAlive is false

Loading

Suggested reviewers: andymrtnzp

Merge Risk: ⚪ Minimal · up to a41b0

The session-lifetime change has coverage for cleanup, recovery, reuse, and token isolation, with no remaining concrete merge-blocking issue.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 4 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
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 primary change: closing one-shot agent sessions after command batches.
Description check	✅ Passed	The description explains the change, scope, behavior, test results, live-browser acceptance, and checklist status. It omits the Related issues and Changes headings and does not explicitly confirm that…

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

_{A rabbit keeps the session bright
Commands hop through the wire
Downloads wait, then errors guide
One-shot browsers close
Reusable paths remain
Fresh paws test each case}

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

[artiom]

Verification complete: npm test reports 1,040 passing; lint and formatting passed. Live-browser acceptance passes: the unchanged baseline retained one active browser after 1.2 seconds; final one-shot teardown preserved the command result and reached zero active sessions 288 ms after return; default echoed calls preserved cookie and page state. Explicit cleanup reached zero. The failed-download-drain finding is fixed with regression coverage; the reuse-wording observation remains an acknowledged non-blocking follow-up. All five current-head checks pass, no review thread remains unresolved, and the branch has no merge conflicts. Ready for review.

[devin-ai-integration]

Devin Review found 1 potential issue.

1 flag not posted on this PR by your GitHub settings — view it in Devin Review. (Configure)