feat: add --headers support for CDP connect

[pahud]

Summary

Add support for custom headers when connecting to remote browsers via CDP, and introduce a new agentcore browser provider for native integration with AWS Bedrock AgentCore Browser.

Closes #396

Changes

CDP Headers Support

• Add headers parameter to connectViaCDP() in browser.ts
• Pass headers to Playwright's connectOverCDP()
• Support --headers flag in CLI for connect command
• Support --headers flag with --cdp global option

AgentCore Browser Provider (-p agentcore)

• Add connectToAgentCore() method with SigV4-signed session creation and CDP connection
• Add closeAgentCoreSession() for proper session cleanup on close
• Add signAgentCoreRequest() helper for AWS SigV4 request signing
• Wire into launch() and close() lifecycle
• Update CLI help text to include agentcore provider
• Add AWS SDK dependencies: @aws-sdk/credential-providers, @smithy/signature-v4, @smithy/protocol-http, @aws-crypto/sha256-js

Usage

CDP Headers (low-level)

agent-browser connect "wss://..." --headers '{"Authorization":"AWS4-HMAC-SHA256...", "X-Amz-Date":"..."}'

AgentCore Provider (recommended)

# Single command - no external scripts or Python needed
agent-browser -p agentcore open https://example.com

# Search Amazon and extract data
agent-browser -p agentcore open https://www.amazon.com
agent-browser type "#twotabsearchtextbox" "1tb nvme ssd"
agent-browser click "#nav-search-submit-button"
agent-browser eval "document.title"

# Clean up
agent-browser close

Environment Variables

Variable	Description	Default
AGENTCORE_REGION	AWS region for AgentCore	us-east-1 (falls back to AWS_REGION)
AGENTCORE_BROWSER_ID	Browser identifier	aws.browser.v1
AGENTCORE_SESSION_TIMEOUT	Session timeout in seconds	3600

Uses standard AWS credential chain (env vars, ~/.aws/credentials, IAM roles, etc).

Architecture

agent-browser -p agentcore open
│
├─ 1. Create session via AgentCore REST API (SigV4-signed)
│ PUT /browsers/{id}/sessions/start
│
├─ 2. Connect to remote browser via CDP WebSocket (SigV4-signed headers)
│ wss://bedrock-agentcore.{region}.amazonaws.com/browser-streams/...
│
├─ 3. Control browser via Playwright (navigate, click, type, eval, etc.)
│
└─ 4. On close: stop session via AgentCore REST API
PUT /browsers/{id}/sessions/stop

This follows the same pattern as existing providers (Browserbase, Kernel, BrowserUse).

Testing

• Unit tests added for CDP headers support
• Unit tests added for AgentCore provider (credential validation, region config, API path, error handling)
• Manually tested with AWS Bedrock AgentCore Browser in us-east-1 and us-west-2

[vercel]

@pahud is attempting to deploy a commit to the Vercel Labs Team on Vercel.

A member of the Team first needs to authorize it.

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	npm/​@​smithy/​protocol-http@​5.3.8
	npm/​@​smithy/​signature-v4@​5.3.8
	npm/​@​aws-crypto/​sha256-js@​5.2.0
	npm/​@​aws-sdk/​credential-providers@​3.985.0

View full report