feat(cloud-agent-sdk): support browser provider jobs

[iscekic]

No new behavior — this change prepares browser task support without changing the product's current controls.

---

Summary

The software development kit (SDK) adds BrowserProviderConnection through UserWebConnectionConfig.browserProvider; omitted values stay permanently disabled. After browserJobsV1 negotiation, retained connections use typed callbacks and short requests; lease loss blocks actions before owner callbacks. Only provider_job offers new work; owners must wait for a running snapshot, and reconnect recovers history without execution replay.

Files

• packages/cloud-agent-sdk/src/user-web-connection.ts — Source; M (modified), 813 changed lines. Requires a matching capability ping/pong before registration or composite parsing. Adds state subscriptions and typed registration, heartbeat, status, approval, cancellation, result, quiescence, and unavailable methods. Validates outbound messages, bounds correlated requests to 10 seconds, and renews leases halfway to expiry. Heartbeat requests require both the matching lease acknowledgement and snapshot. Separates proof-authenticated, cursor-based history from live snapshots, including history after rejected registration or lease loss. History failures leave live leases unchanged. Reconnect retains stable registration data, clears live snapshots, and never replays work, results, or one-shot recovery assertions. Rejects duplicate, foreign, stale, cancelled, or regressive job messages before callbacks. Validates job bindings; results must match the running job and all approved-tab metadata. Expiry, revocation, connection replacement, ticket refresh, and teardown invalidate authority before owner callbacks. Cancelling approved work revokes the lease; cancelling queued or unapproved work preserves it. Allows quiescence for completed or cancelled jobs after lease loss while the binding survives. Explicit unavailability prevents automatic registration, even when sending fails. Sanitizes provider and authentication errors, ignores late sockets and stale refreshes, and stops callbacks after release or destruction.
• packages/cloud-agent-sdk/src/user-web-connection.test.ts — Test; M (modified), 1,377 added lines. Adds fake-timer fixtures and an in-process harness using the real relay. Covers legacy compatibility, negotiation, request timeouts, generation checks, job updates, cancellation, lease expiry, ticket loss, historical recovery, teardown, and error redaction.

Public exports add BrowserProviderConnection, BrowserProviderState, BrowserProviderError, and BrowserProviderErrorCode; the private browserProviderErrorSchema validates relay failures without exposing their text. Lease and history callers receive BrowserProviderRegistration, BrowserProviderLease, BrowserProviderSnapshot, BrowserProviderStatusResult, BrowserJobHandle, BrowserJobSnapshot, BrowserProviderInboundMessage, BrowserProviderOutboundMessage, and BrowserResult. Typed operations use BrowserProviderApprovalInput, BrowserProviderCancelInput, BrowserProviderResultInput, BrowserProviderQuiescenceInput, and BrowserProviderUnavailableInput, without changing the existing UserWebConnection contract or legacy inbound union.

Files

• packages/cloud-agent-sdk/src/index.ts — Source; M (modified), 22 changed lines. Exposes the provider error class and provider connection, state, operation, message, job, lease, and history types through the package entry point.

Tests: 1 modified test file, packages/cloud-agent-sdk/src/user-web-connection.test.ts, with 1,377 added lines.
Generated: 0 files changed.

---

Verification

The handoff reports no manual verification. Runtime verification remains pending on the stack tips. The handoff includes no end-to-end (E2E) report.

Visual Changes

Visual Changes: N/A

Reviewer Notes

Human steps

• before merge — After all section pull requests receive human-ready, merge each repository's levels from bottom to top.
• after merge — Existing callers need no manual setup, new environment values, secrets, migrations, or flag changes.

Automated checks

The recorded scoped checks passed 5/5. The evidence covers local checks only; it does not establish continuous integration (CI) or live verification.

Recorded local check	Result
oxfmt --write on the three changed files	Passed
oxlint --deny-warnings on the three changed files	Passed
Scoped user-web-connection.test.ts Jest suite	Passed; 114 tests
oxfmt --check on the three changed files	Passed
git diff --check on the three changed files	Passed

Scope and dependencies

This description covers Cloud level 4 only. The lower levels own the prerequisite history contracts, ledger reads, and relay routing.

• Immediate base: Cloud #5648.
• Lower Cloud levels: Cloud #5638 and Cloud #5644.
• Command-line interface (CLI) contracts: kilocode #13535. Matching base contracts have landed; history contract parity remains pending.

Worktrees

• Kilo-Org/cloud: /Users/igor/Projects/.worktrees/browser-task-0787, branch browser-task-0787-s4; comparison base browser-task-0787-s3.
• Kilo-Org/kilocode: /Users/igor/Projects/.worktrees/browser-task-0787-kilocode, branch browser-task-0787; related contracts only, outside this level's diff.

Notes

Runtime verification remains pending on the stack tips. The provider transport is opt-in; the extension integration follows in later levels.

Stacked PRs — merge bottom to top. Each level shows only its own diff.

Runtime verification (E2E, user advocacy, simplify) runs on the tip PR over every level.
Every level keeps its own checks, its own bot review, and its own threads; each one is answered on its own PR.
Each level is its own deliverable: it builds and passes its own checks alone.
A finding on a level is repaired on that level, then carried upward with stack.sh forward.

1. browser-task-0787 — feat(browser-task): define negotiated job contracts #5638
2. browser-task-0787-s2 — feat(session-ingest): persist owned browser jobs #5644
3. browser-task-0787-s3 — feat(session-ingest): route fenced browser providers #5648
4. browser-task-0787-s4 — feat(cloud-agent-sdk): support browser provider jobs #5653 ← this PR
5. browser-task-0787-s7 — fix(extension): expose honest browser runner outcomes #5681
6. browser-task-0787-s8 — feat(extension): coordinate browser execution across panels #5694
7. browser-task-0787-s9 — fix(extension): invalidate ended browser task approvals #5698 (tip)

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

Files Reviewed (3 files)

• packages/cloud-agent-sdk/src/index.ts
• packages/cloud-agent-sdk/src/user-web-connection.ts
• packages/cloud-agent-sdk/src/user-web-connection.test.ts

---

_{Reviewed by grok-4.6 · Input: 211.1K · Output: 20.7K · Cached: 610.8K}

_{Review guidance: REVIEW.md from base branch browser-task-0787-s3}