feat(browser-task): define negotiated job contracts

[iscekic]

Summary

No new behavior — this change prepares browser delegation but does not enable it.

---

Maintainer's changelog

browserJobsV1 adds dormant BrowserTaskArguments, BrowserRequest, BrowserResponse, BrowserEvent, BrowserJobHandle, BrowserJobSnapshot, BrowserResult, BrowserProviderOutboundMessage, and BrowserProviderInboundMessage contracts. Strict schemas bind ownership, approvals, identities, deadlines, and results while bounding data and keeping proofs out of validation errors. The relay and software development kit (SDK) duplicate these contracts for separate consumers; maintainers must keep the copies aligned.

Files

• services/session-ingest/src/types/user-connection-protocol.ts — M; Source; +494/-0, or 494 changed lines. Defines model operations list, run, status, cancel, and recover; the command-line interface (CLI) uses invoke instead of run. Model arguments cannot select parent, invocation, proof, user, or connection authority. Owned requests require parentSessionId and parentProof; status and cancel require a conversation ID, even with an exact job ID. The lookup contract reserves an omitted jobId for the conversation's latest job after owner verification. Recovery accepts ownership and an invocation ID, not a new goal or provider. Correlated responses distinguish provider discovery, invoke/cancel acknowledgments, status, recovery, missing invocations, and errors; acknowledgments do not carry progress or terminal results. Distinct prefixed universally unique identifiers (UUIDs) identify providers, conversations, and jobs; request IDs use UUIDs. Invocation IDs use b1.<timestamp>.<digest>; timestamps remain within the safe date range, and proofs and fingerprints require 64 lowercase hexadecimal characters. Snapshots distinguish queued, awaiting_approval, running, succeeded, failed, cancelled, interrupted, and timed_out. Terminal snapshots require matching result identities and status; progress events reject terminal results. Success requires completed and effectsUncertain: false; other terminal states use finite failure reasons. Metadata requires bounded generations, millisecond timestamps, a payload fingerprint, and deadlines within retention. Provider discovery exposes labels, availability, and queue depth from zero through 100.
• packages/cloud-agent-sdk/src/schemas.ts — M; Source; +505/-1, or 506 changed lines. Mirrors the browser contracts and adds outbound web validation and opt-in provider parsers. Provider messages cover registration, heartbeat, approval, results, quiescence, unavailability, exact-job cancellation, dispatch, snapshots, and lease acknowledgments. Only registration accepts providerProof; generation zero represents first registration, and recovery requires tabClosed: true and locksDrained: true. Approval, results, quiescence, and cancellation carry the job identity and a positive generation. Provider results must match their job; provider snapshots must match their provider and generation. Dispatch accepts only awaiting_approval jobs; snapshots reconcile state and do not grant execution permission. Approved tabs include a bounded integer ID, title, address, and safe or dangerous mode. Queued and awaiting-approval snapshots reject approved tabs; running snapshots require them. Text limits count 8-bit Unicode Transformation Format (UTF-8) bytes. Goals allow 16,384 bytes; results allow 65,536 serialized bytes; complete frames must remain below 131,072 serialized bytes. Discovery and snapshot pages allow 25 entries; results allow 32 evidence items containing text, title, or a valid address. Labels and parent IDs allow 128 bytes; titles and error messages allow 1,024 bytes. Evidence text and addresses allow 8,192 bytes; result summaries allow 32,768 bytes. New browser boundaries reject unknown fields. The generic Invalid browser message error omits proof values and unknown key names; consumers must not enable Zod's reportInput.

normalizedBrowserCapabilitiesSchema produces BrowserCapabilities with missing browserJobsV1 support set to false; heartbeat, heartbeat_ack, ping, and pong retain optional advertisements. The new webOutboundMessageSchema validates existing web commands, including optional mutationId values limited to 128 characters. Separate cliOutboundWithBrowserMessageSchema, cliInboundWithBrowserMessageSchema, webOutboundWithBrowserMessageSchema, and webInboundWithBrowserMessageSchema preserve legacy variants and callbacks; consumers must opt in before accepting browser traffic.

Files

• services/session-ingest/src/types/user-connection-protocol.test.ts — M; Test; +1,017/-0, or 1,017 changed lines. Exercises both copies against canonical frames, authority rejection, proof redaction, malformed identities, invalid states, approval, recovery, byte limits, pagination, and directions. Adds legacy frames and frozen callback types to check compatibility without widening legacy parser unions.
• packages/cloud-agent-sdk/src/schemas.test.ts — M; Test; +310/-0, or 310 changed lines. Adds relay/SDK parity fixtures, capability normalization cases, direction checks, and compatibility checks for legacy callbacks, commands, results, and errors. Preserves legacy handling of unknown fields and verifies that only opt-in parsers accept browser frames.

Tests: 2 files modified — schemas.test.ts and user-connection-protocol.test.ts; 1,327 lines added.
Generated: 0 files changed.

---

Verification

No manual or end-to-end tests ran for this level because it adds dormant schemas and does not enable browser delegation. Runtime verification remains pending on the stack tips; no end-to-end report is attached.

Visual Changes

Visual Changes: N/A

Reviewer Notes

Human steps

• before merge: Do not request review now.
• before merge: After every pull request receives human-ready, merge each repository's levels from bottom to top.
• This level needs no environment changes, secret provisioning, migration, flag change, or separate deployment step.

Recorded automated checks

The handoff records seven passing scoped checks and 252 passing cases across the two changed protocol suites. These local results do not establish live verification, continuous integration (CI), or a passing section gate.

Scoped check	Recorded result
Formatting for all four changed files	Passed
Oxlint for all four changed files	Passed
Relay protocol suite	Passed
SDK schema suite	Passed
Strict TypeScript check for both schemas and both suites	Passed
Oxfmt format check for all four changed files	Passed
Git whitespace check for all four changed files	Passed

Repository scope

• Kilo-Org/cloud: /Users/igor/Projects/.worktrees/browser-task-0787; branch browser-task-0787; base origin/main. This level changes four files, with 2,326 added lines and one deleted line.
• Kilo-Org/kilocode: /Users/igor/Projects/.worktrees/browser-task-0787-kilocode; branch browser-task-0787; base origin/main. The matching CLI contracts are published in Kilo-Org/kilocode#13535. Both schema levels remain dormant.

Notes

Runtime verification remains pending on the stack tips. This level adds dormant schemas and does not enable browser delegation.

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 ← this PR
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 (tip)

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

Files Reviewed (4 files)

• packages/cloud-agent-sdk/src/schemas.ts
• packages/cloud-agent-sdk/src/schemas.test.ts
• services/session-ingest/src/types/user-connection-protocol.ts
• services/session-ingest/src/types/user-connection-protocol.test.ts

Previous Review Summary (commit 8087941)

Current summary above is authoritative. Previous snapshots are kept for context only.

Previous review (commit 8087941)

Status: No Issues Found | Recommendation: Merge

Files Reviewed (4 files)

• packages/cloud-agent-sdk/src/schemas.ts
• packages/cloud-agent-sdk/src/schemas.test.ts
• services/session-ingest/src/types/user-connection-protocol.ts
• services/session-ingest/src/types/user-connection-protocol.test.ts

---

_{Reviewed by grok-4.6 · Input: 54.4K · Output: 9.2K · Cached: 402K}

_{Review guidance: REVIEW.md from base branch main}