jb/paseo
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
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.
This commit is contained in:
Mohamed Boudra
2026-05-02 14:02:27 +08:00
committed by GitHub
parent b6c43088fb
commit bb889dae99
44 changed files with 1630 additions and 436 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packages/server/src/client/daemon-client.test.ts
+207
View File
@@ -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();
packages/server/src/client/daemon-client.ts
+182 -3
View File
@@ -82,13 +82,16 @@ import type { MutableDaemonConfig, MutableDaemonConfigPatch } from "../shared/me
import { isRelayClientWebSocketUrl } from "../shared/daemon-endpoints.js";
import {
asUint8Array,
decodeFileTransferFrame,
decodeTerminalSnapshotPayload,
decodeTerminalStreamFrame,
FileTransferOpcode,
encodeTerminalResizePayload,
encodeTerminalStreamFrame,
TerminalStreamOpcode,
type FileTransferFrame,
type TerminalStreamFrame,
} from "../shared/terminal-stream-protocol.js";
} from "../shared/binary-frames/index.js";
import {
createRelayE2eeTransportFactory,
createWebSocketTransportFactory,
@@ -283,6 +286,16 @@ type CreatePaseoWorktreePayload = Extract<
{ type: "create_paseo_worktree_response" }
>["payload"];
type FileExplorerPayload = FileExplorerResponse["payload"];
export type FileExplorerDirectoryPayload = NonNullable<FileExplorerPayload["directory"]>;
type LegacyFileExplorerFilePayload = NonNullable<FileExplorerPayload["file"]>;
export interface FileReadResult {
bytes: Uint8Array;
mime: string;
size: number;
path: string;
kind: LegacyFileExplorerFilePayload["kind"];
modifiedAt: string;
}
type FileDownloadTokenPayload = FileDownloadTokenResponse["payload"];
type ListProviderFeaturesPayload = ListProviderFeaturesResponseMessage["payload"];
type ListProviderModelsPayload = ListProviderModelsResponseMessage["payload"];
@@ -569,6 +582,22 @@ interface WaitHandle<T> {
cancel: (error: Error) => void;
}
interface PendingBinaryFileRead {
cwd: string;
path: string;
}
interface BinaryFileTransferState extends PendingBinaryFileRead {
mime: string;
size: number;
encoding: Extract<
FileTransferFrame,
{ opcode: typeof FileTransferOpcode.FileBegin }
>["metadata"]["encoding"];
modifiedAt: string;
chunks: Uint8Array[];
}
type RpcWaitResult<T> = { kind: "ok"; value: T } | { kind: "error"; error: DaemonRpcError };
type GetDaemonConfigResponse = Extract<
SessionOutboundMessage,
@@ -627,6 +656,55 @@ function normalizeClientId(value: unknown): string | null {
return trimmed.length > 0 ? trimmed : null;
}
function decodeBase64ToBytes(base64: string): Uint8Array {
const binary = globalThis.atob(base64);
const bytes = new Uint8Array(binary.length);
for (let index = 0; index < binary.length; index += 1) {
bytes[index] = binary.charCodeAt(index);
}
return bytes;
}
function legacyExplorerFileToBytes(file: LegacyFileExplorerFilePayload): FileReadResult {
let bytes: Uint8Array;
if (file.encoding === "base64" && file.content) {
bytes = decodeBase64ToBytes(file.content);
} else if (file.encoding === "utf-8" && file.content) {
bytes = new TextEncoder().encode(file.content);
} else {
bytes = new Uint8Array();
}
return {
bytes,
mime: file.mimeType ?? "application/octet-stream",
size: file.size,
path: file.path,
kind: file.kind,
modifiedAt: file.modifiedAt,
};
}
function binaryFileKind(mime: string, encoding: string): FileReadResult["kind"] {
if (mime.startsWith("image/")) {
return "image";
}
if (encoding === "utf-8" || mime.startsWith("text/") || mime === "application/json") {
return "text";
}
return "binary";
}
function concatByteChunks(chunks: Uint8Array[], size: number): Uint8Array {
const bytes = new Uint8Array(size);
let offset = 0;
for (const chunk of chunks) {
bytes.set(chunk, offset);
offset += chunk.byteLength;
}
return bytes;
}
function hashForLog(value: string): string {
let hash = 0;
for (let index = 0; index < value.length; index += 1) {
@@ -697,6 +775,9 @@ export class DaemonClient {
private terminalDirectorySubscriptions = new Set<string>();
private terminalSlots = new Map<string, number>();
private slotTerminals = new Map<number, string>();
private pendingBinaryFileReads = new Map<string, PendingBinaryFileRead>();
private activeBinaryFileTransfers = new Map<string, BinaryFileTransferState>();
private completedBinaryFileReads = new Map<string, FileReadResult>();
private readonly terminalStreamListeners = new Set<(event: TerminalStreamEvent) => void>();
private logger: Logger;
private pendingSendQueue: PendingSend[] = [];
@@ -2865,11 +2946,12 @@ export class DaemonClient {
// File Explorer
// ============================================================================
async exploreFileSystem(
private async requestFileExplorer(
cwd: string,
path: string,
mode: "list" | "file" = "list",
mode: "list" | "file",
requestId?: string,
acceptBinary = false,
): Promise<FileExplorerPayload> {
return this.sendCorrelatedSessionRequest({
requestId,
@@ -2878,12 +2960,51 @@ export class DaemonClient {
cwd,
path,
mode,
...(acceptBinary ? { acceptBinary: true } : {}),
},
responseType: "file_explorer_response",
timeout: 10000,
});
}
async listDirectory(
cwd: string,
path: string,
requestId?: string,
): Promise<FileExplorerDirectoryPayload> {
const payload = await this.requestFileExplorer(cwd, path, "list", requestId);
if (payload.error) {
throw new Error(payload.error);
}
if (!payload.directory) {
throw new Error("Directory listing unavailable.");
}
return payload.directory;
}
async readFile(cwd: string, path: string, requestId?: string): Promise<FileReadResult> {
const resolvedRequestId = this.createRequestId(requestId);
this.pendingBinaryFileReads.set(resolvedRequestId, { cwd, path });
try {
const payload = await this.requestFileExplorer(cwd, path, "file", resolvedRequestId, true);
if (payload.error) {
throw new Error(payload.error);
}
const binaryResult = this.completedBinaryFileReads.get(resolvedRequestId);
if (binaryResult) {
this.completedBinaryFileReads.delete(resolvedRequestId);
return binaryResult;
}
if (!payload.file) {
throw new Error("File unavailable.");
}
return legacyExplorerFileToBytes(payload.file);
} finally {
this.pendingBinaryFileReads.delete(resolvedRequestId);
this.activeBinaryFileTransfers.delete(resolvedRequestId);
}
}
async requestDownloadToken(
cwd: string,
path: string,
@@ -3933,6 +4054,13 @@ export class DaemonClient {
}
private tryHandleBinaryFrame(rawBytes: Uint8Array): boolean {
const fileFrame = decodeFileTransferFrame(rawBytes);
if (fileFrame) {
this.handleFileTransferFrame(fileFrame);
this.runtimeMetrics?.recordBinaryFrame("other", rawBytes.byteLength, 0);
return true;
}
const frame = decodeTerminalStreamFrame(rawBytes);
if (!frame) {
return false;
@@ -3953,6 +4081,57 @@ export class DaemonClient {
return true;
}
private handleFileTransferFrame(frame: FileTransferFrame): void {
if (frame.opcode === FileTransferOpcode.FileBegin) {
const pending = this.pendingBinaryFileReads.get(frame.requestId);
if (!pending) {
return;
}
this.activeBinaryFileTransfers.set(frame.requestId, {
...pending,
mime: frame.metadata.mime,
size: frame.metadata.size,
encoding: frame.metadata.encoding,
modifiedAt: frame.metadata.modifiedAt,
chunks: [],
});
return;
}
const transfer = this.activeBinaryFileTransfers.get(frame.requestId);
if (!transfer) {
return;
}
if (frame.opcode === FileTransferOpcode.FileChunk) {
transfer.chunks.push(frame.payload);
return;
}
const bytes = concatByteChunks(transfer.chunks, transfer.size);
this.activeBinaryFileTransfers.delete(frame.requestId);
this.completedBinaryFileReads.set(frame.requestId, {
bytes,
mime: transfer.mime,
size: transfer.size,
path: transfer.path,
kind: binaryFileKind(transfer.mime, transfer.encoding),
modifiedAt: transfer.modifiedAt,
});
this.handleSessionMessage({
type: "file_explorer_response",
payload: {
cwd: transfer.cwd,
path: transfer.path,
mode: "file",
directory: null,
file: null,
error: null,
requestId: frame.requestId,
},
});
}
private handleBinaryFrame(frame: TerminalStreamFrame): void {
const terminalId = this.slotTerminals.get(frame.slot);
if (!terminalId) {
packages/server/src/server/daemon-client.e2e.test.ts
+4 -8
View File
@@ -1291,11 +1291,9 @@ test("supports git and file operations", async () => {
return unsubscribeList;
});
const listResult = await ctx.client.exploreFileSystem(cwd, ".", "list", listRequestId);
const listResult = await ctx.client.listDirectory(cwd, ".", listRequestId);
const listMessage = await listMessagePromise;
expect(listResult.error).toBeNull();
expect(listResult.directory).toBeTruthy();
expect(listResult.requestId).toBe(listRequestId);
expect(listResult.entries.some((entry) => entry.name === "download.txt")).toBe(true);
expect(listMessage.payload.mode).toBe("list");
expect(listMessage.payload.requestId).toBe(listRequestId);
@@ -1319,11 +1317,9 @@ test("supports git and file operations", async () => {
return unsubscribeFile;
});
const fileResult = await ctx.client.exploreFileSystem(cwd, "download.txt", "file", fileRequestId);
const fileResult = await ctx.client.readFile(cwd, "download.txt", fileRequestId);
const fileMessage = await fileMessagePromise;
expect(fileResult.error).toBeNull();
expect(fileResult.file?.content).toBe(downloadContents);
expect(fileResult.requestId).toBe(fileRequestId);
expect(new TextDecoder().decode(fileResult.bytes)).toBe(downloadContents);
expect(fileMessage.payload.mode).toBe("file");
expect(fileMessage.payload.requestId).toBe(fileRequestId);
packages/server/src/server/daemon-e2e/filesystem.e2e.test.ts
+10 -19
View File
@@ -22,7 +22,7 @@ afterEach(async () => {
await ctx.cleanup();
}, 60000);
describe("exploreFileSystem", () => {
describe("file explorer", () => {
test("lists directory contents", async () => {
const cwd = tmpCwd();
@@ -45,16 +45,13 @@ describe("exploreFileSystem", () => {
expect(agent.status).toBe("idle");
// List directory contents
const result = await ctx.client.exploreFileSystem(cwd, ".", "list");
const directory = await ctx.client.listDirectory(cwd, ".");
// Verify listing returned without error
expect(result.error).toBeNull();
expect(result.mode).toBe("list");
expect(result.directory).toBeTruthy();
expect(result.directory!.entries).toBeTruthy();
expect(directory.entries).toBeTruthy();
// Find expected entries
const entries = result.directory!.entries;
const entries = directory.entries;
const testTxt = entries.find((e) => e.name === "test.txt");
const dataJson = entries.find((e) => e.name === "data.json");
const subdir = entries.find((e) => e.name === "subdir");
@@ -92,17 +89,14 @@ describe("exploreFileSystem", () => {
expect(agent.id).toBeTruthy();
// Read file contents
const result = await ctx.client.exploreFileSystem(cwd, "readme.txt", "file");
const result = await ctx.client.readFile(cwd, "readme.txt");
// Verify file read
expect(result.error).toBeNull();
expect(result.mode).toBe("file");
expect(result.file).toBeTruthy();
// Server may return basename or full path
expect(result.file!.path).toContain("readme.txt");
expect(result.file!.kind).toBe("text");
expect(result.file!.content).toBe(testContent);
expect(result.file!.size).toBe(testContent.length);
expect(result.path).toContain("readme.txt");
expect(result.kind).toBe("text");
expect(new TextDecoder().decode(result.bytes)).toBe(testContent);
expect(result.size).toBe(testContent.length);
// Cleanup
await ctx.client.deleteAgent(agent.id);
@@ -124,10 +118,7 @@ describe("exploreFileSystem", () => {
expect(agent.id).toBeTruthy();
// Try to list non-existent path
const result = await ctx.client.exploreFileSystem(cwd, "does-not-exist", "list");
// Should return error
expect(result.error).toBeTruthy();
await expect(ctx.client.listDirectory(cwd, "does-not-exist")).rejects.toThrow();
// Cleanup
await ctx.client.deleteAgent(agent.id);
packages/server/src/server/file-explorer/service.ts
+55 -4
View File
@@ -39,6 +39,16 @@ export interface FileExplorerFile {
modifiedAt: string;
}
export interface FileExplorerFileBytes {
path: string;
kind: ExplorerFileKind;
encoding: "utf-8" | "binary";
bytes: Uint8Array;
mimeType: string;
size: number;
modifiedAt: string;
}
const TEXT_MIME_TYPES: Record<string, string> = {
".json": "application/json",
};
@@ -120,6 +130,46 @@ export async function readExplorerFile({
root,
relativePath,
}: ReadFileParams): Promise<FileExplorerFile> {
const file = await readExplorerFileBytes({ root, relativePath });
if (file.kind === "image") {
return {
path: file.path,
kind: file.kind,
encoding: "base64",
content: Buffer.from(file.bytes).toString("base64"),
mimeType: file.mimeType,
size: file.size,
modifiedAt: file.modifiedAt,
};
}
if (file.kind === "binary") {
return {
path: file.path,
kind: file.kind,
encoding: "none",
mimeType: file.mimeType,
size: file.size,
modifiedAt: file.modifiedAt,
};
}
return {
path: file.path,
kind: file.kind,
encoding: "utf-8",
content: Buffer.from(file.bytes).toString("utf-8"),
mimeType: file.mimeType,
size: file.size,
modifiedAt: file.modifiedAt,
};
}
export async function readExplorerFileBytes({
root,
relativePath,
}: ReadFileParams): Promise<FileExplorerFileBytes> {
const filePath = await resolveScopedPath({ root, relativePath });
const stats = await fs.stat(filePath);
@@ -139,8 +189,8 @@ export async function readExplorerFile({
return {
...basePayload,
kind: "image",
encoding: "base64",
content: buffer.toString("base64"),
encoding: "binary",
bytes: buffer,
mimeType: IMAGE_MIME_TYPES[ext],
};
}
@@ -150,7 +200,8 @@ export async function readExplorerFile({
return {
...basePayload,
kind: "binary",
encoding: "none",
encoding: "binary",
bytes: buffer,
mimeType: "application/octet-stream",
};
}
@@ -159,7 +210,7 @@ export async function readExplorerFile({
...basePayload,
kind: "text",
encoding: "utf-8",
content: buffer.toString("utf-8"),
bytes: buffer,
mimeType: textMimeTypeForExtension(ext),
};
}
packages/server/src/server/session.test.ts
+127 -14
View File
@@ -7,6 +7,7 @@ import { afterEach, describe, expect, test, vi } from "vitest";
import { CheckoutPrStatusSchema } from "../shared/messages.js";
import type { WorkspaceDescriptorPayload } from "../shared/messages.js";
import { decodeFileTransferFrame, FileTransferOpcode } from "../shared/binary-frames/index.js";
import { normalizeCheckoutPrStatusPayload, Session } from "./session.js";
import type {
AgentClient,
@@ -47,6 +48,17 @@ function asSessionInternals(session: Session): SessionHandlerInternals {
return session as unknown as SessionHandlerInternals;
}
function createBinaryMessageHandler(
binaryMessages: Uint8Array[] | undefined,
): ((frame: Uint8Array) => void) | undefined {
if (!binaryMessages) {
return undefined;
}
return (frame) => {
binaryMessages.push(frame);
};
}
const checkoutGitMocks = vi.hoisted(() => ({
checkoutResolvedBranch: vi.fn(),
commitChanges: vi.fn(),
@@ -195,7 +207,7 @@ vi.mock("./worktree-bootstrap.js", async (importOriginal) => {
};
});
function createSessionForTest(options?: {
interface SessionForTestOptions {
github?: {
invalidate: ReturnType<typeof vi.fn>;
isAuthenticated?: ReturnType<typeof vi.fn>;
@@ -223,17 +235,20 @@ function createSessionForTest(options?: {
getDaemonTcpHost?: () => string | null;
providerSnapshotManager?: ProviderSnapshotManager;
messages?: unknown[];
}): Session {
binaryMessages?: Uint8Array[];
}
function createSessionForTest(options: SessionForTestOptions = {}): Session {
const logger = pino({ level: "silent" });
const github = options?.github ?? {
const github = options.github ?? {
invalidate: vi.fn(),
searchIssuesAndPrs: vi.fn(),
createPullRequest: vi.fn(),
};
const checkoutDiffManager = options?.checkoutDiffManager ?? {
const checkoutDiffManager = options.checkoutDiffManager ?? {
scheduleRefreshForCwd: vi.fn(),
};
const workspaceGitService = options?.workspaceGitService ?? {
const workspaceGitService = options.workspaceGitService ?? {
getCheckoutDiff: vi.fn(),
getSnapshot: vi.fn(),
suggestBranchesForCwd: vi.fn(),
@@ -244,11 +259,12 @@ function createSessionForTest(options?: {
resolveRepoRemoteUrl: vi.fn(),
getWorkspaceGitMetadata: vi.fn(),
};
const messages = options?.messages ?? [];
const messages = options.messages ?? [];
return new Session({
clientId: "test-client",
onMessage: (message) => messages.push(message),
onBinaryMessage: createBinaryMessageHandler(options.binaryMessages),
logger,
downloadTokenStore: {} as unknown as SessionOptions["downloadTokenStore"],
pushTokenStore: {} as unknown as SessionOptions["pushTokenStore"],
@@ -260,7 +276,7 @@ function createSessionForTest(options?: {
agentStorage: {
list: vi.fn().mockResolvedValue([]),
} as unknown as SessionOptions["agentStorage"],
projectRegistry: (options?.projectRegistry ?? {
projectRegistry: (options.projectRegistry ?? {
list: vi.fn().mockResolvedValue([]),
get: vi.fn(),
upsert: vi.fn(),
@@ -269,7 +285,7 @@ function createSessionForTest(options?: {
initialize: vi.fn(),
existsOnDisk: vi.fn(),
}) as unknown as SessionOptions["projectRegistry"],
workspaceRegistry: (options?.workspaceRegistry ?? {
workspaceRegistry: (options.workspaceRegistry ?? {
get: vi.fn(),
list: vi.fn().mockResolvedValue([]),
}) as unknown as SessionOptions["workspaceRegistry"],
@@ -288,15 +304,112 @@ function createSessionForTest(options?: {
} as unknown as SessionOptions["daemonConfigStore"],
stt: null,
tts: null,
terminalManager: (options?.terminalManager ?? null) as SessionOptions["terminalManager"],
providerSnapshotManager: options?.providerSnapshotManager,
scriptRouteStore: options?.scriptRouteStore as SessionOptions["scriptRouteStore"],
scriptRuntimeStore: options?.scriptRuntimeStore as SessionOptions["scriptRuntimeStore"],
getDaemonTcpPort: options?.getDaemonTcpPort,
getDaemonTcpHost: options?.getDaemonTcpHost,
terminalManager: (options.terminalManager ?? null) as SessionOptions["terminalManager"],
providerSnapshotManager: options.providerSnapshotManager,
scriptRouteStore: options.scriptRouteStore as SessionOptions["scriptRouteStore"],
scriptRuntimeStore: options.scriptRuntimeStore as SessionOptions["scriptRuntimeStore"],
getDaemonTcpPort: options.getDaemonTcpPort,
getDaemonTcpHost: options.getDaemonTcpHost,
});
}
describe("file explorer binary responses", () => {
const tempDirs: string[] = [];
afterEach(() => {
for (const dir of tempDirs.splice(0)) {
rmSync(dir, { recursive: true, force: true });
}
});
function makeRoot(): string {
const root = realpathSync(mkdtempSync(join(tmpdir(), "file-explorer-session-test-")));
tempDirs.push(root);
return root;
}
test("old clients get legacy JSON file content from a new daemon", async () => {
const cwd = makeRoot();
writeFileSync(join(cwd, "logo.png"), "hello");
const messages: unknown[] = [];
const binaryMessages: Uint8Array[] = [];
const session = createSessionForTest({ messages, binaryMessages });
await session.handleMessage({
type: "file_explorer_request",
cwd,
path: "logo.png",
mode: "file",
requestId: "req-old-client",
});
expect(binaryMessages).toEqual([]);
expect(messages).toEqual([
{
type: "file_explorer_response",
payload: expect.objectContaining({
cwd,
path: "logo.png",
mode: "file",
directory: null,
error: null,
requestId: "req-old-client",
file: expect.objectContaining({
kind: "image",
encoding: "base64",
content: "aGVsbG8=",
mimeType: "image/png",
size: 5,
}),
}),
},
]);
});
test("new clients get binary file frames without legacy JSON content", async () => {
const cwd = makeRoot();
writeFileSync(join(cwd, "logo.png"), "hello");
const messages: unknown[] = [];
const binaryMessages: Uint8Array[] = [];
const session = createSessionForTest({ messages, binaryMessages });
await session.handleMessage({
type: "file_explorer_request",
cwd,
path: "logo.png",
mode: "file",
requestId: "req-new-client",
acceptBinary: true,
});
expect(messages).toEqual([]);
expect(binaryMessages).toHaveLength(3);
const frames = binaryMessages.map((frame) => decodeFileTransferFrame(frame));
expect(frames[0]).toEqual({
opcode: FileTransferOpcode.FileBegin,
requestId: "req-new-client",
metadata: {
mime: "image/png",
size: 5,
encoding: "binary",
modifiedAt: expect.any(String),
},
payload: new Uint8Array(),
});
expect(frames[1]).toEqual({
opcode: FileTransferOpcode.FileChunk,
requestId: "req-new-client",
payload: new TextEncoder().encode("hello"),
});
expect(frames[2]).toEqual({
opcode: FileTransferOpcode.FileEnd,
requestId: "req-new-client",
payload: new Uint8Array(),
});
});
});
function createProjectRecord(rootPath: string, archivedAt: string | null = null) {
return {
projectId: `project:${rootPath}`,
packages/server/src/server/session.ts
+55 -17
View File
@@ -35,7 +35,11 @@ import {
} from "./messages.js";
import type { TerminalManager } from "../terminal/terminal-manager.js";
import { TerminalSessionController } from "../terminal/terminal-session-controller.js";
import type { TerminalStreamFrame } from "../shared/terminal-stream-protocol.js";
import {
encodeFileTransferFrame,
FileTransferOpcode,
type TerminalStreamFrame,
} from "../shared/binary-frames/index.js";
import { CursorError } from "./pagination/cursor.js";
import { SortablePager, type SortSpec } from "./pagination/sortable-pager.js";
import { TTSManager } from "./agent/tts-manager.js";
@@ -149,6 +153,7 @@ import { isVoicePermissionAllowed } from "./voice-permission-policy.js";
import {
listDirectoryEntries,
readExplorerFile,
readExplorerFileBytes,
getDownloadableFileInfo,
} from "./file-explorer/service.js";
import { DownloadTokenStore } from "./file-download/token-store.js";
@@ -5475,23 +5480,56 @@ export class Session {
},
});
} else {
const file = await readExplorerFile({
root: cwd,
relativePath: requestedPath,
});
if (request.acceptBinary && this.onBinaryMessage) {
const file = await readExplorerFileBytes({
root: cwd,
relativePath: requestedPath,
});
this.emit({
type: "file_explorer_response",
payload: {
cwd,
path: file.path,
mode,
directory: null,
file,
error: null,
requestId,
},
});
this.emitBinary(
encodeFileTransferFrame({
opcode: FileTransferOpcode.FileBegin,
requestId,
metadata: {
mime: file.mimeType,
size: file.size,
encoding: file.encoding,
modifiedAt: file.modifiedAt,
},
}),
);
this.emitBinary(
encodeFileTransferFrame({
opcode: FileTransferOpcode.FileChunk,
requestId,
payload: file.bytes,
}),
);
this.emitBinary(
encodeFileTransferFrame({
opcode: FileTransferOpcode.FileEnd,
requestId,
}),
);
} else {
const file = await readExplorerFile({
root: cwd,
relativePath: requestedPath,
});
this.emit({
type: "file_explorer_response",
payload: {
cwd,
path: file.path,
mode,
directory: null,
file,
error: null,
requestId,
},
});
}
}
} catch (error) {
this.sessionLogger.error(
packages/server/src/server/websocket-server.ts
+1 -1
View File
@@ -26,7 +26,7 @@ import {
type WSOutboundMessage,
wrapSessionMessage,
} from "./messages.js";
import { asUint8Array, decodeTerminalStreamFrame } from "../shared/terminal-stream-protocol.js";
import { asUint8Array, decodeTerminalStreamFrame } from "../shared/binary-frames/index.js";
import type { HostnamesConfig } from "./hostnames.js";
import { isHostnameAllowed } from "./hostnames.js";
import { Session, type SessionLifecycleIntent, type SessionRuntimeMetrics } from "./session.js";
packages/server/src/shared/binary-frames/file-transfer.test.ts
+154
View File
@@ -0,0 +1,154 @@
import { describe, expect, it } from "vitest";
import {
FileTransferOpcode,
TerminalStreamOpcode,
decodeFileTransferFrame,
decodeTerminalStreamFrame,
encodeFileTransferFrame,
} from "./index.js";
describe("file transfer binary frames", () => {
const encoder = new TextEncoder();
it("uses non-terminal opcodes", () => {
expect(Object.values(TerminalStreamOpcode)).not.toContain(FileTransferOpcode.FileBegin);
expect(Object.values(TerminalStreamOpcode)).not.toContain(FileTransferOpcode.FileChunk);
expect(Object.values(TerminalStreamOpcode)).not.toContain(FileTransferOpcode.FileEnd);
});
it("encodes FileBegin as opcode plus request id prefix plus JSON metadata", () => {
const encoded = encodeFileTransferFrame({
opcode: FileTransferOpcode.FileBegin,
requestId: "req-1",
metadata: {
mime: "image/png",
size: 6,
encoding: "binary",
modifiedAt: "2026-05-02T00:00:00.000Z",
},
});
const requestId = encoder.encode("req-1");
const metadata = encoder.encode(
JSON.stringify({
mime: "image/png",
size: 6,
encoding: "binary",
modifiedAt: "2026-05-02T00:00:00.000Z",
}),
);
expect(decodeTerminalStreamFrame(encoded)).toBeNull();
expect(encoded[0]).toBe(FileTransferOpcode.FileBegin);
expect(encoded[1]).toBe(requestId.byteLength);
expect(encoded.subarray(2, 2 + requestId.byteLength)).toEqual(requestId);
expect(
new DataView(encoded.buffer, encoded.byteOffset).getUint16(2 + requestId.byteLength),
).toBe(metadata.byteLength);
expect(encoded.subarray(4 + requestId.byteLength)).toEqual(metadata);
expect(decodeFileTransferFrame(encoded)).toEqual({
opcode: FileTransferOpcode.FileBegin,
requestId: "req-1",
metadata: {
mime: "image/png",
size: 6,
encoding: "binary",
modifiedAt: "2026-05-02T00:00:00.000Z",
},
payload: new Uint8Array(),
});
});
it("encodes FileChunk as opcode plus request id prefix plus binary payload", () => {
const payload = new Uint8Array([0, 1, 2, 253, 254, 255]);
const encoded = encodeFileTransferFrame({
opcode: FileTransferOpcode.FileChunk,
requestId: "req-1",
payload,
});
const requestId = encoder.encode("req-1");
expect(encoded[0]).toBe(FileTransferOpcode.FileChunk);
expect(encoded[1]).toBe(requestId.byteLength);
expect(encoded.subarray(2, 2 + requestId.byteLength)).toEqual(requestId);
expect(encoded.subarray(2 + requestId.byteLength)).toEqual(payload);
const decoded = decodeFileTransferFrame(encoded);
expect(decoded).toEqual({
opcode: FileTransferOpcode.FileChunk,
requestId: "req-1",
payload,
});
expect(decoded?.payload).toBeInstanceOf(Uint8Array);
expect(decoded?.payload).toEqual(payload);
});
it("encodes FileEnd as opcode plus request id prefix only", () => {
const encoded = encodeFileTransferFrame({
opcode: FileTransferOpcode.FileEnd,
requestId: "req-1",
});
const requestId = encoder.encode("req-1");
expect(encoded).toEqual(
new Uint8Array([FileTransferOpcode.FileEnd, requestId.byteLength, ...requestId]),
);
expect(decodeFileTransferFrame(encoded)).toEqual({
opcode: FileTransferOpcode.FileEnd,
requestId: "req-1",
payload: new Uint8Array(),
});
});
it("rejects malformed metadata and unknown metadata fields", () => {
expect(
decodeFileTransferFrame(
encodeFileTransferFrame({
opcode: FileTransferOpcode.FileBegin,
requestId: "req-1",
metadata: {
mime: "image/png",
size: -1,
encoding: "binary",
modifiedAt: "2026-05-02T00:00:00.000Z",
},
}),
),
).toBeNull();
const json = encoder.encode(
JSON.stringify({
mime: "image/png",
size: 1,
encoding: "binary",
modifiedAt: "2026-05-02T00:00:00.000Z",
extra: true,
}),
);
const requestId = encoder.encode("req-1");
const encoded = new Uint8Array(4 + requestId.byteLength + json.byteLength);
encoded[0] = FileTransferOpcode.FileBegin;
encoded[1] = requestId.byteLength;
encoded.set(requestId, 2);
new DataView(encoded.buffer).setUint16(2 + requestId.byteLength, json.byteLength);
encoded.set(json, 4 + requestId.byteLength);
expect(decodeFileTransferFrame(encoded)).toBeNull();
});
it("rejects malformed request id prefixes and frame tails", () => {
expect(decodeFileTransferFrame(new Uint8Array([FileTransferOpcode.FileEnd, 0]))).toBeNull();
expect(decodeFileTransferFrame(new Uint8Array([FileTransferOpcode.FileEnd, 6, 1]))).toBeNull();
const requestId = encoder.encode("req-1");
const encoded = new Uint8Array([
FileTransferOpcode.FileEnd,
requestId.byteLength,
...requestId,
1,
]);
expect(decodeFileTransferFrame(encoded)).toBeNull();
});
});
packages/server/src/shared/binary-frames/file-transfer.ts
+163
View File
@@ -0,0 +1,163 @@
import { z } from "zod";
import { asUint8Array } from "./terminal.js";
export const FileTransferOpcode = {
FileBegin: 0x10,
FileChunk: 0x11,
FileEnd: 0x12,
} as const;
export type FileTransferOpcode = (typeof FileTransferOpcode)[keyof typeof FileTransferOpcode];
export const FileBeginMetadataSchema = z
.object({
mime: z.string().min(1),
size: z.number().int().nonnegative(),
encoding: z.enum(["utf-8", "binary"]),
modifiedAt: z.string(),
})
.strict();
export interface FileBegin {
opcode: typeof FileTransferOpcode.FileBegin;
requestId: string;
metadata: z.infer<typeof FileBeginMetadataSchema>;
payload: Uint8Array;
}
export interface FileChunk {
opcode: typeof FileTransferOpcode.FileChunk;
requestId: string;
payload: Uint8Array;
}
export interface FileEnd {
opcode: typeof FileTransferOpcode.FileEnd;
requestId: string;
payload: Uint8Array;
}
export type FileTransferFrame = FileBegin | FileChunk | FileEnd;
type FileTransferFrameInput =
| {
opcode: typeof FileTransferOpcode.FileBegin;
requestId: string;
metadata: z.infer<typeof FileBeginMetadataSchema>;
}
| {
opcode: typeof FileTransferOpcode.FileChunk;
requestId: string;
payload?: Uint8Array | ArrayBuffer | string;
}
| {
opcode: typeof FileTransferOpcode.FileEnd;
requestId: string;
};
export function encodeFileTransferFrame(input: FileTransferFrameInput): Uint8Array {
const requestId = encodeRequestId(input.requestId);
if (input.opcode === FileTransferOpcode.FileBegin) {
const metadata = encodeJsonPayload(input.metadata);
if (metadata.byteLength > 0xffff) {
throw new RangeError("FileBegin metadata is too long");
}
const bytes = new Uint8Array(4 + requestId.byteLength + metadata.byteLength);
const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
bytes[0] = input.opcode;
bytes[1] = requestId.byteLength;
bytes.set(requestId, 2);
view.setUint16(2 + requestId.byteLength, metadata.byteLength);
bytes.set(metadata, 4 + requestId.byteLength);
return bytes;
}
const payload =
input.opcode === FileTransferOpcode.FileChunk
? (asUint8Array(input.payload ?? new Uint8Array()) ?? new Uint8Array())
: new Uint8Array();
const bytes = new Uint8Array(2 + requestId.byteLength + payload.byteLength);
bytes[0] = input.opcode;
bytes[1] = requestId.byteLength;
bytes.set(requestId, 2);
bytes.set(payload, 2 + requestId.byteLength);
return bytes;
}
export function decodeFileTransferFrame(bytes: Uint8Array): FileTransferFrame | null {
if (bytes.byteLength < 2) {
return null;
}
const opcode = bytes[0];
if (!isFileTransferOpcode(opcode)) {
return null;
}
const requestIdLength = bytes[1];
if (requestIdLength === 0 || requestIdLength > bytes.byteLength - 2) {
return null;
}
const requestId = decodeRequestId(bytes.subarray(2, 2 + requestIdLength));
const body = bytes.subarray(2 + requestIdLength);
if (opcode === FileTransferOpcode.FileBegin) {
if (body.byteLength < 2) {
return null;
}
const view = new DataView(body.buffer, body.byteOffset, body.byteLength);
const metadataLength = view.getUint16(0);
if (metadataLength !== body.byteLength - 2) {
return null;
}
const metadataBytes = body.subarray(2);
const result = FileBeginMetadataSchema.safeParse(decodeJsonPayload(metadataBytes));
return result.success
? { opcode, requestId, metadata: result.data, payload: new Uint8Array() }
: null;
}
if (opcode === FileTransferOpcode.FileChunk) {
return { opcode, requestId, payload: body };
}
if (body.byteLength !== 0) {
return null;
}
return { opcode, requestId, payload: new Uint8Array() };
}
function isFileTransferOpcode(value: number): value is FileTransferOpcode {
return (
value === FileTransferOpcode.FileBegin ||
value === FileTransferOpcode.FileChunk ||
value === FileTransferOpcode.FileEnd
);
}
function encodeJsonPayload(value: unknown): Uint8Array {
return new TextEncoder().encode(JSON.stringify(value));
}
function encodeRequestId(requestId: string): Uint8Array {
const bytes = new TextEncoder().encode(requestId);
if (bytes.byteLength === 0) {
throw new RangeError("File transfer requestId is required");
}
if (bytes.byteLength > 0xff) {
throw new RangeError("File transfer requestId is too long");
}
return bytes;
}
function decodeRequestId(bytes: Uint8Array): string {
return new TextDecoder().decode(bytes);
}
function decodeJsonPayload(bytes: Uint8Array): unknown {
try {
return JSON.parse(new TextDecoder().decode(bytes));
} catch {
return null;
}
}
packages/server/src/shared/binary-frames/index.ts
+2
View File
@@ -0,0 +1,2 @@
export * from "./file-transfer.js";
export * from "./terminal.js";
packages/server/src/shared/binary-frames/terminal.test.ts
+114
View File
@@ -0,0 +1,114 @@
import { describe, expect, it } from "vitest";
import {
TerminalStreamOpcode,
decodeTerminalResizePayload,
decodeTerminalSnapshotPayload,
decodeTerminalStreamFrame,
encodeTerminalResizePayload,
encodeTerminalSnapshotPayload,
encodeTerminalStreamFrame,
} from "./index.js";
describe("terminal binary frames", () => {
it("encodes output frames as opcode plus slot plus payload", () => {
const payload = new TextEncoder().encode("hello");
const encoded = encodeTerminalStreamFrame({
opcode: TerminalStreamOpcode.Output,
slot: 7,
payload,
});
expect(encoded[0]).toBe(TerminalStreamOpcode.Output);
expect(encoded[1]).toBe(7);
expect(Array.from(encoded.subarray(2))).toEqual(Array.from(payload));
const decoded = decodeTerminalStreamFrame(encoded);
expect(decoded).toEqual({
opcode: TerminalStreamOpcode.Output,
slot: 7,
payload,
});
});
it("round-trips resize payloads", () => {
const payload = encodeTerminalResizePayload({
rows: 24,
cols: 80,
});
expect(decodeTerminalResizePayload(payload)).toEqual({
rows: 24,
cols: 80,
});
});
it("round-trips snapshot payloads", () => {
const state = {
rows: 1,
cols: 2,
grid: [[{ char: "A" }, { char: "B" }]],
scrollback: [],
cursor: { row: 0, col: 2 },
};
const payload = encodeTerminalSnapshotPayload(state);
expect(decodeTerminalSnapshotPayload(payload)).toEqual(state);
});
it("rejects unknown opcodes", () => {
expect(decodeTerminalStreamFrame(new Uint8Array([0xff, 0x01, 0x02]))).toBeNull();
});
it("rejects frames without a slot byte", () => {
expect(decodeTerminalStreamFrame(new Uint8Array([TerminalStreamOpcode.Output]))).toBeNull();
});
it("rejects malformed JSON payloads", () => {
const malformed = new TextEncoder().encode("{");
expect(decodeTerminalResizePayload(malformed)).toBeNull();
expect(decodeTerminalSnapshotPayload(malformed)).toBeNull();
});
it("rejects invalid resize and snapshot shapes", () => {
expect(
decodeTerminalResizePayload(
new TextEncoder().encode(JSON.stringify({ rows: "24", cols: 80 })),
),
).toBeNull();
expect(
decodeTerminalSnapshotPayload(
new TextEncoder().encode(
JSON.stringify({
rows: 1,
cols: 1,
grid: [[{ char: "A" }]],
scrollback: [],
}),
),
),
).toBeNull();
});
it("rejects unknown fields in resize and snapshot payloads", () => {
expect(
decodeTerminalResizePayload(
new TextEncoder().encode(JSON.stringify({ rows: 24, cols: 80, extra: true })),
),
).toBeNull();
expect(
decodeTerminalSnapshotPayload(
new TextEncoder().encode(
JSON.stringify({
rows: 1,
cols: 1,
grid: [[{ char: "A", extra: true }]],
scrollback: [],
cursor: { row: 0, col: 1 },
}),
),
),
).toBeNull();
});
});
packages/server/src/shared/binary-frames/terminal.ts
+131
View File
@@ -0,0 +1,131 @@
import { z } from "zod";
import { TerminalStateSchema } from "../messages.js";
export const TerminalStreamResizeSchema = z
.object({
rows: z.number().int().positive(),
cols: z.number().int().positive(),
})
.strict();
export const TerminalStreamOpcode = {
Output: 0x01,
Input: 0x02,
Resize: 0x03,
Snapshot: 0x04,
} as const;
export type TerminalStreamOpcode = (typeof TerminalStreamOpcode)[keyof typeof TerminalStreamOpcode];
export interface TerminalStreamFrame {
opcode: TerminalStreamOpcode;
slot: number;
payload: Uint8Array;
}
export function asUint8Array(data: unknown): Uint8Array | null {
if (typeof data === "string") {
if (typeof TextEncoder !== "undefined") {
return new TextEncoder().encode(data);
}
if (typeof Buffer !== "undefined") {
return new Uint8Array(Buffer.from(data, "utf8"));
}
const out = new Uint8Array(data.length);
for (let index = 0; index < data.length; index += 1) {
out[index] = data.charCodeAt(index) & 0xff;
}
return out;
}
if (data instanceof Uint8Array) {
return data;
}
if (typeof ArrayBuffer !== "undefined" && data instanceof ArrayBuffer) {
return new Uint8Array(data);
}
if (ArrayBuffer.isView(data)) {
return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
}
if (typeof Buffer !== "undefined" && Buffer.isBuffer(data)) {
return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
}
return null;
}
function isTerminalStreamOpcode(value: number): value is TerminalStreamOpcode {
return (
value === TerminalStreamOpcode.Output ||
value === TerminalStreamOpcode.Input ||
value === TerminalStreamOpcode.Resize ||
value === TerminalStreamOpcode.Snapshot
);
}
export function encodeTerminalStreamFrame(input: {
opcode: TerminalStreamOpcode;
slot: number;
payload?: Uint8Array | ArrayBuffer | string;
}): Uint8Array {
const payload = asUint8Array(input.payload ?? new Uint8Array(0)) ?? new Uint8Array(0);
const bytes = new Uint8Array(2 + payload.byteLength);
bytes[0] = input.opcode;
bytes[1] = input.slot & 0xff;
bytes.set(payload, 2);
return bytes;
}
export function decodeTerminalStreamFrame(bytes: Uint8Array): TerminalStreamFrame | null {
if (bytes.byteLength < 2) {
return null;
}
const opcode = bytes[0];
if (!isTerminalStreamOpcode(opcode)) {
return null;
}
return {
opcode,
slot: bytes[1],
payload: bytes.subarray(2),
};
}
export function encodeTerminalSnapshotPayload(
state: z.infer<typeof TerminalStateSchema>,
): Uint8Array {
return encodeJsonPayload(state);
}
export function decodeTerminalSnapshotPayload(
bytes: Uint8Array,
): z.infer<typeof TerminalStateSchema> | null {
const parsed = decodeJsonPayload(bytes);
const result = TerminalStateSchema.safeParse(parsed);
return result.success ? result.data : null;
}
export function encodeTerminalResizePayload(
input: z.infer<typeof TerminalStreamResizeSchema>,
): Uint8Array {
return encodeJsonPayload(input);
}
export function decodeTerminalResizePayload(
bytes: Uint8Array,
): z.infer<typeof TerminalStreamResizeSchema> | null {
const parsed = decodeJsonPayload(bytes);
const result = TerminalStreamResizeSchema.safeParse(parsed);
return result.success ? result.data : null;
}
function encodeJsonPayload(value: unknown): Uint8Array {
return new TextEncoder().encode(JSON.stringify(value));
}
function decodeJsonPayload(bytes: Uint8Array): unknown {
try {
const text = new TextDecoder().decode(bytes);
return JSON.parse(text);
} catch {
return null;
}
}
packages/server/src/shared/messages.test.ts
+36 -1
View File
@@ -1,5 +1,5 @@
import { describe, expect, test } from "vitest";
import { SessionOutboundMessageSchema } from "./messages.js";
import { FileExplorerRequestSchema, SessionOutboundMessageSchema } from "./messages.js";
function workspaceDescriptor(overrides: Record<string, unknown> = {}) {
return {
@@ -126,3 +126,38 @@ describe("workspace descriptor message compatibility", () => {
});
});
});
describe("file explorer request compatibility", () => {
test("acceptBinary is optional for old clients and accepted for new clients", () => {
expect(
FileExplorerRequestSchema.parse({
type: "file_explorer_request",
cwd: "/repo/app",
path: "image.png",
mode: "file",
requestId: "req-old",
}),
).toEqual({
type: "file_explorer_request",
cwd: "/repo/app",
path: "image.png",
mode: "file",
requestId: "req-old",
});
expect(
FileExplorerRequestSchema.parse({
type: "file_explorer_request",
cwd: "/repo/app",
path: "image.png",
mode: "file",
requestId: "req-new",
acceptBinary: true,
}),
).toMatchObject({
type: "file_explorer_request",
requestId: "req-new",
acceptBinary: true,
});
});
});
packages/server/src/shared/messages.ts
+1
View File
@@ -1505,6 +1505,7 @@ export const FileExplorerRequestSchema = z.object({
path: z.string().optional(),
mode: z.enum(["list", "file"]),
requestId: z.string(),
acceptBinary: z.boolean().optional(),
});
export const ProjectIconRequestSchema = z.object({
packages/server/src/shared/terminal-stream-protocol.test.ts
+18 -96
View File
@@ -1,114 +1,36 @@
import { describe, expect, it } from "vitest";
import {
TerminalStreamOpcode,
decodeTerminalResizePayload,
decodeTerminalSnapshotPayload,
decodeTerminalStreamFrame,
encodeTerminalResizePayload,
encodeTerminalSnapshotPayload,
encodeTerminalStreamFrame,
} from "./terminal-stream-protocol.js";
import * as terminalBinaryFrames from "./binary-frames/index.js";
import * as legacyTerminalStreamProtocol from "./terminal-stream-protocol.js";
describe("terminal stream protocol", () => {
it("encodes output frames as opcode plus slot plus payload", () => {
it("keeps the old import path compatible with terminal binary frames", () => {
expect(legacyTerminalStreamProtocol.TerminalStreamOpcode).toBe(
terminalBinaryFrames.TerminalStreamOpcode,
);
expect(legacyTerminalStreamProtocol.encodeTerminalStreamFrame).toBe(
terminalBinaryFrames.encodeTerminalStreamFrame,
);
expect(legacyTerminalStreamProtocol.decodeTerminalStreamFrame).toBe(
terminalBinaryFrames.decodeTerminalStreamFrame,
);
const payload = new TextEncoder().encode("hello");
const encoded = encodeTerminalStreamFrame({
opcode: TerminalStreamOpcode.Output,
const encoded = legacyTerminalStreamProtocol.encodeTerminalStreamFrame({
opcode: legacyTerminalStreamProtocol.TerminalStreamOpcode.Output,
slot: 7,
payload,
});
expect(encoded[0]).toBe(TerminalStreamOpcode.Output);
expect(encoded[0]).toBe(terminalBinaryFrames.TerminalStreamOpcode.Output);
expect(encoded[1]).toBe(7);
expect(Array.from(encoded.subarray(2))).toEqual(Array.from(payload));
const decoded = decodeTerminalStreamFrame(encoded);
const decoded = terminalBinaryFrames.decodeTerminalStreamFrame(encoded);
expect(decoded).toEqual({
opcode: TerminalStreamOpcode.Output,
opcode: legacyTerminalStreamProtocol.TerminalStreamOpcode.Output,
slot: 7,
payload,
});
});
it("round-trips resize payloads", () => {
const payload = encodeTerminalResizePayload({
rows: 24,
cols: 80,
});
expect(decodeTerminalResizePayload(payload)).toEqual({
rows: 24,
cols: 80,
});
});
it("round-trips snapshot payloads", () => {
const state = {
rows: 1,
cols: 2,
grid: [[{ char: "A" }, { char: "B" }]],
scrollback: [],
cursor: { row: 0, col: 2 },
};
const payload = encodeTerminalSnapshotPayload(state);
expect(decodeTerminalSnapshotPayload(payload)).toEqual(state);
});
it("rejects unknown opcodes", () => {
expect(decodeTerminalStreamFrame(new Uint8Array([0xff, 0x01, 0x02]))).toBeNull();
});
it("rejects frames without a slot byte", () => {
expect(decodeTerminalStreamFrame(new Uint8Array([TerminalStreamOpcode.Output]))).toBeNull();
});
it("rejects malformed JSON payloads", () => {
const malformed = new TextEncoder().encode("{");
expect(decodeTerminalResizePayload(malformed)).toBeNull();
expect(decodeTerminalSnapshotPayload(malformed)).toBeNull();
});
it("rejects invalid resize and snapshot shapes", () => {
expect(
decodeTerminalResizePayload(
new TextEncoder().encode(JSON.stringify({ rows: "24", cols: 80 })),
),
).toBeNull();
expect(
decodeTerminalSnapshotPayload(
new TextEncoder().encode(
JSON.stringify({
rows: 1,
cols: 1,
grid: [[{ char: "A" }]],
scrollback: [],
}),
),
),
).toBeNull();
});
it("rejects unknown fields in resize and snapshot payloads", () => {
expect(
decodeTerminalResizePayload(
new TextEncoder().encode(JSON.stringify({ rows: 24, cols: 80, extra: true })),
),
).toBeNull();
expect(
decodeTerminalSnapshotPayload(
new TextEncoder().encode(
JSON.stringify({
rows: 1,
cols: 1,
grid: [[{ char: "A", extra: true }]],
scrollback: [],
cursor: { row: 0, col: 1 },
}),
),
),
).toBeNull();
});
});
packages/server/src/shared/terminal-stream-protocol.ts
+1 -131
View File
@@ -1,131 +1 @@
import { z } from "zod";
import { TerminalStateSchema } from "./messages.js";
export const TerminalStreamResizeSchema = z
.object({
rows: z.number().int().positive(),
cols: z.number().int().positive(),
})
.strict();
export const TerminalStreamOpcode = {
Output: 0x01,
Input: 0x02,
Resize: 0x03,
Snapshot: 0x04,
} as const;
export type TerminalStreamOpcode = (typeof TerminalStreamOpcode)[keyof typeof TerminalStreamOpcode];
export interface TerminalStreamFrame {
opcode: TerminalStreamOpcode;
slot: number;
payload: Uint8Array;
}
export function asUint8Array(data: unknown): Uint8Array | null {
if (typeof data === "string") {
if (typeof TextEncoder !== "undefined") {
return new TextEncoder().encode(data);
}
if (typeof Buffer !== "undefined") {
return new Uint8Array(Buffer.from(data, "utf8"));
}
const out = new Uint8Array(data.length);
for (let index = 0; index < data.length; index += 1) {
out[index] = data.charCodeAt(index) & 0xff;
}
return out;
}
if (data instanceof Uint8Array) {
return data;
}
if (typeof ArrayBuffer !== "undefined" && data instanceof ArrayBuffer) {
return new Uint8Array(data);
}
if (ArrayBuffer.isView(data)) {
return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
}
if (typeof Buffer !== "undefined" && Buffer.isBuffer(data)) {
return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
}
return null;
}
function isTerminalStreamOpcode(value: number): value is TerminalStreamOpcode {
return (
value === TerminalStreamOpcode.Output ||
value === TerminalStreamOpcode.Input ||
value === TerminalStreamOpcode.Resize ||
value === TerminalStreamOpcode.Snapshot
);
}
export function encodeTerminalStreamFrame(input: {
opcode: TerminalStreamOpcode;
slot: number;
payload?: Uint8Array | ArrayBuffer | string;
}): Uint8Array {
const payload = asUint8Array(input.payload ?? new Uint8Array(0)) ?? new Uint8Array(0);
const bytes = new Uint8Array(2 + payload.byteLength);
bytes[0] = input.opcode;
bytes[1] = input.slot & 0xff;
bytes.set(payload, 2);
return bytes;
}
export function decodeTerminalStreamFrame(bytes: Uint8Array): TerminalStreamFrame | null {
if (bytes.byteLength < 2) {
return null;
}
const opcode = bytes[0];
if (!isTerminalStreamOpcode(opcode)) {
return null;
}
return {
opcode,
slot: bytes[1],
payload: bytes.subarray(2),
};
}
export function encodeTerminalSnapshotPayload(
state: z.infer<typeof TerminalStateSchema>,
): Uint8Array {
return encodeJsonPayload(state);
}
export function decodeTerminalSnapshotPayload(
bytes: Uint8Array,
): z.infer<typeof TerminalStateSchema> | null {
const parsed = decodeJsonPayload(bytes);
const result = TerminalStateSchema.safeParse(parsed);
return result.success ? result.data : null;
}
export function encodeTerminalResizePayload(
input: z.infer<typeof TerminalStreamResizeSchema>,
): Uint8Array {
return encodeJsonPayload(input);
}
export function decodeTerminalResizePayload(
bytes: Uint8Array,
): z.infer<typeof TerminalStreamResizeSchema> | null {
const parsed = decodeJsonPayload(bytes);
const result = TerminalStreamResizeSchema.safeParse(parsed);
return result.success ? result.data : null;
}
function encodeJsonPayload(value: unknown): Uint8Array {
return new TextEncoder().encode(JSON.stringify(value));
}
function decodeJsonPayload(bytes: Uint8Array): unknown {
try {
const text = new TextDecoder().decode(bytes);
return JSON.parse(text);
} catch {
return null;
}
}
export * from "./binary-frames/terminal.js";
packages/server/src/terminal/terminal-session-controller.ts
+1 -1
View File
@@ -19,7 +19,7 @@ import {
encodeTerminalSnapshotPayload,
encodeTerminalStreamFrame,
type TerminalStreamFrame,
} from "../shared/terminal-stream-protocol.js";
} from "../shared/binary-frames/index.js";
import { TerminalOutputCoalescer } from "./terminal-output-coalescer.js";
import type { TerminalSession } from "./terminal.js";
import type { TerminalManager, TerminalsChangedEvent } from "./terminal-manager.js";