feat: stream files as binary frames over WebSocket (#659)

Replace base64-in-JSON file transfers with binary WebSocket frames to unblock the JS thread when assistant markdown messages contain images. Receive cost (JSON.parse over multi-MB base64) and persist cost (base64 re-encode to disk) both removed. - Split daemon-client `exploreFileSystem` into `listDirectory` + `readFile`; `readFile` returns `{ bytes, mime, size, modifiedAt }`. Encoding stays private to the seam. - New `packages/server/src/shared/binary-frames/` module hosts terminal frames (moved from `terminal-stream-protocol.ts`) and new file-transfer opcodes (`FileBegin` / `FileChunk` / `FileEnd`) with request-id correlation. - Add optional `acceptBinary` to `FileExplorerRequestSchema`. New daemons emit binary frames when set; legacy JSON path remains for old clients. Compat fallback lives only inside `readFile`. - New `persistAttachmentFromBytes` writes bytes directly: native via `expo-file-system` `File.write(Uint8Array)`, web via Blob -> IndexedDB, desktop via new `write_attachment_bytes` IPC. `persistAttachmentFromBase64` removed.
2026-05-02 14:02:27 +08:00
parent b6c43088fb
commit bb889dae99
44 changed files with 1630 additions and 436 deletions
@@ -1,5 +1,6 @@
 import { afterEach, expect, expectTypeOf, test, vi } from "vitest";
 import { DaemonClient, type DaemonTransport } from "./daemon-client";
+import { encodeFileTransferFrame, FileTransferOpcode } from "../shared/binary-frames/index.js";
 import {
  asUint8Array,
  decodeTerminalResizePayload,
@@ -13,6 +14,9 @@ expectTypeOf<"getGitDiff" extends keyof DaemonClient ? true : false>().toEqualTy
 expectTypeOf<
  "getHighlightedDiff" extends keyof DaemonClient ? true : false
 >().toEqualTypeOf<false>();
+expectTypeOf<
+  "exploreFileSystem" extends keyof DaemonClient ? true : false
+>().toEqualTypeOf<false>();

 function createMockLogger() {
  return {
@@ -235,6 +239,209 @@ test("does not reconnect after close when ensureConnected is called", async () =
  expect(client.getConnectionState().status).toBe("disposed");
 });

+test("listDirectory sends a list file explorer request and returns directory entries", async () => {
+  const logger = createMockLogger();
+  const mock = createMockTransport();
+
+  const client = new DaemonClient({
+    url: "ws://test",
+    clientId: "clsk_unit_test",
+    logger,
+    reconnect: { enabled: false },
+    transportFactory: () => mock.transport,
+  });
+  clients.push(client);
+
+  const connectPromise = client.connect();
+  mock.triggerOpen();
+  await connectPromise;
+
+  const responsePromise = client.listDirectory("/tmp/project", "src", "req-list");
+
+  expect(JSON.parse(String(mock.sent[0]))).toEqual({
+    type: "session",
+    message: {
+      type: "file_explorer_request",
+      cwd: "/tmp/project",
+      path: "src",
+      mode: "list",
+      requestId: "req-list",
+    },
+  });
+
+  mock.triggerMessage(
+    wrapSessionMessage({
+      type: "file_explorer_response",
+      payload: {
+        cwd: "/tmp/project",
+        path: "src",
+        mode: "list",
+        directory: {
+          path: "src",
+          entries: [
+            {
+              name: "index.ts",
+              path: "src/index.ts",
+              kind: "file",
+              size: 12,
+              modifiedAt: "2026-05-02T00:00:00.000Z",
+            },
+          ],
+        },
+        file: null,
+        error: null,
+        requestId: "req-list",
+      },
+    }),
+  );
+
+  await expect(responsePromise).resolves.toEqual({
+    path: "src",
+    entries: [
+      {
+        name: "index.ts",
+        path: "src/index.ts",
+        kind: "file",
+        size: 12,
+        modifiedAt: "2026-05-02T00:00:00.000Z",
+      },
+    ],
+  });
+});
+
+test("readFile hides legacy base64 behind bytes", async () => {
+  const logger = createMockLogger();
+  const mock = createMockTransport();
+
+  const client = new DaemonClient({
+    url: "ws://test",
+    clientId: "clsk_unit_test",
+    logger,
+    reconnect: { enabled: false },
+    transportFactory: () => mock.transport,
+  });
+  clients.push(client);
+
+  const connectPromise = client.connect();
+  mock.triggerOpen();
+  await connectPromise;
+
+  const responsePromise = client.readFile("/tmp/project", "logo.png", "req-file");
+
+  expect(JSON.parse(String(mock.sent[0]))).toEqual({
+    type: "session",
+    message: {
+      type: "file_explorer_request",
+      cwd: "/tmp/project",
+      path: "logo.png",
+      mode: "file",
+      acceptBinary: true,
+      requestId: "req-file",
+    },
+  });
+
+  mock.triggerMessage(
+    wrapSessionMessage({
+      type: "file_explorer_response",
+      payload: {
+        cwd: "/tmp/project",
+        path: "logo.png",
+        mode: "file",
+        directory: null,
+        file: {
+          path: "logo.png",
+          kind: "image",
+          encoding: "base64",
+          content: "aGVsbG8=",
+          mimeType: "image/png",
+          size: 5,
+          modifiedAt: "2026-05-02T00:00:00.000Z",
+        },
+        error: null,
+        requestId: "req-file",
+      },
+    }),
+  );
+
+  const result = await responsePromise;
+  expect(result).toMatchObject({
+    mime: "image/png",
+    size: 5,
+    path: "logo.png",
+    kind: "image",
+    modifiedAt: "2026-05-02T00:00:00.000Z",
+  });
+  expect(new TextDecoder().decode(result.bytes)).toBe("hello");
+});
+
+test("readFile resolves from binary file frames when the daemon supports them", async () => {
+  const logger = createMockLogger();
+  const mock = createMockTransport();
+
+  const client = new DaemonClient({
+    url: "ws://test",
+    clientId: "clsk_unit_test",
+    logger,
+    reconnect: { enabled: false },
+    transportFactory: () => mock.transport,
+  });
+  clients.push(client);
+
+  const connectPromise = client.connect();
+  mock.triggerOpen();
+  await connectPromise;
+
+  const responsePromise = client.readFile("/tmp/project", "logo.png", "req-binary");
+
+  expect(JSON.parse(String(mock.sent[0]))).toEqual({
+    type: "session",
+    message: {
+      type: "file_explorer_request",
+      cwd: "/tmp/project",
+      path: "logo.png",
+      mode: "file",
+      acceptBinary: true,
+      requestId: "req-binary",
+    },
+  });
+
+  mock.triggerMessage(
+    encodeFileTransferFrame({
+      opcode: FileTransferOpcode.FileBegin,
+      requestId: "req-binary",
+      metadata: {
+        mime: "image/png",
+        size: 5,
+        encoding: "binary",
+        modifiedAt: "2026-05-02T00:00:00.000Z",
+      },
+    }),
+  );
+  mock.triggerMessage(
+    encodeFileTransferFrame({
+      opcode: FileTransferOpcode.FileChunk,
+      requestId: "req-binary",
+      payload: new TextEncoder().encode("hello"),
+    }),
+  );
+  mock.triggerMessage(
+    encodeFileTransferFrame({
+      opcode: FileTransferOpcode.FileEnd,
+      requestId: "req-binary",
+    }),
+  );
+
+  const result = await responsePromise;
+  expect(result).toMatchObject({
+    mime: "image/png",
+    size: 5,
+    path: "logo.png",
+    kind: "image",
+    modifiedAt: "2026-05-02T00:00:00.000Z",
+  });
+  expect(new TextDecoder().decode(result.bytes)).toBe("hello");
+});
+
 test("normalizes workspace_setup_progress into a workspace-scoped daemon event", async () => {
  const logger = createMockLogger();
  const mock = createMockTransport();