Skip to content

Extend browser workbench protocol#44

Merged
glittercowboy merged 3 commits intomainfrom
codex/gsd-browser-workbench-protocol
May 1, 2026
Merged

Extend browser workbench protocol#44
glittercowboy merged 3 commits intomainfrom
codex/gsd-browser-workbench-protocol

Conversation

@glittercowboy
Copy link
Copy Markdown
Contributor

@glittercowboy glittercowboy commented May 1, 2026

Summary

  • Adds browser control state, claim-and-input, user-input ack, evidence, artifact, and identity fields to the protocol envelope.
  • Adds validation coverage for browser approval and control messages.
  • Documents protocol v0.35.0 as the required downstream tag for daemon and cloud-app relay consumers.

Verification

  • go test ./...

Dependency order

  1. Merge this PR and tag v0.35.0.
  2. Update daemon and cloud-app relay consumers to github.com/gsd-build/protocol-go@v0.35.0.
  3. Merge browser runtime, daemon, then cloud-app PRs.

Post-merge actions

  • Create and push protocol tag v0.35.0.

Summary by CodeRabbit

  • New Features

    • Identity-scoped browser sessions, identity lifecycle events, control/claim workflows, viewport-setting, and evidence/debug bundle messages
    • Expanded sensitive-action approval requests and richer approval responses
  • Improvements

    • Enhanced frame/viewport/capture metadata (scaling, encoding, latency, sequencing)
    • Broader user input variants (modifiers, pointer/click/key/text/deltas, URLs/actions) and more explicit ack/acceptance metadata
  • Tests

    • End-to-end, unknown-field tolerance, type-validation, and approval-field validation tests for the browser/workbench protocol

@coderabbitai
Copy link
Copy Markdown

coderabbitai Bot commented May 1, 2026

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: e0f1ad58-03bb-490a-b637-a13938f11bf7

📥 Commits

Reviewing files that changed from the base of the PR and between ab5e273 and 8b3e1d9.

📒 Files selected for processing (1)
  • messages_test.go
🚧 Files skipped from review as they are similar to previous changes (1)
  • messages_test.go

📝 Walkthrough

Walkthrough

Extends the browser protocol and Go implementation with control/claim messages, richer frame/viewport/capture metadata, identity/evidence and identity-lifecycle messages, expanded user-input/ack schemas, sensitive-action approval fields with validation, envelope payload mappings, and tests.

Changes

Browser Protocol and Message Type Expansion

Layer / File(s) Summary
Protocol Spec
PROTOCOL.md
Adds identity-scoping to browserSessionOpen; expands browserFrame with viewport/capture/encoding/latency fields; introduces control messages browserControlClaimRequest, browserControlState, browserClaimAndInput; extends browserUserInput/browserUserInputAck; adds browserViewportSet; adds "Browser Identity And Evidence" with browserEvidenceCreated/browserDebugBundleCreated; expands browserSensitiveActionRequest/browserSensitiveActionResponse with approval/security fields.
Message Type Constants & Imports
messages.go (imports, consts)
Adds many MsgTypeBrowser* constants, new BrowserInputKind* and rejection-reason constants; adds fmt import for validation errors.
Core Message Structs
messages.go (Browser* structs)
Extends BrowserSessionOpen, BrowserFrame, BrowserArtifactCreated, BrowserUserInput, BrowserUserInputAck, BrowserSensitiveActionRequest/Response; adds new structs: BrowserControlState, BrowserControlClaimRequest, BrowserClaimAndInput, BrowserEvidenceCreated, BrowserDebugBundleCreated, BrowserIdentity* types, BrowserViewportSet.
Validation Logic
messages.go (validation helper & methods)
Adds ValidateApprovalFields() on BrowserSensitiveActionRequest and BrowserSensitiveActionResponse and shared validateBrowserApprovalFields(...) helper using fmt.Errorf.
Envelope Payload Mapping
envelope.go (payloadForType switch)
payloadForType extended to return concrete payload types for the new MsgTypeBrowser* values.
Tests
messages_test.go
Adds round-trip contract tests for new browser/workbench messages, unknown-field tolerance tests, invalid-field-type rejection tests, BrowserUserInputAck reason/safeRetry preservation tests, and approval-field validation tests for request/response.

Sequence Diagram(s)

sequenceDiagram
    participant Client
    participant ControlSvc as Control Service
    participant Browser as Browser Host
    participant Identity as Identity Store

    Client->>ControlSvc: Send browserControlClaimRequest (claim + metadata)
    ControlSvc->>Browser: Announce/assign control via browserControlState
    Client->>ControlSvc: Send browserClaimAndInput (claim + BrowserUserInput)
    ControlSvc->>Browser: Forward BrowserUserInput
    Browser->>ControlSvc: Reply BrowserUserInputAck (accepted/denied/reason/safeRetry)
    Browser->>Identity: Emit browserEvidenceCreated / browserDebugBundleCreated
    Identity->>ControlSvc: Emit BrowserIdentitySaved / BrowserIdentityAvailable
Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

Poem

🐰 I nibbled specs by moonlit light,

Claims and frames and inputs bright.
Identities, evidence all in tow,
Acks that tell me yes or no.
Tiny rabbit hops — protocol, go!

🚥 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 'Extend browser workbench protocol' directly and accurately describes the main change: extending the browser workbench protocol with new message types, fields, and validation.
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/gsd-browser-workbench-protocol

Review rate limit: 6/10 reviews remaining, refill in 23 minutes and 7 seconds.

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

Copy link
Copy Markdown

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick comments (1)
messages_test.go (1)

15-277: 💤 Low value

Consider adding unknown/invalid field handling tests for new message types.

Per coding guidelines, tests should verify "unknown/invalid payload handling, and protocol compatibility behavior." The existing test suite has TestBrowserEnvelopeIgnoresUnknownFields and TestBrowserEnvelopeRejectsInvalidFieldTypes for other browser messages. The new control/identity/evidence messages would benefit from similar coverage to ensure forward compatibility and type safety.

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@messages_test.go` around lines 15 - 277, Add tests that assert ParseEnvelope
ignores unknown fields and rejects invalid field types for each new message
struct (e.g., BrowserControlState, BrowserControlClaimRequest,
BrowserClaimAndInput, BrowserEvidenceCreated, BrowserDebugBundleCreated,
BrowserIdentityAvailable/Saved/Revoked/Used/Bind/Unbind/UseApproved,
BrowserViewportSet, BrowserSensitiveActionRequest/Response). Mirror the patterns
from TestBrowserEnvelopeIgnoresUnknownFields and
TestBrowserEnvelopeRejectsInvalidFieldTypes: construct JSON for each message,
inject an extra unknown field and assert ParseEnvelope still decodes the payload
(using mustJSONMap/jsonEqual), and construct JSON with wrong types for required
fields and assert ParseEnvelope returns an error; use ParseEnvelope and the
existing helper functions to locate and validate behavior.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@messages_test.go`:
- Around line 15-277: Add tests that assert ParseEnvelope ignores unknown fields
and rejects invalid field types for each new message struct (e.g.,
BrowserControlState, BrowserControlClaimRequest, BrowserClaimAndInput,
BrowserEvidenceCreated, BrowserDebugBundleCreated,
BrowserIdentityAvailable/Saved/Revoked/Used/Bind/Unbind/UseApproved,
BrowserViewportSet, BrowserSensitiveActionRequest/Response). Mirror the patterns
from TestBrowserEnvelopeIgnoresUnknownFields and
TestBrowserEnvelopeRejectsInvalidFieldTypes: construct JSON for each message,
inject an extra unknown field and assert ParseEnvelope still decodes the payload
(using mustJSONMap/jsonEqual), and construct JSON with wrong types for required
fields and assert ParseEnvelope returns an error; use ParseEnvelope and the
existing helper functions to locate and validate behavior.

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: c024e038-f144-4cb9-9da9-c679514e178d

📥 Commits

Reviewing files that changed from the base of the PR and between e5a44f5 and a8ee03b.

📒 Files selected for processing (4)
  • PROTOCOL.md
  • envelope.go
  • messages.go
  • messages_test.go

Copy link
Copy Markdown

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 `@messages_test.go`:
- Around line 311-339: Add a parallel test that verifies
BrowserSensitiveActionResponse.ValidateApprovalFields enforces the same required
fields as the request test: create a valid BrowserSensitiveActionResponse with
ApprovalID, Nonce, ParameterHash, ExpiresAt set (matching values used in
TestBrowserSensitiveApprovalValidation), assert no error from
ValidateApprovalFields(), then iterate the same table of mutations (setting
ApprovalID, Nonce, ParameterHash, ExpiresAt to empty) and assert each mutated
response returns an error; name the new test e.g.
TestBrowserSensitiveApprovalResponseValidation and call
BrowserSensitiveActionResponse.ValidateApprovalFields() to ensure parity with
BrowserSensitiveActionRequest.ValidateApprovalFields().
- Around line 279-309: Update TestBrowserUserInputAckCarriesReasonCode to
include compatibility cases for the new BrowserUserInputAck fields: add a
subtest that injects an invalid-type for ReasonCode (e.g. set "ReasonCode":
"invalid-string" in the raw JSON) and assert ParseEnvelope/raw-unmarshal
behavior matches the rest of this test file's compatibility expectations (i.e.
parsing fails/returns error or rejects the payload as the suite requires), and
add another subtest that adds an unknown extra field (e.g. "unknown_extra": 42)
to the JSON and assert ParseEnvelope still succeeds and the returned
env.Payload.(*BrowserUserInputAck) preserves the known fields (Type, BrowserID,
SafeRetry, etc.)—use the existing TestBrowserUserInputAckCarriesReasonCode,
BrowserUserInputAck struct, and ParseEnvelope helper to locate and implement
these checks.
🪄 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: 48c1f38a-f51e-4cc5-aef0-cd75fba94bb5

📥 Commits

Reviewing files that changed from the base of the PR and between a8ee03b and ab5e273.

📒 Files selected for processing (1)
  • messages_test.go

Comment thread messages_test.go
Comment thread messages_test.go
@glittercowboy glittercowboy merged commit ff3d347 into main May 1, 2026
2 checks passed
@glittercowboy glittercowboy deleted the codex/gsd-browser-workbench-protocol branch May 1, 2026 23:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant