Let plugins stream live events and binary data to the app (#8527)

* feat(plugins): stream events and bytes between plugins and the app

Plugins can declare a subscription with defineSubscription, handle it with
server.handle(contract, (input, { push, signal })), and listen from a surface
with useSubscription or client.subscribe. A top-level Uint8Array in an event,
an RPC output, or an RPC input crosses the wire as a binary frame (opcodes
0x20-0x2f) without JSON or base64; a nested one fails validation on the sender.

Each subscriber runs its own handler, owned by the session that subscribed,
so release, disconnect, plugin stop and reload need no plugin code. The
runtime buffers pushes until the subscribe response has gone out, so a client
never sees an event for a subscription it does not know yet.

Gated on server_info.features.pluginSubscriptions; binary outputs reach only
clients that advertise plugin_binary_payloads.

* fix(plugins): close subscription gaps found in review

- Losing daemon.manage now releases the session's plugin subscriptions;
  binary events bypass the outbound permission check, so streams would
  otherwise outlive the revocation.
- A subscribe that times out sends unsubscribe, since the plugin may
  still start the handler after the daemon gave up.
- The byte limit leaves room for the largest frame header and routing,
  and lives in assertPluginWireValue so events, outputs and inputs share it.
- A release right after the host accepted keeps `ready` resolved, so a
  handler that returns at once reports closed rather than an error.
- Session trace logging tolerates loggers without isLevelEnabled.

* fix(plugins): withhold binary plugin results after plugin access is revoked

A binary RPC output or event skipped the outbound permission check its
JSON form passes, so an RPC in flight when daemon.manage was revoked still
delivered its bytes. Each frame now checks the permission of the JSON
message it stands in for.

* test(plugins): cover subscriptions in a real browser instead of JSDOM

The app subscription tests mounted hooks in JSDOM, which docs/testing.md
rules out. The adapter and contract behavior is now a plain unit test,
and a Playwright spec drives the diff-watch and media-stream examples:
JSON events following file changes, streamed bytes, and an upload.

* test(plugins): add the plain subscription unit test and the browser spec

* fix(plugins): apply subscription schema transforms once

Both ends parsed each subscription value, and the sender sent its parse
output, so the receiver parsed a schema's output as fresh input. An event
schema like z.string().transform((s) => s.length) closed the stream as
invalid. The sender now validates and sends the value as given; the
receiver's parse produces what the handler or callback sees.

* fix(plugins): parse a subscription's input once in the plugin process

server.handle wrapped subscription handlers in a second input parse, so a
transforming input schema rejected its own parsed output before the
handler ran.

packages/protocol/src/binary-frames/demux.ts

@@ -4,6 +4,7 @@ import {
   FileTransferOpcode,
   type FileTransferFrame,
 } from "./file-transfer.js";
+import { decodePluginFrame, PluginFrameOpcode, type PluginFrame } from "./plugin.js";
 import {
   decodeTerminalStreamFrame,
   TerminalStreamOpcode,
@@ -13,7 +14,8 @@ import {
 export type BinaryFrame =
   | { kind: "host_route"; frame: HostRouteFrame }
   | { kind: "terminal"; frame: TerminalStreamFrame }
-  | { kind: "file_transfer"; frame: FileTransferFrame };
+  | { kind: "file_transfer"; frame: FileTransferFrame }
+  | { kind: "plugin"; frame: PluginFrame };
 
 export function decodeBinaryFrame(bytes: Uint8Array): BinaryFrame | null {
   switch (bytes[0]) {
@@ -38,6 +40,12 @@ export function decodeBinaryFrame(bytes: Uint8Array): BinaryFrame | null {
       const frame = decodeFileTransferFrame(bytes);
       return frame ? { kind: "file_transfer", frame } : null;
     }
+    case PluginFrameOpcode.Event:
+    case PluginFrameOpcode.Output:
+    case PluginFrameOpcode.Input: {
+      const frame = decodePluginFrame(bytes);
+      return frame ? { kind: "plugin", frame } : null;
+    }
     default:
       return null;
   }

packages/protocol/src/binary-frames/index.ts

@@ -2,3 +2,4 @@ export * from "./demux.js";
 export * from "./file-transfer.js";
 export * from "./terminal.js";
 export * from "./host-route.js";
+export * from "./plugin.js";

packages/protocol/src/binary-frames/plugin.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  assertPluginWireValue,
+  decodeBinaryFrame,
+  decodePluginFrame,
+  encodePluginEventFrame,
+  encodePluginInputFrame,
+  encodePluginOutputFrame,
+  FileTransferOpcode,
+  MAX_PLUGIN_PAYLOAD_BYTES,
+  MAX_ROUTED_PAYLOAD_BYTES,
+  PluginFrameOpcode,
+  TerminalStreamOpcode,
+} from "./index.js";
+
+describe("plugin binary frames", () => {
+  it("uses the reserved plugin opcode range", () => {
+    for (const opcode of Object.values(PluginFrameOpcode)) {
+      expect(opcode).toBeGreaterThanOrEqual(0x20);
+      expect(opcode).toBeLessThanOrEqual(0x2f);
+      expect(Object.values(TerminalStreamOpcode)).not.toContain(opcode);
+      expect(Object.values(FileTransferOpcode)).not.toContain(opcode);
+    }
+  });
+
+  it("frames a subscription event as opcode, id length, id, and the untouched payload", () => {
+    const payload = new Uint8Array([9, 8, 7]);
+    const frame = encodePluginEventFrame("sub-1", payload);
+    expect([...frame]).toEqual([0x20, 5, ...new TextEncoder().encode("sub-1"), 9, 8, 7]);
+    expect(decodeBinaryFrame(frame)).toEqual({
+      kind: "plugin",
+      frame: { opcode: PluginFrameOpcode.Event, subscriptionId: "sub-1", payload },
+    });
+  });
+
+  it("decodes payloads as views into the received buffer", () => {
+    const frame = encodePluginOutputFrame("req-1", new Uint8Array([1, 2, 3, 4]));
+    const decoded = decodePluginFrame(frame);
+    if (decoded?.opcode !== PluginFrameOpcode.Output) throw new Error("Expected an output frame");
+    expect(decoded.requestId).toBe("req-1");
+    expect(decoded.payload.buffer).toBe(frame.buffer);
+    expect([...decoded.payload]).toEqual([1, 2, 3, 4]);
+  });
+
+  it("frames an RPC input with the plugin and method in its header", () => {
+    const frame = encodePluginInputFrame({
+      requestId: "req-2",
+      pluginId: "uploads",
+      method: "upload.store",
+      payload: new Uint8Array([5, 6]),
+    });
+    expect(decodePluginFrame(frame)).toEqual({
+      opcode: PluginFrameOpcode.Input,
+      requestId: "req-2",
+      pluginId: "uploads",
+      method: "upload.store",
+      payload: new Uint8Array([5, 6]),
+    });
+  });
+
+  it("rejects truncated frames", () => {
+    expect(decodePluginFrame(new Uint8Array([0x20]))).toBeNull();
+    expect(decodePluginFrame(new Uint8Array([0x20, 9, 1]))).toBeNull();
+    expect(decodePluginFrame(new Uint8Array([0x22, 1, 65, 0, 40]))).toBeNull();
+  });
+});
+
+describe("the plugin byte rule", () => {
+  it("accepts JSON values and a top-level Uint8Array", () => {
+    expect(() => assertPluginWireValue({ a: [1, "b", null] }, "event")).not.toThrow();
+    expect(() => assertPluginWireValue(new Uint8Array(4), "event")).not.toThrow();
+  });
+
+  it("rejects bytes that would not fit in one frame with the largest header", () => {
+    const bytes = new Uint8Array(MAX_PLUGIN_PAYLOAD_BYTES + 1);
+    expect(() => assertPluginWireValue(bytes.subarray(1), "event")).not.toThrow();
+    expect(() => assertPluginWireValue(bytes, "event")).toThrow(
+      `event is ${MAX_PLUGIN_PAYLOAD_BYTES + 1} bytes; one value carries at most ${MAX_PLUGIN_PAYLOAD_BYTES} bytes`,
+    );
+    const frame = encodePluginInputFrame({
+      requestId: "r".repeat(255),
+      pluginId: "p",
+      method: "m".repeat(0xffff - 30),
+      payload: bytes.subarray(1),
+    });
+    expect(frame.byteLength).toBeLessThanOrEqual(MAX_ROUTED_PAYLOAD_BYTES);
+  });
+
+  it("rejects bytes nested in a value and names the rule and the path", () => {
+    expect(() => assertPluginWireValue({ frames: [{ data: new Uint8Array(1) }] }, "event")).toThrow(
+      "event.frames[0].data is a Uint8Array. Bytes cross the wire only as the whole value: send the Uint8Array itself, or encode it into the value.",
+    );
+  });
+});

packages/protocol/src/binary-frames/plugin.ts

@@ -0,0 +1,152 @@
+import { MAX_ROUTED_PAYLOAD_BYTES } from "./host-route.js";
+
+/**
+ * Plugin values that are a `Uint8Array` travel as binary frames. Opcodes 0x20-0x2f are
+ * reserved for plugin traffic. Every frame is `[opcode][id length u8][id]...` and the payload
+ * is the rest of the frame, decoded as a view so no hop copies it.
+ */
+export const PluginFrameOpcode = {
+  /** `[0x20][id length][subscriptionId][payload]`: a subscription event. */
+  Event: 0x20,
+  /** `[0x21][id length][requestId][payload]`: an RPC output; no JSON response follows. */
+  Output: 0x21,
+  /** `[0x22][id length][requestId][header length u16][header JSON][payload]`: an RPC input. */
+  Input: 0x22,
+} as const;
+
+export type PluginFrameOpcode = (typeof PluginFrameOpcode)[keyof typeof PluginFrameOpcode];
+
+/** The largest frame header: an input's opcode, ID and header JSON, each at its maximum length. */
+const MAX_PLUGIN_FRAME_HEADER_BYTES = 2 + 0xff + 2 + 0xffff;
+
+/** The largest `Uint8Array` a plugin value carries, so its frame fits in one routed message. */
+export const MAX_PLUGIN_PAYLOAD_BYTES = MAX_ROUTED_PAYLOAD_BYTES - MAX_PLUGIN_FRAME_HEADER_BYTES;
+
+export type PluginFrame =
+  | { opcode: typeof PluginFrameOpcode.Event; subscriptionId: string; payload: Uint8Array }
+  | { opcode: typeof PluginFrameOpcode.Output; requestId: string; payload: Uint8Array }
+  | {
+      opcode: typeof PluginFrameOpcode.Input;
+      requestId: string;
+      pluginId: string;
+      method: string;
+      payload: Uint8Array;
+    };
+
+export function isPluginFrameOpcode(value: number | undefined): value is PluginFrameOpcode {
+  return (
+    value === PluginFrameOpcode.Event ||
+    value === PluginFrameOpcode.Output ||
+    value === PluginFrameOpcode.Input
+  );
+}
+
+export function encodePluginEventFrame(subscriptionId: string, payload: Uint8Array): Uint8Array {
+  return encodeFrame(PluginFrameOpcode.Event, subscriptionId, new Uint8Array(0), payload);
+}
+
+export function encodePluginOutputFrame(requestId: string, payload: Uint8Array): Uint8Array {
+  return encodeFrame(PluginFrameOpcode.Output, requestId, new Uint8Array(0), payload);
+}
+
+export function encodePluginInputFrame(input: {
+  requestId: string;
+  pluginId: string;
+  method: string;
+  payload: Uint8Array;
+}): Uint8Array {
+  const header = new TextEncoder().encode(
+    JSON.stringify({ pluginId: input.pluginId, method: input.method }),
+  );
+  if (header.byteLength > 0xffff) throw new RangeError("Plugin input header is too long");
+  const prefix = new Uint8Array(2 + header.byteLength);
+  new DataView(prefix.buffer).setUint16(0, header.byteLength);
+  prefix.set(header, 2);
+  return encodeFrame(PluginFrameOpcode.Input, input.requestId, prefix, input.payload);
+}
+
+export function decodePluginFrame(bytes: Uint8Array): PluginFrame | null {
+  const opcode = bytes[0];
+  if (bytes.byteLength < 2 || !isPluginFrameOpcode(opcode)) return null;
+  const idLength = bytes[1];
+  if (idLength === 0 || idLength > bytes.byteLength - 2) return null;
+  const id = new TextDecoder().decode(bytes.subarray(2, 2 + idLength));
+  const body = bytes.subarray(2 + idLength);
+  if (opcode === PluginFrameOpcode.Event) return { opcode, subscriptionId: id, payload: body };
+  if (opcode === PluginFrameOpcode.Output) return { opcode, requestId: id, payload: body };
+  if (body.byteLength < 2) return null;
+  const headerLength = new DataView(body.buffer, body.byteOffset, body.byteLength).getUint16(0);
+  if (headerLength > body.byteLength - 2) return null;
+  const header = decodeInputHeader(body.subarray(2, 2 + headerLength));
+  if (!header) return null;
+  return { opcode, requestId: id, ...header, payload: body.subarray(2 + headerLength) };
+}
+
+function encodeFrame(
+  opcode: PluginFrameOpcode,
+  id: string,
+  prefix: Uint8Array,
+  payload: Uint8Array,
+): Uint8Array {
+  const idBytes = new TextEncoder().encode(id);
+  if (idBytes.byteLength === 0) throw new RangeError("Plugin frame ID is required");
+  if (idBytes.byteLength > 0xff) throw new RangeError("Plugin frame ID is too long");
+  const headerLength = 2 + idBytes.byteLength + prefix.byteLength;
+  const frame = new Uint8Array(headerLength + payload.byteLength);
+  frame[0] = opcode;
+  frame[1] = idBytes.byteLength;
+  frame.set(idBytes, 2);
+  frame.set(prefix, 2 + idBytes.byteLength);
+  frame.set(payload, headerLength);
+  return frame;
+}
+
+function decodeInputHeader(bytes: Uint8Array): { pluginId: string; method: string } | null {
+  try {
+    const header: unknown = JSON.parse(new TextDecoder().decode(bytes));
+    if (typeof header !== "object" || header === null) return null;
+    const pluginId = Reflect.get(header, "pluginId");
+    const method = Reflect.get(header, "method");
+    if (typeof pluginId !== "string" || typeof method !== "string" || !pluginId || !method)
+      return null;
+    return { pluginId, method };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The byte rule: a plugin value is either a `Uint8Array`, sent as a binary frame, or a JSON value
+ * with no `Uint8Array` inside it. Checks object structure only; never reads the bytes.
+ */
+export function assertPluginWireValue(value: unknown, label: string): void {
+  if (value instanceof Uint8Array) {
+    if (value.byteLength > MAX_PLUGIN_PAYLOAD_BYTES)
+      throw new RangeError(
+        `${label} is ${value.byteLength} bytes; one value carries at most ${MAX_PLUGIN_PAYLOAD_BYTES} bytes`,
+      );
+    return;
+  }
+  const nested = findNestedBytes(value, label);
+  if (nested)
+    throw new TypeError(
+      `${nested} is a Uint8Array. Bytes cross the wire only as the whole value: send the Uint8Array itself, or encode it into the value.`,
+    );
+}
+
+function findNestedBytes(value: unknown, path: string): string | null {
+  if (value instanceof Uint8Array) return path;
+  if (typeof value !== "object" || value === null) return null;
+  if (Array.isArray(value)) {
+    for (let index = 0; index < value.length; index += 1) {
+      const found = findNestedBytes(value[index], `${path}[${index}]`);
+      if (found) return found;
+    }
+    return null;
+  }
+  for (const [key, entry] of Object.entries(value)) {
+    const found = findNestedBytes(entry, `${path}.${key}`);
+    if (found) return found;
+  }
+  return null;
+}