chore(deps): integrate agent-browser v0.6.0

[galligan]

Agent-Browser v0.6.0 Integration

Upstream agent-browser has updates to integrate into our fork.

Upstream	v0.6.0 (399fd7a)
Fork (before)	b4c7c47
Fork (after)	3963ec0
Commits	26
Breaking	0

Fork Status

Already merged. The fork has been synced with upstream and pushed to origin.
Navigator's bun.lock updated but not committed.

Changes

Breaking Changes

None

New Features

Commit	Feature	Navigator Action	Priority
a8dcbb1	CDP connect for persistent sessions	N/A (already supported)	-
03a53c9	Claude marketplace plugin	Exclude (see below)	-
b1c0c6a	Network request details in response	Auto-inherited	-
c88734d	NO_COLOR env support	Auto-inherited	Low
e6e832d	styles command - computed styles	Add styles action	High
1f31452	Native video recording	Add recording actions	High
3675e6b	--proxy flag for browser	Add proxy option	Medium
7bdfcf8	--version flag	N/A (navigator has own)	-

Bug Fixes

12 fixes included (general stability improvements)

Navigator Impact

New Actions Required

1. styles Action (High Priority)

Get computed styles for visual testing and UI verification.

Upstream schema (src/protocol.ts:307-310):

const stylesSchema = baseCommandSchema.extend({
  action: z.literal('styles'),
  selector: z.string().min(1),
});

Return type (src/types.ts):

interface ElementStyleInfo {
  tag: string;
  text: string | null;
  box: { x: number; y: number; width: number; height: number };
  styles: {
    fontSize: string;
    fontWeight: string;
    fontFamily: string;
    color: string;
    backgroundColor: string;
    borderRadius: string;
    border: string | null;
    boxShadow: string | null;
    padding: string;
  };
}

Navigator schema addition (packages/core/src/schema/index.ts):

export const stylesSchema = baseActionSchema.extend({
  action: z.literal('styles'),
  selector: z.string().min(1).describe('CSS selector for elements'),
})

2. recording Actions (High Priority)

Playwright native video recording for demos and debugging.

Upstream schemas (src/protocol.ts:321-335):

const recordingStartSchema = baseCommandSchema.extend({
  action: z.literal('recording_start'),
  path: z.string().min(1),
  url: z.string().min(1).optional(),
});

const recordingStopSchema = baseCommandSchema.extend({
  action: z.literal('recording_stop'),
});

const recordingRestartSchema = baseCommandSchema.extend({
  action: z.literal('recording_restart'),
  path: z.string().min(1),
  url: z.string().min(1).optional(),
});

Navigator schema additions:

export const recordingStartSchema = baseActionSchema.extend({
  action: z.literal('recordingStart'),
  path: z.string().min(1).describe('Output path for video file'),
  url: z.string().url().optional().describe('URL to navigate to before recording'),
})

export const recordingStopSchema = baseActionSchema.extend({
  action: z.literal('recordingStop'),
})

export const recordingRestartSchema = baseActionSchema.extend({
  action: z.literal('recordingRestart'),
  path: z.string().min(1).describe('Output path for new video file'),
  url: z.string().url().optional(),
})

3. proxy Launch Option (Medium Priority)

Browser proxy configuration for testing behind proxies or with MITM tools.

Upstream schema (src/protocol.ts:22-30):

proxy: z
  .object({
    server: z.string().min(1),
    bypass: z.string().optional(),
    username: z.string().optional(),
    password: z.string().optional(),
  })
  .optional(),

Navigator integration: Add to launch/connect options in server config.

Modified Actions

tab_new / newTab

Now accepts optional url parameter. Navigator's newTab action should be updated:

export const newTabSchema = baseActionSchema.extend({
  action: z.literal('newTab'),
  url: z.string().url().optional().describe('URL to open in new tab'),
})

Files Affected

File	Change Required
packages/core/src/schema/index.ts	Add styles, recordingStart/Stop/Restart schemas
packages/server/src/action-executor.ts	Wire new actions to agent-browser
packages/mcp/src/tools/navigator.ts	Document new actions in tool schema

Marketplace Plugin Decision

Recommendation: Exclude from fork

The upstream .claude-plugin/marketplace.json is:

• Vercel-branded (owner.name: "Vercel")
• Generic agent-browser focused
• Not aligned with Navigator's plugin at packages/agents/

Action items:

• Add .claude-plugin/ to fork's .gitignore or delete after merge
• Ensure navigator's own plugin (packages/agents/) is the source of truth
• Consider cherry-picking useful parts of upstream's skills/agent-browser/SKILL.md into navigator docs

Integration Checklist

• Review upstream changes
• Merge upstream into fork (b4c7c47 → 3963ec0)
• Push fork to GitHub
• Update navigator's bun.lock
• Run bun run typecheck (passes)
• Run bun test (515 tests pass)
• Add styles action to navigator schema
• Add recording* actions to navigator schema
• Add proxy option to launch config
• Update newTab to accept URL
• Remove/gitignore upstream marketplace plugin from fork
• Update navigator's CHANGELOG.md
• Commit bun.lock update
• Create PR

Links

• Upstream diff
• Fork repo
• Navigator schemas

[galligan]

Design Framework Evaluation

Evaluated all v0.6.0 changes against DESIGN.md frameworks.

Framework Application Summary

Feature	Framework	Decision	Rationale
styles	A (New Feature)	Adopt	Agent benefit clear (visual testing, UI verification)
recording_*	A + D (Multiple Related)	Adopt as 3 actions	Cognitively distinct operations (start/stop/restart)
proxy	A (New Feature)	Adopt	Config-level, not action. Specialized testing benefit.
newTab url	Extend Existing	Extend	Convenience (create + navigate in one call)
Marketplace plugin	E (Skip)	Skip	Branding-specific. Navigator has own plugin.
Bug fixes (12)	E (Always Adopt)	Auto-inherited	Stability improvements

Naming Validation

Per DESIGN.md §Naming Conventions:

Upstream	Navigator	Rule Applied
styles	styles	Keep (already optimal)
recording_start	recordingStart	camelCase conversion
recording_stop	recordingStop	camelCase conversion
recording_restart	recordingRestart	camelCase conversion

Design Decision Needed: styles Input

Question: Should styles accept element refs (e42) in addition to CSS selectors?

Option A: Selector only (match upstream)

export const stylesSchema = baseActionSchema.extend({
  action: z.literal('styles'),
  selector: z.string().min(1),
})

• ✓ Simpler, aligned with upstream
• ✗ Doesn't leverage Navigator's ref system

Option B: Support both selector and ref (recommended)

export const stylesSchema = baseActionSchema.extend({
  action: z.literal('styles'),
  selector: z.string().min(1).optional(),
  ref: z.string().regex(/^e\d+(_\d+)?$/).optional(),
}).refine(data => data.selector || data.ref, {
  message: "Either selector or ref required"
})

• ✓ Consistent with Navigator's element ref philosophy (DESIGN.md §Element Reference Philosophy)
• ✓ Executor already maps refs → selectors for other actions
• ✗ Requires translation layer

Recommendation: Option B — element refs are Navigator's primary interface for element interaction.

CLI Mapping (to document)

MCP Action	CLI Command
styles	nav styles <selector|ref>
recordingStart	nav recording start <path> [--url <url>]
recordingStop	nav recording stop
recordingRestart	nav recording restart <path> [--url <url>]

Updated Checklist

Schema changes:

• Add styles action (with ref support decision)
• Add recordingStart action
• Add recordingStop action
• Add recordingRestart action
• Extend newTab with optional url param
• Add proxy to launch config

Other:

• Document CLI commands
• Update CHANGELOG.md
• Remove/gitignore .claude-plugin/ in fork