Add ambient browser runtime bridge

[glittercowboy]

Summary

Adds the daemon side of the ambient GSD Browser loop:

• probes gsd-browser 0.1.20 and advertises runtime state in daemon hello
• starts a local Unix-socket browser RPC bridge for the bundled Pi extension
• registers the ambient gsd_browser tool and bundled browser skill in Pi
• lazy-opens browser sessions from task-scoped grants and emits browser lifecycle/result events
• passes task, session, project, machine, grant, runtime, and socket context into Pi task environments

Dependencies

• gsd-build/protocol-go v0.34.0 is tagged and used by this branch.
• gsd-build/gsd-browser v0.1.20 is tagged for the cloud method manifest/runtime minimum.

Verification

• cd internal/pi/extension && npm test -- browser-tool.test.mjs browser-methods.generated.test.mjs
• go test ./...
• go build -o /tmp/gsd-cloud-browser-ambient-loop .

Post-merge

Tag the daemon release as the next daemon/v0.3.x version and verify the release workflow produces binaries.

Summary by CodeRabbit

• New Features

  • Runtime probing for local browser tooling with detailed readiness and version info.
  • Local JSON-RPC socket for invoking browser tools and ambient browser tool availability even without grant.
  • Browser tool lifecycle events for start/update/result states and richer tool responses.

• Bug Fixes

  • Better handling/reporting for credential gating, approval-required flows, and service errors.

• Documentation

  • Added comprehensive gsd-browser skill documentation.

• Tests

  • New tests covering runtime probing, RPC handling, and browser tool lifecycles.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 85f68afe-9452-439d-9642-c9dfa78db7c6

📥 Commits

Reviewing files that changed from the base of the PR and between 45e2a11 and 0bbbafb.

⛔ Files ignored due to path filters (1)

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

📒 Files selected for processing (19)

• go.mod
• internal/browser/manager.go
• internal/browser/manager_test.go
• internal/browser/runtime_probe.go
• internal/browser/runtime_probe_test.go
• internal/browser/types.go
• internal/loop/browser_rpc.go
• internal/loop/daemon.go
• internal/loop/daemon_test.go
• internal/pi/executor.go
• internal/pi/extension/browser-extension.ts
• internal/pi/extension/browser-methods.generated.test.mjs
• internal/pi/extension/browser-methods.generated.ts
• internal/pi/extension/browser-methods.ts
• internal/pi/extension/browser-tool.test.mjs
• internal/pi/extension/gsd-browser-skill/SKILL.md
• internal/pi/extension/index.ts
• internal/relay/conn.go
• internal/session/actor.go

---

📝 Walkthrough

Walkthrough

Adds browser runtime probing and a Unix-domain RPC for browser tooling; extends browser grant/session handling with ChannelID and an Ensure flow; refactors tool lifecycle to emit structured start/update/result events; propagates browser context through daemon, session, and PI executor layers; adds extension, tests, and skill docs.

Changes

Cohort / File(s)	Summary
Protocol & Dependency go.mod	Bump github.com/gsd-build/protocol-go v0.33.0 → v0.34.0.
Browser Manager Core internal/browser/manager.go, internal/browser/manager_test.go, internal/browser/types.go	Add ChannelID to Grant; add Manager.Ensure and Manager.ToolResult; refactor Tool lifecycle to emit BrowserToolCallStarted/Updated/Result, broaden credential-method detection/rejection, add ToolResult.ErrorCode and ToolRPCRequest types; update tests for lifecycle and credential gating.
Runtime Probe internal/browser/runtime_probe.go, internal/browser/runtime_probe_test.go	Add ProbeRuntime (select binary, parse/version-check, run cloud-methods and daemon health JSON probes); add RequiredRuntimeVersion and RuntimeStatus type; comprehensive tests with fake executable.
Browser RPC Server & Daemon Loop internal/loop/browser_rpc.go, internal/loop/daemon_test.go, internal/loop/daemon.go	Implement length-prefixed Unix socket JSON-RPC browser_tool handler that calls Manager.Ensure and ToolResult; daemon starts runBrowserRPC, uses GSD_BROWSER_PATH, probes runtime per task, and propagates BrowserGrant/BrowserRuntime/BrowserRPCSocket into session actors; add daemon test for RPC handling.
Session & Executor Integration internal/session/actor.go, internal/pi/executor.go	Add BrowserGrant, BrowserRuntimeSnapshot, BrowserRPCSocket to actor Options and taskContext; new Actor.SetBrowserGrant; extend pi.Options with browser fields; refactor browserEnv to accept Options and inject/strip GSD_* env vars (including derived GSD_BROWSER_SKILL_DIR).
PI Extension (TS) & Methods Registry internal/pi/extension/browser-extension.ts, internal/pi/extension/browser-methods.generated.ts, internal/pi/extension/browser-methods.generated.test.mjs, internal/pi/extension/browser-methods.ts, internal/pi/extension/index.ts, internal/pi/extension/browser-tool.test.mjs	Add browser-extension implementing socket RPC client, BrowserGrant helpers, tool registration API; move method/category registry to generated module and exclude credential_auth methods from exposure; always surface browser tool in build flow; update tests and fixtures.
Skill Documentation internal/pi/extension/gsd-browser-skill/SKILL.md	Add skill documentation describing use cases, workflow, sensitive-action policy, and recovery guidance.
Relay Capability Reporting internal/relay/conn.go	Probe browser runtime at client connect and report dynamic browser capability fields (Ready, Installed, version, path, error code/message, cloud methods version, chrome availability).

Sequence Diagram(s)

sequenceDiagram
    actor Client
    participant RPC as Browser RPC Handler
    participant Daemon as Daemon
    participant Mgr as Browser Manager
    participant ES as Event System

    Client->>RPC: send length-prefixed JSON-RPC "browser_tool"
    RPC->>Daemon: validate request & context -> call Manager.Ensure
    Daemon->>Mgr: Ensure(grant/session/project/task/channel/machine/expires)
    alt grant available
        Mgr-->>Daemon: existing Grant
    else need open
        Mgr-->>Mgr: lazy Open session -> re-derive Grant (includes ChannelID)
        Mgr-->>Daemon: new Grant
    end
    RPC->>ES: emit BrowserToolCallStarted
    RPC->>Mgr: call ToolResult(BrowserToolCall)
    alt service success
        Mgr->>ES: BrowserToolCallUpdated(status: "ok")
        Mgr->>ES: BrowserToolResult(OK:true, SessionID/ChannelID,...)
        RPC-->>Client: JSON-RPC response ok (result)
    else credential-method rejected
        Mgr->>ES: BrowserToolCallUpdated(status: "feature_not_enabled"/approval_required)
        Mgr->>ES: BrowserToolResult(ErrorCode: "feature_not_enabled")
        RPC-->>Client: JSON-RPC error (-32001 / tool error)
    else service failure
        Mgr->>ES: BrowserToolCallUpdated(error details)
        Mgr->>ES: BrowserToolResult(ErrorCode: "browser_tool_failed")
        RPC-->>Client: JSON-RPC error (-32001 / tool error)
    end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• Add shared browser session daemon bridge #83: Direct overlap — similar browser manager changes (Ensure, Tool lifecycle, ChannelID) and RPC/socket plumbing.
• Fix browser grants for session tasks #86: Overlapping browser grant/session management and session-indexing work related to manager behavior.
• feat: pi subagent extension with cloud-linked child sessions #108: Related daemon socket path and session/actor option plumbing for browser RPC socket propagation.

Poem

A rabbit taps the socket door, 🐇
Probes the browser, checks the core,
Grants and channels neatly tied,
Events hop out, results supplied —
A tiny hop, a giant browse, hooray! 🎉

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 2.38% 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 clearly summarizes the main change: introducing an ambient browser runtime bridge as a new feature. It is specific, concise, and directly reflects the primary objective of the changeset.
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-ambient-loop

---

_{Review rate limit: 9/10 reviews remaining, refill in 6 minutes.}

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