Expose full GSD browser tool schema

[glittercowboy]

Summary

• Expands the Pi gsd_browser schema to the categorized cloud browser method registry.
• Forwards browser refs from the local browser daemon to the relay.
• Gates sensitive browser actions behind approval and blocks agent-owned vault saves.
• Routes Lex-owned browser commands through the same local browser tool path.
• Bumps github.com/gsd-build/protocol-go to v0.33.0.

Verification

• go test ./...
• npm test from internal/pi/extension

Dependency

• Requires protocol-go v0.33.0, tagged from Add browser refs and command input protocol protocol-go#42.

Summary by CodeRabbit

• New Features

  • Browser references are now captured and published alongside frame data.
  • Sensitive browser actions require explicit approval with a 2-minute expiry.
  • Browser methods are risk-classified to determine approval needs.
  • User input commands (navigate, click, etc.) are mapped directly to browser tools.
  • Agent-initiated vault operations are blocked from execution.

• Tests

  • Expanded coverage for refs, approval flows, and risk classification.

• Chores

  • Updated protocol dependency to latest version.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 300df8ad-9af8-48f2-b7c5-949268a2dac2

📥 Commits

Reviewing files that changed from the base of the PR and between 8f6e3b5 and d753c69.

📒 Files selected for processing (3)

• internal/browser/manager.go
• internal/browser/manager_test.go
• internal/browser/safety.go

---

📝 Walkthrough

Walkthrough

The PR adds browser reference capture and publishing, implements risk-based approval gating for sensitive browser tool operations, introduces a safety classification system to categorize tool risks, updates the browser service with a new Refs RPC pathway, and centralizes browser tool method taxonomy in TypeScript schemas. It also extends sidebar user input command support.

Changes

Cohort / File(s)	Summary
Dependency & Types go.mod, internal/browser/types.go	Bumps github.com/gsd-build/protocol-go to v0.33.0 and adds Refs/Ref types (version, refs list, capturedAt, x/y/w/h).
Manager & Control Flow internal/browser/manager.go, internal/browser/manager_test.go	Adds sendRefs publish after frames; enforces pre-execution risk gating for tools (sends BrowserSensitiveActionRequest, blocks execution when approval required, rolls back owner/version on failures); adds helper to format approval summary; tests added for refs, user-input routing, sensitive-action blocking, rollback, and risk classification.
Safety Classification internal/browser/safety.go	New BrowserRisk type, risk constants, classifyBrowserTool (including recursive batch handling), browserRiskRequiresApproval, and riskRank utilities.
Service & RPC internal/browser/service.go, internal/loop/daemon_test.go	Adds Service.Refs(ctx, browserID) to fetch/normalize cloud_refs (version, refs, capturedAt derivation); test stub implements Refs.
PI Extension Schema & Tests internal/pi/extension/browser-methods.ts, internal/pi/extension/index.ts, internal/pi/extension/browser-tool.test.mjs	Introduces centralized browser method/category lists and TypeBox schemas; refactors browser tool parameter typing to use external schemas; tests assert method list, categories, and mappings.

Sequence Diagram(s)

sequenceDiagram
    participant BrowserManager
    participant Service
    participant CloudAPI as Cloud API
    participant SessionOwner as Session Owner

    rect rgba(70, 130, 180, 0.5)
    Note over BrowserManager,CloudAPI: Tool invocation with sensitive-operation gating
    BrowserManager->>BrowserManager: Tool(method, params) invoked
    BrowserManager->>BrowserManager: classifyBrowserTool(method, params)
    alt RiskRequiresApproval
        BrowserManager->>BrowserManager: set owner -> OwnerApproval, bump controlVersion
        BrowserManager->>CloudAPI: Emit BrowserSensitiveActionRequest (2m expiry)
        BrowserManager->>SessionOwner: Await approval (external)
        BrowserManager-->>BrowserManager: Return error (do not call Service.Tool)
    else Allowed
        BrowserManager->>Service: Tool(ctx, method, params)
        Service-->>BrowserManager: Tool result
    end
    end

Loading

sequenceDiagram
    participant BrowserManager
    participant Service
    participant CloudAPI as Cloud API

    rect rgba(34, 139, 34, 0.5)
    Note over BrowserManager,CloudAPI: Frame emission with refs publishing
    BrowserManager->>CloudAPI: Emit BrowserFrame
    BrowserManager->>Service: Refs(ctx, browserID) with 10s timeout
    Service->>CloudAPI: cloud_refs RPC
    CloudAPI-->>Service: version, refs, capturedAtMs
    Service-->>BrowserManager: Refs {Version, Refs, CapturedAt}
    BrowserManager->>CloudAPI: Emit BrowserRefs (normalized protocol.BrowserRef[])
    end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~50 minutes

Possibly related PRs

• Add shared browser session daemon bridge #83: Directly related — overlapping changes to browser subsystem (manager, service, types, PI extension).
• Enforce browser control ownership #119: Related — modifies internal/browser/manager.go and associated tests affecting tool handling and frame behavior.
• Fix GSD browser tool grant contract #123: Related — changes PI extension browser tool schema/registration in internal/pi/extension/*.

Poem

🐰 Hops and whispers through the frame,

Refs now bloom and callers name,
Gates of caution softly stand,
Approval clutches steady hand,
A rabbit cheers — safe browsing's planned.

🚥 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
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Expose full GSD browser tool schema' directly relates to the main changes: externalizing the browser tool method/category definitions and updating the Pi extension to use centralized schemas.
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 docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/browser-tool-schema

---

_{Review rate limit: 7/10 reviews remaining, refill in 16 minutes and 45 seconds.}

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

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@internal/browser/manager.go`:
- Around line 482-513: The two branches that call m.sender.Send (the vault_save
rejection branch and the approval branch inside the
browserRiskRequiresApproval(risk) path) ignore send errors and leave the browser
state changed (state.owner = OwnerApproval and state.controlVersion++ in the
approval path), so detect and handle failures from m.sender.Send: capture the
error returned by m.sender.Send in both branches, and if it fails roll back the
state changes (reset state.owner from OwnerApproval and decrement/restore
state.controlVersion as applicable), ensure m.mu is unlocked consistently, and
return the send error (or a wrapped error) instead of suppressing it; locate
these changes around the m.sender.Send calls and the state mutation in the
browserRiskRequiresApproval branch and in the vault_save branch to implement the
rollback and proper error return.

In `@internal/browser/safety.go`:
- Around line 35-65: classifyBrowserBatch currently treats JSON unmarshal
failures and steps missing a method/action as low-risk (BrowserRiskInspection);
change it to fail closed by returning/upgrading to BrowserRiskExternalEffect in
those cases: when json.Unmarshal(params, &payload) returns an error, return
BrowserRiskExternalEffect; when iterating steps if method=="" (after using
stringValue) treat that step as BrowserRiskExternalEffect (i.e., set nested =
BrowserRiskExternalEffect rather than skipping) so riskRank logic will escalate
the batch appropriately; keep using classifyBrowserTool and riskRank for normal
cases.

🪄 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: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 52fe8c97-c468-49d8-bd75-fc3838c476d9

📥 Commits

Reviewing files that changed from the base of the PR and between 82e0817 and 8f6e3b5.

⛔ Files ignored due to path filters (1)

• go.sum is excluded by !**/*.sum

📒 Files selected for processing (10)

• go.mod
• internal/browser/manager.go
• internal/browser/manager_test.go
• internal/browser/safety.go
• internal/browser/service.go
• internal/browser/types.go
• internal/loop/daemon_test.go
• internal/pi/extension/browser-methods.ts
• internal/pi/extension/browser-tool.test.mjs
• internal/pi/extension/index.ts