chore: clarify proxy usage in agent tool

[andyMrtnzP]

Summary by CodeRabbit

• Documentation

  • Expanded proxy configuration guidance clarifying that settings must be provided as top-level arguments at session creation.

• Bug Fixes

  • Added validation to detect incorrect proxy command entries with improved error messages providing explicit recovery steps.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 24e794cf-833f-4926-8a71-6e96f8a1f1a1

📥 Commits

Reviewing files that changed from the base of the PR and between 44ea624 and 01f7d8f.

📒 Files selected for processing (1)

• src/tools/agent.ts

Disabled knowledge base sources:

• Linear integration is disabled

You can enable these sources in your CodeRabbit configuration.

---

Walkthrough

This PR clarifies proxy configuration for browserless_agent and adds runtime validation that rejects commands entries with method === "proxy", emitting analytics and throwing a UserError instructing callers to close and reopen the session with proxy options passed at the top level.

Changes

Proxy Configuration Enforcement

Layer / File(s)	Summary
Proxy documentation and validation src/tools/agent.ts	Updated "Proxy (optional)" instructions to clarify proxy parameters are top-level tool arguments applied at session creation, must be set on the initial call, cannot be sent as commands mutations, and require closing/restarting if set too late. Added validation to detect commands items with method === "proxy", send failure analytics, and throw a UserError with recovery steps.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• browserless/browserless-mcp#82: Touches src/tools/agent.ts proxy instructions; this PR extends that work by adding runtime validation and error handling for invalid proxy commands entries.
• browserless/browserless-mcp#61: Adds proxy-aware session setup via top-level args.proxy, related to enforcing top-level proxy contract here.
• browserless/browserless-mcp#16: Implements command normalization and run flow that the new commands validation now interacts with.

Suggested reviewers

• ashwinsingh2007
• artiom

Poem

🐰 A proxy once confused the way,
Now docs and guards keep errors at bay,
Top-level it goes, at session's first call,
Close and reopen if you tried to stall,
Hop, retry, and let the session stand tall!

✨ 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/clarify-proxying

---

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