Allow configuring Stagehand's cache directory

[MagellaX]

Let folks point the cache at a writable path via the new cacheDir option or STAGEHAND_CACHE_DIR, document it, and cover the behavior with regression tests.
Covers #190

[changeset-bot]

⚠️ No Changeset found

Latest commit: 4aedc70

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[greptile-apps]

Greptile Summary

This PR adds configurable cache directory support to Stagehand, addressing issue #190. The implementation allows users to specify a custom cache directory via the cacheDir constructor option or the STAGEHAND_CACHE_DIR environment variable, with fallback to the default <cwd>/tmp/.cache path.

Key changes:

• Added cacheDir parameter to ConstructorParams interface with proper JSDoc documentation
• Updated BaseCache constructor to accept optional cacheDir parameter and resolve it through environment variables
• Modified LLMProvider to pass cache directory configuration to LLMCache
• Updated documentation in caching.mdx to explain the new configuration options
• Added comprehensive test coverage for cache directory resolution logic
• Refactored agent tools to use StagehandPage instead of full Stagehand object for better separation of concerns

Architecture improvements:

• Better path resolution handling with absolute path detection
• Environment variable precedence: constructor param > env var > default
• Test coverage ensures cache directory creation respects configuration

Confidence score: 4/5

• This PR is safe to merge with minor improvements recommended
• The implementation correctly addresses the user requirement for configurable cache directories. The code follows existing patterns, includes proper documentation, and has test coverage. Minor logic improvements suggested for edge case handling and code simplification.
• lib/cache/BaseCache.ts requires minor fix for whitespace-only path handling

_{6 files reviewed, 2 comments}

_{Edit Code Review Bot Settings | Greptile}

[MagellaX]

@seanmcguire12 all good!