feat: add support for saving screenshots to disk with reusable handles

[andyMrtnzP]

Summary

Allows saving and reusing screenshots via the upload/download mechanism.

Related issues

Closes AUTO-185

Changes

Test plan

• npm test passes locally
• npm run lint passes locally
• npm run coverage thresholds still met
• Manual smoke test against a real Browserless token (describe below)
• N/A — docs / chore / refactor only

Checklist

• I have read CONTRIBUTING.md
• My commits follow the conventional-commit prefix convention
• I have updated documentation where relevant (README, CHANGELOG, etc.)
• I have not introduced new dependencies without flagging them in the summary

Summary by CodeRabbit

• New Features
  • Added an option to save screenshots directly to disk instead of displaying them inline.
  • Disk-saved screenshots return a reusable “download-style” handle (local path or temporary download URL) for later use.
• Documentation
  • Documented the new save-to-disk behavior and guidance on when to use it.
  • Updated file-transfer guidance to reflect how screenshot handles can be reused.
• Bug Fixes
  • Improved screenshot command handling to avoid embedding inline image/base64 data when saving to disk.

[coderabbitai]

Warning

Review limit reached

@andyMrtnzP, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 34 minutes and 1 second. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 99b527aa-084f-4f8a-af37-8ad5204494cd

📥 Commits

Reviewing files that changed from the base of the PR and between dc2343b and 5dee6a1.

📒 Files selected for processing (3)

• src/tools/agent.ts
• test/helpers/upgrade-server.ts
• test/tools/agent.spec.ts

Walkthrough

The PR adds a toDisk option to screenshot commands, updates related docs and schema, stores screenshot bytes as reusable download handles, strips the internal flag before dispatch, and adds tests for disk, URL, and missing-data paths.

Changes

Screenshot save-to-disk flow

Layer / File(s)	Summary
Contract and docs src/tools/schemas.ts, src/skills/screenshots.md, src/skills/file-transfers.md	screenshot accepts toDisk, and the skills docs describe saved handles, URL reuse, and delayed visibility.
Save helper and tests src/tools/agent.ts, test/tools/agent.spec.ts	formatScreenshotToDisk stores screenshot bytes in the download store, and the new tests cover stdio saves, HTTP download URLs, and missing payload handling.
Command dispatch and batch output src/tools/agent.ts	The send loop removes the internal toDisk flag before dispatching screenshot commands, and batch formatting switches screenshot results with toDisk: true to the saved-download formatter before falling back to JSON text.

Sequence Diagram(s)

sequenceDiagram
  participant Agent as agent.ts
  participant ScreenshotResult as screenshot result
  participant DownloadStore as storeDownload
  participant TestSuite as agent.spec.ts

  Agent->>ScreenshotResult: extract base64 and mimeType
  Agent->>DownloadStore: store screenshot bytes with sessionId
  DownloadStore-->>Agent: saved handle or URL
  TestSuite->>Agent: verify disk and URL formatting

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Suggested reviewers

• ashwinsingh2007

Poem

A bunny saw a screenshot glow,
Then tucked it where the downloads grow.
No inline peek, just hop and save,
A handle waits in disk-bound brave. 🐇

🚥 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%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: saving screenshots to disk with reusable handles.
Description check	✅ Passed	All required sections are present and mostly complete; the empty Changes section is acceptable because the summary covers it.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch anderson/auto-185-explain-screenshot-temp-path-capture-and-reuse-to-agents

---

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

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

test/tools/agent.spec.ts (1)

212-277: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add one batch-level regression test for toDisk.

These cases only hit formatScreenshotToDisk() directly, so they won't catch formatter bugs in the full browserless_agent flow. Please add a tool-level case for something like [screenshot { toDisk: true }, close] so the save-to-disk path stays covered end to end.

🤖 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 `@test/tools/agent.spec.ts` around lines 212 - 277, Add a batch-level
regression test in the browserless agent flow to cover the save-to-disk path end
to end, since the current coverage only exercises formatScreenshotToDisk
directly. Update the relevant batch/tool test around browserless_agent handling
of screenshot with toDisk enabled, using a sequence like screenshot with toDisk:
true followed by close, and assert the returned output includes the disk-save
path behavior. Keep the existing formatScreenshotToDisk unit tests, but add this
higher-level case so formatter regressions are caught through the full tool
pipeline.

🤖 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.

Inline comments:
In `@src/tools/agent.ts`:
- Around line 723-748: The screenshot-to-disk branch in agent.ts is using a
different command source than the `last` result when a batch ends with `close`,
so the `toDisk` check can miss the final screenshot command. Update the logic
around `last`, `lastCmd`, and `formatScreenshotToDisk` to derive both the result
and command from the same pre-close filtered list, then add a regression test
for a batch like `screenshot { toDisk: true }` followed by `close` to verify the
saved-download handle is returned.

---

Nitpick comments:
In `@test/tools/agent.spec.ts`:
- Around line 212-277: Add a batch-level regression test in the browserless
agent flow to cover the save-to-disk path end to end, since the current coverage
only exercises formatScreenshotToDisk directly. Update the relevant batch/tool
test around browserless_agent handling of screenshot with toDisk enabled, using
a sequence like screenshot with toDisk: true followed by close, and assert the
returned output includes the disk-save path behavior. Keep the existing
formatScreenshotToDisk unit tests, but add this higher-level case so formatter
regressions are caught through the full tool pipeline.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 99f915f8-fd33-44b9-aaa5-937cc9f8ed18

📥 Commits

Reviewing files that changed from the base of the PR and between de30d08 and 72824d8.

📒 Files selected for processing (5)

• src/skills/file-transfers.md
• src/skills/screenshots.md
• src/tools/agent.ts
• src/tools/schemas.ts
• test/tools/agent.spec.ts