feat(protocol): add browser contracts

packages/protocol/src/browser-control.ts

@@ -0,0 +1,77 @@
+export * as BrowserControlProtocol from "./browser-control.js"
+
+import { BrowserControl } from "@opencode-ai/schema/browser-control"
+import { Effect, Schema } from "effect"
+
+export const MaxMessageBytes = 8 * 1_024 * 1_024
+
+export class MessageError extends Schema.TaggedErrorClass<MessageError>()("BrowserControlProtocol.MessageError", {
+  kind: Schema.Literals(["invalid", "too_large"]),
+  message: Schema.String,
+  cause: Schema.optional(Schema.Defect()),
+}) {}
+
+const decoder = new TextDecoder("utf-8", { fatal: true })
+const encoder = new TextEncoder()
+const encodeDesktop = Schema.encodeSync(Schema.fromJsonString(BrowserControl.FromDesktop))
+const encodeServer = Schema.encodeSync(Schema.fromJsonString(BrowserControl.FromServer))
+const decodeDesktop = Schema.decodeUnknownEffect(Schema.fromJsonString(BrowserControl.FromDesktop), {
+  errors: "all",
+  onExcessProperty: "error",
+})
+const decodeServer = Schema.decodeUnknownEffect(Schema.fromJsonString(BrowserControl.FromServer), {
+  errors: "all",
+  onExcessProperty: "error",
+})
+
+export function encodeFromDesktop(input: BrowserControl.FromDesktop) {
+  return encode(input, encodeDesktop)
+}
+
+export function encodeFromServer(input: BrowserControl.FromServer) {
+  return encode(input, encodeServer)
+}
+
+function encode<Message>(input: Message, encodeMessage: (input: Message) => string) {
+  const output = encodeMessage(input)
+  if (encoder.encode(output).byteLength > MaxMessageBytes) {
+    throw new RangeError(`Browser control message must not exceed ${MaxMessageBytes} bytes.`)
+  }
+  return output
+}
+
+export function decodeFromDesktop(input: string | Uint8Array) {
+  return decode(input, decodeDesktop)
+}
+
+export function decodeFromServer(input: string | Uint8Array) {
+  return decode(input, decodeServer)
+}
+
+function decode<Message>(
+  input: string | Uint8Array,
+  decodeMessage: (input: unknown) => Effect.Effect<Message, unknown>,
+): Effect.Effect<Message, MessageError> {
+  if (typeof input === "string" && encoder.encode(input).byteLength > MaxMessageBytes) {
+    return Effect.fail(new MessageError({ kind: "too_large", message: "Browser control message is too large." }))
+  }
+  if (typeof input !== "string" && input.byteLength > MaxMessageBytes) {
+    return Effect.fail(new MessageError({ kind: "too_large", message: "Browser control message is too large." }))
+  }
+  const text =
+    typeof input === "string"
+      ? Effect.succeed(input)
+      : Effect.try({
+          try: () => decoder.decode(input),
+          catch: (cause) =>
+            new MessageError({ kind: "invalid", message: "Browser control message is not valid UTF-8.", cause }),
+        })
+  return text.pipe(
+    Effect.flatMap(decodeMessage),
+    Effect.mapError((cause) =>
+      cause instanceof MessageError
+        ? cause
+        : new MessageError({ kind: "invalid", message: "Browser control message is invalid.", cause }),
+    ),
+  )
+}

packages/protocol/src/browser-tunnel.ts

@@ -0,0 +1,117 @@
+export * as BrowserTunnelProtocol from "./browser-tunnel.js"
+
+import { BrowserTunnel } from "@opencode-ai/schema/browser-tunnel"
+import { Effect, Schema } from "effect"
+
+export const FrameType = {
+  Data: 0,
+  Control: 1,
+} as const
+
+export const MaxDataBytes = 64 * 1_024
+export const MaxControlBytes = 16 * 1_024
+export const InitialWindowBytes = 256 * 1_024
+export const InitialFrameWindow = 16
+
+export class FrameError extends Schema.TaggedErrorClass<FrameError>()("BrowserTunnelProtocol.FrameError", {
+  kind: Schema.Literals(["invalid", "too_large"]),
+  message: Schema.String,
+  cause: Schema.optional(Schema.Defect()),
+}) {}
+
+export type DataFrame = {
+  readonly type: "data"
+  readonly data: Uint8Array
+}
+
+export type ControlFrame<Message> = {
+  readonly type: "control"
+  readonly message: Message
+}
+
+export type FromDesktop = DataFrame | ControlFrame<BrowserTunnel.FromDesktop>
+export type FromServer = DataFrame | ControlFrame<BrowserTunnel.FromServer>
+
+const encoder = new TextEncoder()
+const decoder = new TextDecoder("utf-8", { fatal: true })
+const encodeDesktop = Schema.encodeSync(Schema.fromJsonString(BrowserTunnel.FromDesktop))
+const encodeServer = Schema.encodeSync(Schema.fromJsonString(BrowserTunnel.FromServer))
+const decodeDesktop = Schema.decodeUnknownEffect(Schema.fromJsonString(BrowserTunnel.FromDesktop), {
+  errors: "all",
+  onExcessProperty: "error",
+})
+const decodeServer = Schema.decodeUnknownEffect(Schema.fromJsonString(BrowserTunnel.FromServer), {
+  errors: "all",
+  onExcessProperty: "error",
+})
+
+export function data(input: Uint8Array) {
+  if (input.byteLength === 0 || input.byteLength > MaxDataBytes) {
+    throw new RangeError(`Browser tunnel data must contain between 1 and ${MaxDataBytes} bytes.`)
+  }
+  const frame = new Uint8Array(input.byteLength + 1)
+  frame[0] = FrameType.Data
+  frame.set(input, 1)
+  return frame
+}
+
+export function encodeFromDesktop(input: BrowserTunnel.FromDesktop) {
+  return control(encodeDesktop(input))
+}
+
+export function encodeFromServer(input: BrowserTunnel.FromServer) {
+  return control(encodeServer(input))
+}
+
+function control(input: string) {
+  const payload = encoder.encode(input)
+  if (payload.byteLength > MaxControlBytes) {
+    throw new RangeError(`Browser tunnel control data must not exceed ${MaxControlBytes} bytes.`)
+  }
+  const frame = new Uint8Array(payload.byteLength + 1)
+  frame[0] = FrameType.Control
+  frame.set(payload, 1)
+  return frame
+}
+
+export function decodeFromDesktop(input: string | Uint8Array): Effect.Effect<FromDesktop, FrameError> {
+  return decode(input, decodeDesktop)
+}
+
+export function decodeFromServer(input: string | Uint8Array): Effect.Effect<FromServer, FrameError> {
+  return decode(input, decodeServer)
+}
+
+function decode<Message>(
+  input: string | Uint8Array,
+  decodeMessage: (input: unknown) => Effect.Effect<Message, unknown>,
+): Effect.Effect<DataFrame | ControlFrame<Message>, FrameError> {
+  if (typeof input === "string" || input.byteLength === 0) {
+    return Effect.fail(new FrameError({ kind: "invalid", message: "Browser tunnel frames must use binary framing." }))
+  }
+  if (input[0] === FrameType.Data) {
+    if (input.byteLength === 1 || input.byteLength > MaxDataBytes + 1) {
+      return Effect.fail(new FrameError({ kind: "too_large", message: "Browser tunnel data frame size is invalid." }))
+    }
+    return Effect.succeed({ type: "data", data: input.subarray(1) })
+  }
+  if (input[0] !== FrameType.Control) {
+    return Effect.fail(new FrameError({ kind: "invalid", message: "Browser tunnel frame type is invalid." }))
+  }
+  if (input.byteLength > MaxControlBytes + 1) {
+    return Effect.fail(new FrameError({ kind: "too_large", message: "Browser tunnel control frame is too large." }))
+  }
+  return Effect.try({
+    try: () => decoder.decode(input.subarray(1)),
+    catch: (cause) =>
+      new FrameError({ kind: "invalid", message: "Browser tunnel control frame is not valid UTF-8.", cause }),
+  }).pipe(
+    Effect.flatMap(decodeMessage),
+    Effect.map((message) => ({ type: "control" as const, message })),
+    Effect.mapError((cause) =>
+      cause instanceof FrameError
+        ? cause
+        : new FrameError({ kind: "invalid", message: "Browser tunnel control frame is invalid.", cause }),
+    ),
+  )
+}

packages/protocol/src/groups/browser.ts

@@ -0,0 +1,83 @@
+import { Schema } from "effect"
+import { HttpApiEndpoint, HttpApiGroup, OpenApi } from "effect/unstable/httpapi"
+import { ConflictError, ServiceUnavailableError } from "../errors.js"
+
+export const BROWSER_CONTROL_PROTOCOL = "opencode.browser.control.v1"
+export const BROWSER_TUNNEL_PROTOCOL = "opencode.browser.tunnel.v1"
+
+export function isBrowserConnectURL(input: string) {
+  try {
+    const path = decodeURI(new URL(input, "http://localhost").pathname)
+      .replace(/;[^/]*$/, "")
+      .replace(/\/+/g, "/")
+      .replace(/\/$/, "")
+      .toLowerCase()
+    return path === "/api/browser/control" || path === "/api/browser/tunnel"
+  } catch {
+    return false
+  }
+}
+
+const websocket = (
+  identifier: string,
+  summary: string,
+  description: string,
+  subprotocol: string,
+  incoming: string,
+  outgoing: string,
+) =>
+  OpenApi.annotations({
+    identifier,
+    summary,
+    description,
+    transform: (operation) => ({
+      ...operation,
+      "x-websocket": true,
+      "x-websocket-subprotocol": subprotocol,
+      "x-websocket-incoming": incoming,
+      "x-websocket-outgoing": outgoing,
+      responses: {
+        ...operation.responses,
+        403: { description: "WebSocket Origin is not allowed." },
+        426: { description: `WebSocket subprotocol ${subprotocol} is required.` },
+      },
+    }),
+  })
+
+export const BrowserGroup = HttpApiGroup.make("server.browser")
+  .add(
+    HttpApiEndpoint.get("browser.control.connect", "/api/browser/control", {
+      success: Schema.Boolean,
+      error: ConflictError,
+    }).annotateMerge(
+      websocket(
+        "v2.browser.control.connect",
+        "Connect desktop browser host",
+        "Establish an authenticated WebSocket carrying Session-scoped browser attachments and semantic browser commands.",
+        BROWSER_CONTROL_PROTOCOL,
+        "BrowserControl.FromDesktop",
+        "BrowserControl.FromServer",
+      ),
+    ),
+  )
+  .add(
+    HttpApiEndpoint.get("browser.tunnel.connect", "/api/browser/tunnel", {
+      success: Schema.Boolean,
+      error: ServiceUnavailableError,
+    }).annotateMerge(
+      websocket(
+        "v2.browser.tunnel.connect",
+        "Open browser network tunnel",
+        "Establish an authenticated WebSocket carrying one TCP stream dialed from the OpenCode server.",
+        BROWSER_TUNNEL_PROTOCOL,
+        "BrowserTunnel.FromDesktop and binary DATA frames",
+        "BrowserTunnel.FromServer and binary DATA frames",
+      ),
+    ),
+  )
+  .annotateMerge(
+    OpenApi.annotations({
+      title: "browser",
+      description: "Desktop browser host control and server-network tunnel routes.",
+    }),
+  )

packages/protocol/test/browser-control.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, test } from "bun:test"
+import { BrowserControlProtocol } from "../src/browser-control.js"
+import { Effect } from "effect"
+
+describe("BrowserControlProtocol", () => {
+  test("decodes text and Bun-compatible UTF-8 byte messages", async () => {
+    const message = '{"type":"browser.control.sync","revision":1,"attachments":[]}'
+    expect(await Effect.runPromise(BrowserControlProtocol.decodeFromDesktop(message))).toEqual({
+      type: "browser.control.sync",
+      revision: 1,
+      attachments: [],
+    })
+    expect(
+      await Effect.runPromise(BrowserControlProtocol.decodeFromDesktop(new TextEncoder().encode(message))),
+    ).toEqual({
+      type: "browser.control.sync",
+      revision: 1,
+      attachments: [],
+    })
+  })
+
+  test("round trips both control directions", async () => {
+    const desktop = { type: "browser.control.sync" as const, revision: 1, attachments: [] }
+    const server = { type: "browser.control.synced" as const, revision: 1 }
+    expect(
+      await Effect.runPromise(BrowserControlProtocol.decodeFromDesktop(BrowserControlProtocol.encodeFromDesktop(desktop))),
+    ).toEqual(desktop)
+    expect(
+      await Effect.runPromise(BrowserControlProtocol.decodeFromServer(BrowserControlProtocol.encodeFromServer(server))),
+    ).toEqual(server)
+  })
+
+  test("rejects excess properties and oversized messages", async () => {
+    expect(
+      await Effect.runPromise(
+        BrowserControlProtocol.decodeFromDesktop(
+          '{"type":"browser.control.sync","revision":1,"attachments":[],"extra":true}',
+        ).pipe(Effect.result),
+      ),
+    ).toMatchObject({ _tag: "Failure", failure: { _tag: "BrowserControlProtocol.MessageError" } })
+
+    expect(
+      await Effect.runPromise(
+        BrowserControlProtocol.decodeFromDesktop(new Uint8Array(BrowserControlProtocol.MaxMessageBytes + 1)).pipe(
+          Effect.result,
+        ),
+      ),
+    ).toMatchObject({
+      _tag: "Failure",
+      failure: { _tag: "BrowserControlProtocol.MessageError", kind: "too_large" },
+    })
+  })
+})

packages/protocol/test/browser-tunnel.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, test } from "bun:test"
+import { Browser } from "@opencode-ai/schema/browser"
+import { BrowserTunnel } from "@opencode-ai/schema/browser-tunnel"
+import { Session } from "@opencode-ai/schema/session"
+import { Effect } from "effect"
+import { BrowserTunnelProtocol } from "../src/browser-tunnel.js"
+
+describe("BrowserTunnelProtocol", () => {
+  test("round trips binary data without copying protocol semantics into it", async () => {
+    const payload = new Uint8Array([0, 1, 2, 255])
+    const decoded = await Effect.runPromise(BrowserTunnelProtocol.decodeFromServer(BrowserTunnelProtocol.data(payload)))
+    expect(decoded).toEqual({ type: "data", data: payload })
+    expect(Array.from(BrowserTunnelProtocol.data(new Uint8Array([1, 2])))).toEqual([0, 1, 2])
+  })
+
+  test("round trips typed control messages", async () => {
+    const message: BrowserTunnel.FromDesktop = {
+      type: "browser.tunnel.open",
+      sessionID: Session.ID.make("ses_browser_tunnel"),
+      leaseID: Browser.LeaseID.make("brl_browsertunnel"),
+      target: { host: BrowserTunnel.Host.make("localhost"), port: BrowserTunnel.Port.make(5173) },
+      receiveWindow: BrowserTunnel.WindowSize.make(BrowserTunnelProtocol.InitialWindowBytes),
+      receiveFrames: BrowserTunnel.FrameWindow.make(BrowserTunnelProtocol.InitialFrameWindow),
+    }
+    const decoded = await Effect.runPromise(
+      BrowserTunnelProtocol.decodeFromDesktop(BrowserTunnelProtocol.encodeFromDesktop(message)),
+    )
+    expect(decoded).toEqual({ type: "control", message })
+  })
+
+  test("rejects unframed, unknown, and malformed control payloads", async () => {
+    for (const input of [
+      "unframed",
+      new Uint8Array([9, 0]),
+      new Uint8Array([BrowserTunnelProtocol.FrameType.Control, 255]),
+    ]) {
+      expect(await Effect.runPromise(BrowserTunnelProtocol.decodeFromDesktop(input).pipe(Effect.result))).toMatchObject(
+        {
+          _tag: "Failure",
+          failure: { _tag: "BrowserTunnelProtocol.FrameError" },
+        },
+      )
+    }
+  })
+
+  test("pins control framing and public size limits", async () => {
+    expect(Array.from(BrowserTunnelProtocol.encodeFromDesktop({ type: "browser.tunnel.end" }))).toEqual([
+      BrowserTunnelProtocol.FrameType.Control,
+      ...new TextEncoder().encode('{"type":"browser.tunnel.end"}'),
+    ])
+    expect(() => BrowserTunnelProtocol.data(new Uint8Array())).toThrow()
+    expect(() => BrowserTunnelProtocol.data(new Uint8Array(BrowserTunnelProtocol.MaxDataBytes + 1))).toThrow()
+
+    const extra = new TextEncoder().encode('{"type":"browser.tunnel.end","extra":true}')
+    const frame = new Uint8Array(extra.byteLength + 1)
+    frame[0] = BrowserTunnelProtocol.FrameType.Control
+    frame.set(extra, 1)
+    expect(await Effect.runPromise(BrowserTunnelProtocol.decodeFromDesktop(frame).pipe(Effect.result))).toMatchObject({
+      _tag: "Failure",
+      failure: { _tag: "BrowserTunnelProtocol.FrameError" },
+    })
+  })
+})