@av-pi-studio/server 0.0.117 → 0.0.118

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -648,6 +648,7 @@ export function startDaemon(opts) {
648
648
  subscriptions.disposeSession(session);
649
649
  daemonStatusService.disposeSession(session);
650
650
  daemonLogsService.disposeSession(session);
651
+ fileTransfer.disposeSession(session);
651
652
  },
652
653
  onMessage: (session, frame) => {
653
654
  if ("text" in frame) {
@@ -688,6 +689,7 @@ export function startDaemon(opts) {
688
689
  subscriptions.disposeSession(relaySession);
689
690
  daemonStatusService.disposeSession(relaySession);
690
691
  daemonLogsService.disposeSession(relaySession);
692
+ fileTransfer.disposeSession(relaySession);
691
693
  }
692
694
  relaySession = null;
693
695
  };
@@ -716,6 +718,7 @@ export function startDaemon(opts) {
716
718
  id: randomUUID(),
717
719
  clientId: hello.data.clientId,
718
720
  clientType: hello.data.clientType,
721
+ platform: hello.data.platform,
719
722
  capabilities,
720
723
  appVersion: hello.data.appVersion,
721
724
  transport: "relay",
@@ -9,10 +9,11 @@
9
9
  import { randomUUID } from "node:crypto";
10
10
  import { readFile, stat } from "node:fs/promises";
11
11
  import { execFile } from "node:child_process";
12
+ import { join } from "node:path";
12
13
  import { expandHome } from "../files/resolve-path.js";
13
14
  import { createHttpServer } from "../http/http-server.js";
14
15
  import { createWebSocketServer } from "../ws/ws-server.js";
15
- import { HandlerRegistry, routeTextFrame } from "../ws/router.js";
16
+ import { HandlerRegistry, routeBinaryFrame, routeTextFrame } from "../ws/router.js";
16
17
  import { registerAgentUiHandlers } from "../agent/agent-ui/agent-ui-rpc.js";
17
18
  import { AgentUiService } from "../agent/agent-ui/agent-ui-service.js";
18
19
  import { registerAgentTodosHandlers } from "../agent/agent-todos/agent-todos-rpc.js";
@@ -26,6 +27,7 @@ import { registerTimelineHandler } from "../agent/timeline-rpc.js";
26
27
  import { createMockClient } from "../agent/providers/mock/mock-provider.js";
27
28
  import { ProviderRegistry } from "../agent/provider-registry.js";
28
29
  import { FileExplorerService } from "../files/file-explorer.js";
30
+ import { FileTransferService } from "../files/file-transfer.js";
29
31
  import { MAX_INLINE_FILE_READ_BYTES } from "../files/limits.js";
30
32
  import { LogTap } from "../logging/log-tap.js";
31
33
  import { createDaemonLogger } from "../logging/logger.js";
@@ -33,6 +35,8 @@ import { registerDaemonLogsHandlers } from "../observability/daemon-logs-rpc.js"
33
35
  import { DaemonLogsService } from "../observability/daemon-logs-service.js";
34
36
  import { registerDaemonStatusHandlers } from "../observability/daemon-status-rpc.js";
35
37
  import { DaemonStatusService } from "../observability/daemon-status-service.js";
38
+ import { TerminalManager } from "../terminal/terminal-manager.js";
39
+ import { makeTerminalBinaryHandler, registerTerminalHandlers } from "../terminal/terminal-rpc.js";
36
40
  import { registerViewerSettingsHandlers } from "../viewers/viewer-settings-rpc.js";
37
41
  import { SERVER_VERSION } from "../version.js";
38
42
  import { wrapSessionEnvelope } from "./bootstrap.js";
@@ -262,7 +266,23 @@ export function startDevDaemon(opts) {
262
266
  // ── File explorer: real directory listing + file preview from disk ───────
263
267
  // (features/file-explorer-transfer.md). Lets the workspace Explorer + file
264
268
  // preview panes show actual files.
265
- new FileExplorerService().registerHandlers(registry);
269
+ //
270
+ // Same wiring as production `bootstrap.ts`: the explorer issues download tokens through the
271
+ // transfer service, which also owns the token / download / upload RPCs and the upload binary
272
+ // handler.
273
+ const fileTransfer = new FileTransferService();
274
+ new FileExplorerService({ issueDownloadToken: fileTransfer.issueDownloadToken }).registerHandlers(registry);
275
+ fileTransfer.registerHandlers(registry);
276
+ const fileTransferBinary = fileTransfer.binaryHandler();
277
+ // ── Terminals: manager + control RPCs + binary stream (same wiring as production) ──────────
278
+ const terminalManager = new TerminalManager({ logger });
279
+ registerTerminalHandlers(registry, {
280
+ manager: terminalManager,
281
+ broadcast,
282
+ restoreModesEnabled: true,
283
+ projectConfigPath: (cwd) => join(cwd, "pi-studio.json"),
284
+ }, getActiveSessions);
285
+ const terminalBinaryHandler = makeTerminalBinaryHandler(terminalManager, broadcast, getActiveSessions);
266
286
  // Simple file diff RPC for the POC UI. Untracked (brand-new) files have no git-tracked "before"
267
287
  // state, so a plain `git diff` against them is always empty — git only diffs a path once it's
268
288
  // in the index or committed. Fall back to `git diff --no-index /dev/null <path>` (exit code 1
@@ -289,8 +309,7 @@ export function startDevDaemon(opts) {
289
309
  return { type: "file_diff_response", ok: true, path: filePath, patch };
290
310
  });
291
311
  // Simple text file read RPC for the POC UI (returns up to `MAX_INLINE_FILE_READ_BYTES` of
292
- // UTF-8 text; larger files must use the chunked binary download path instead — note
293
- // download-token RPCs are not registered in this dev bootstrap; see AGENTS.md). Async so a
312
+ // UTF-8 text; larger files must use the chunked binary download path instead). Async so a
294
313
  // multi-MB read/decode never blocks the event loop.
295
314
  registry.register("file_read_request", async (ctx) => {
296
315
  const filePath = String(ctx.message.path ?? "");
@@ -337,12 +356,19 @@ export function startDevDaemon(opts) {
337
356
  onSessionClose: (session) => {
338
357
  daemonStatusService.disposeSession(session);
339
358
  daemonLogsService.disposeSession(session);
359
+ fileTransfer.disposeSession(session);
340
360
  },
341
361
  onMessage: (session, frame) => {
342
362
  if ("text" in frame) {
343
363
  void routeTextFrame(session, frame.text, registry);
344
364
  }
345
- // Binary (terminal) frames not wired in dev bootstrap yet.
365
+ else {
366
+ // Binary frames: try terminal (Input/Resize) then file-transfer (upload) decoders.
367
+ routeBinaryFrame(session, frame.binary, (s, bytes) => {
368
+ terminalBinaryHandler(s, bytes);
369
+ fileTransferBinary(s, bytes);
370
+ });
371
+ }
346
372
  },
347
373
  });
348
374
  // Now that the WS server exists, point the holder at its live session set.
@@ -360,6 +386,7 @@ export function startDevDaemon(opts) {
360
386
  close: async () => {
361
387
  logger.info("dev daemon shutting down");
362
388
  daemonStatusService.dispose();
389
+ terminalManager.killAll();
363
390
  daemonLogsService.dispose();
364
391
  await wsHandle.close();
365
392
  await new Promise((resolve) => httpServer.close(() => resolve()));
@@ -1,12 +1,35 @@
1
+ import type { Session } from "../ws/session.js";
1
2
  import type { BinaryHandler, HandlerRegistry } from "../ws/router.js";
2
3
  import { DownloadTokenStore } from "./download-token-store.js";
4
+ /**
5
+ * A download stops reading from disk while this many bytes are queued on the session's socket (32
6
+ * default chunks) and resumes below the low mark. Chosen, not measured: big enough that the read
7
+ * never starves a fast LAN link between polls, small enough that a stalled client costs the daemon
8
+ * about a megabyte instead of the whole file. Injectable through `FileTransferDeps`.
9
+ */
10
+ export declare const DOWNLOAD_HIGH_WATER_BYTES: number;
11
+ export declare const DOWNLOAD_LOW_WATER_BYTES: number;
3
12
  export interface FileTransferDeps {
4
13
  tokenStore?: DownloadTokenStore;
5
14
  chunkBytes?: number;
15
+ highWaterBytes?: number;
16
+ lowWaterBytes?: number;
17
+ /** How often a paused download re-reads the socket's queue. */
18
+ drainPollMs?: number;
19
+ }
20
+ /** What a download needs to know about the socket it writes to. Absent means "do not pace". */
21
+ export interface DownloadPacing {
22
+ /** Bytes queued and not yet flushed; `undefined` when the socket cannot say. */
23
+ bufferedAmount(): number | undefined;
24
+ /** False once the socket is closing or closed: the transfer ends without further frames. */
25
+ isOpen(): boolean;
6
26
  }
7
27
  export declare class FileTransferService {
8
28
  readonly tokenStore: DownloadTokenStore;
9
29
  private readonly chunkBytes;
30
+ private readonly highWaterBytes;
31
+ private readonly lowWaterBytes;
32
+ private readonly drainPollMs;
10
33
  /** Pending uploads keyed by stream id. */
11
34
  private readonly uploads;
12
35
  /** Rotating hand-out point in the one-byte stream id space (see `nextFreeSlot`). */
@@ -21,15 +44,31 @@ export declare class FileTransferService {
21
44
  private takeStream;
22
45
  /**
23
46
  * Validate + consume the token, then stream the file as `Begin → Chunk* → End` binary frames.
47
+ *
48
+ * With `pacing`, the disk read pauses while the socket's queue is above the high-water mark, so a
49
+ * client that reads slowly costs the daemon about that much memory, not the whole file. A read
50
+ * error sends one `Error` frame and stops (no `End`); a socket that closed mid-transfer ends it
51
+ * silently.
24
52
  */
25
- startDownload(token: string, stream: number, sink: (frame: Uint8Array) => void): Promise<{
53
+ startDownload(token: string, stream: number, sink: (frame: Uint8Array) => void, pacing?: DownloadPacing): Promise<{
26
54
  ok: boolean;
27
55
  error?: string;
28
56
  transferId?: string;
29
57
  }>;
58
+ private pipeFile;
59
+ /** Resolves `true` once the socket's queue is at or below the low-water mark; `false` if it closed. */
60
+ private waitForDrain;
30
61
  /** Binary frame handler for upload streams (Begin → Chunk* → End). Frames are serialized per
31
- * stream so an in-flight `Begin` (open) completes before any `Chunk` writes. */
62
+ * stream so an in-flight `Begin` (open) completes before any `Chunk` writes. A frame is applied
63
+ * only if it comes from the session that opened the stream. */
32
64
  binaryHandler(): BinaryHandler;
65
+ /**
66
+ * Release everything a session left open: its pending uploads lose their stream id and their file
67
+ * handle is closed once frames already in flight finish. Nothing is sent (the session is gone).
68
+ */
69
+ disposeSession(session: Session): void;
33
70
  private handleUploadFrame;
71
+ /** Release the stream; push `file_upload_complete` if the client asked for it. */
72
+ private finishUpload;
34
73
  }
35
74
  //# sourceMappingURL=file-transfer.d.ts.map
@@ -9,11 +9,29 @@ import { expandHome } from "./resolve-path.js";
9
9
  * Chunked file download (token-authorized) + upload over the file-transfer binary frame format
10
10
  * (features/file-explorer-transfer.md § Binary transfer frames, § Behavior). Downloads stream
11
11
  * `Begin → Chunk* → End`; uploads consume the same frames and write to the target path.
12
+ * Flow control, completion and stream ownership: features/desktop-client-protocol-followups.md § 2.
12
13
  */
13
14
  const DEFAULT_CHUNK_BYTES = 32 * 1024;
15
+ /**
16
+ * A download stops reading from disk while this many bytes are queued on the session's socket (32
17
+ * default chunks) and resumes below the low mark. Chosen, not measured: big enough that the read
18
+ * never starves a fast LAN link between polls, small enough that a stalled client costs the daemon
19
+ * about a megabyte instead of the whole file. Injectable through `FileTransferDeps`.
20
+ */
21
+ export const DOWNLOAD_HIGH_WATER_BYTES = 1024 * 1024;
22
+ export const DOWNLOAD_LOW_WATER_BYTES = 256 * 1024;
23
+ const DEFAULT_DRAIN_POLL_MS = 10;
24
+ /** `open_failed (EACCES)`-style text: a stage plus the errno code, never a path or a stack. */
25
+ function failureText(stage, err) {
26
+ const code = err?.code;
27
+ return typeof code === "string" ? `${stage}_failed (${code})` : `${stage}_failed`;
28
+ }
14
29
  export class FileTransferService {
15
30
  tokenStore;
16
31
  chunkBytes;
32
+ highWaterBytes;
33
+ lowWaterBytes;
34
+ drainPollMs;
17
35
  /** Pending uploads keyed by stream id. */
18
36
  uploads = new Map();
19
37
  /** Rotating hand-out point in the one-byte stream id space (see `nextFreeSlot`). */
@@ -21,6 +39,9 @@ export class FileTransferService {
21
39
  constructor(deps = {}) {
22
40
  this.tokenStore = deps.tokenStore ?? new DownloadTokenStore();
23
41
  this.chunkBytes = deps.chunkBytes ?? DEFAULT_CHUNK_BYTES;
42
+ this.highWaterBytes = deps.highWaterBytes ?? DOWNLOAD_HIGH_WATER_BYTES;
43
+ this.lowWaterBytes = deps.lowWaterBytes ?? DOWNLOAD_LOW_WATER_BYTES;
44
+ this.drainPollMs = deps.drainPollMs ?? DEFAULT_DRAIN_POLL_MS;
24
45
  }
25
46
  /** Issue a download token for a resolved path (also used by the file explorer for binary files). */
26
47
  issueDownloadToken = (resolvedPath) => this.tokenStore.issue(resolvedPath).token;
@@ -46,7 +67,10 @@ export class FileTransferService {
46
67
  if (!Number.isInteger(stream) || stream < 0 || stream >= SLOT_SPACE) {
47
68
  return { type: "file_download_response", stream, ok: false, error: "invalid_stream" };
48
69
  }
49
- const result = await this.startDownload(token, stream, (frame) => ctx.session.sendBinary(frame));
70
+ const result = await this.startDownload(token, stream, (frame) => ctx.session.sendBinary(frame), {
71
+ bufferedAmount: () => ctx.session.bufferedAmount,
72
+ isOpen: () => ctx.session.isOpen,
73
+ });
50
74
  return { type: "file_download_response", stream, ...result };
51
75
  });
52
76
  registry.register("file_upload_request", (ctx) => {
@@ -63,9 +87,12 @@ export class FileTransferService {
63
87
  this.uploads.set(stream, {
64
88
  transferId,
65
89
  targetPath,
90
+ sessionId: ctx.session.id,
91
+ ack: ctx.message.ack === true,
66
92
  handle: null,
67
93
  bytesWritten: 0,
68
94
  chain: Promise.resolve(),
95
+ done: false,
69
96
  });
70
97
  return { type: "file_upload_response", ok: true, stream };
71
98
  });
@@ -80,8 +107,13 @@ export class FileTransferService {
80
107
  }
81
108
  /**
82
109
  * Validate + consume the token, then stream the file as `Begin → Chunk* → End` binary frames.
110
+ *
111
+ * With `pacing`, the disk read pauses while the socket's queue is above the high-water mark, so a
112
+ * client that reads slowly costs the daemon about that much memory, not the whole file. A read
113
+ * error sends one `Error` frame and stops (no `End`); a socket that closed mid-transfer ends it
114
+ * silently.
83
115
  */
84
- async startDownload(token, stream, sink) {
116
+ async startDownload(token, stream, sink, pacing) {
85
117
  const path = this.tokenStore.consume(token);
86
118
  if (!path)
87
119
  return { ok: false, error: "invalid_or_expired_token" };
@@ -91,63 +123,155 @@ export class FileTransferService {
91
123
  stream,
92
124
  meta: { transferId, fileName: basename(path), mimeType: mimeHintForFile(path) },
93
125
  }));
94
- await new Promise((resolve, reject) => {
95
- const rs = createReadStream(path, { highWaterMark: this.chunkBytes });
96
- rs.on("data", (chunk) => {
97
- const bytes = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
98
- sink(encodeFileTransferFrame({ opcode: "Chunk", stream, data: new Uint8Array(bytes) }));
99
- });
100
- rs.on("end", () => resolve());
101
- rs.on("error", reject);
102
- }).catch(() => {
126
+ const outcome = await this.pipeFile(path, stream, sink, pacing);
127
+ if (outcome === "closed")
128
+ return { ok: false, error: "connection_closed", transferId };
129
+ if (outcome === "error") {
103
130
  sink(encodeFileTransferFrame({ opcode: "Error", stream, message: "read_failed" }));
104
- });
131
+ return { ok: false, error: "read_failed", transferId };
132
+ }
105
133
  sink(encodeFileTransferFrame({ opcode: "End", stream, ok: true }));
106
134
  return { ok: true, transferId };
107
135
  }
136
+ pipeFile(path, stream, sink, pacing) {
137
+ const { promise, resolve } = Promise.withResolvers();
138
+ const rs = createReadStream(path, { highWaterMark: this.chunkBytes });
139
+ let settled = false;
140
+ const finish = (outcome) => {
141
+ if (settled)
142
+ return;
143
+ settled = true;
144
+ rs.destroy();
145
+ resolve(outcome);
146
+ };
147
+ rs.on("data", (chunk) => {
148
+ if (settled)
149
+ return;
150
+ if (pacing && !pacing.isOpen())
151
+ return finish("closed");
152
+ const bytes = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
153
+ sink(encodeFileTransferFrame({ opcode: "Chunk", stream, data: new Uint8Array(bytes) }));
154
+ const queued = pacing?.bufferedAmount();
155
+ if (pacing && queued !== undefined && queued > this.highWaterBytes) {
156
+ rs.pause();
157
+ void this.waitForDrain(pacing).then((stillOpen) => {
158
+ if (!stillOpen)
159
+ finish("closed");
160
+ else if (!settled)
161
+ rs.resume();
162
+ });
163
+ }
164
+ });
165
+ rs.on("end", () => finish("end"));
166
+ rs.on("error", () => finish("error"));
167
+ return promise;
168
+ }
169
+ /** Resolves `true` once the socket's queue is at or below the low-water mark; `false` if it closed. */
170
+ async waitForDrain(pacing) {
171
+ for (;;) {
172
+ if (!pacing.isOpen())
173
+ return false;
174
+ const queued = pacing.bufferedAmount();
175
+ if (queued === undefined || queued <= this.lowWaterBytes)
176
+ return true;
177
+ const { promise, resolve } = Promise.withResolvers();
178
+ setTimeout(resolve, this.drainPollMs);
179
+ await promise;
180
+ }
181
+ }
108
182
  /** Binary frame handler for upload streams (Begin → Chunk* → End). Frames are serialized per
109
- * stream so an in-flight `Begin` (open) completes before any `Chunk` writes. */
183
+ * stream so an in-flight `Begin` (open) completes before any `Chunk` writes. A frame is applied
184
+ * only if it comes from the session that opened the stream. */
110
185
  binaryHandler() {
111
- return (_session, bytes) => {
186
+ return (session, bytes) => {
112
187
  const frame = tryDecodeFileTransferFrame(bytes);
113
188
  if (!frame)
114
189
  return;
115
190
  const upload = this.uploads.get(frame.stream);
116
191
  if (!upload)
117
192
  return; // unknown/closed stream
118
- upload.chain = upload.chain.then(() => this.handleUploadFrame(frame));
193
+ if (upload.sessionId !== session.id)
194
+ return; // not this session's stream
195
+ upload.chain = upload.chain.then(() => this.handleUploadFrame(session, upload, frame));
119
196
  };
120
197
  }
121
- async handleUploadFrame(frame) {
122
- const upload = this.uploads.get(frame.stream);
123
- if (!upload)
124
- return; // unknown/closed stream
125
- switch (frame.opcode) {
126
- case "Begin": {
127
- if (frame.meta.transferId !== upload.transferId)
128
- return; // mismatched transfer
129
- await mkdir(dirname(upload.targetPath), { recursive: true });
130
- upload.handle = await open(upload.targetPath, "w");
131
- return;
132
- }
133
- case "Chunk": {
134
- if (!upload.handle)
198
+ /**
199
+ * Release everything a session left open: its pending uploads lose their stream id and their file
200
+ * handle is closed once frames already in flight finish. Nothing is sent (the session is gone).
201
+ */
202
+ disposeSession(session) {
203
+ for (const [stream, upload] of this.uploads) {
204
+ if (upload.sessionId !== session.id)
205
+ continue;
206
+ this.uploads.delete(stream);
207
+ upload.done = true;
208
+ upload.chain = upload.chain.then(() => upload.handle?.close().catch(() => { }));
209
+ }
210
+ }
211
+ async handleUploadFrame(session, upload, frame) {
212
+ if (upload.done)
213
+ return; // released while this frame was queued
214
+ let stage = "write";
215
+ try {
216
+ switch (frame.opcode) {
217
+ case "Begin": {
218
+ if (frame.meta.transferId !== upload.transferId)
219
+ return; // mismatched transfer
220
+ stage = "mkdir";
221
+ await mkdir(dirname(upload.targetPath), { recursive: true });
222
+ stage = "open";
223
+ upload.handle = await open(upload.targetPath, "w");
135
224
  return;
136
- await upload.handle.write(Buffer.from(frame.data));
137
- upload.bytesWritten += frame.data.length;
138
- return;
139
- }
140
- case "End": {
141
- await upload.handle?.close();
142
- this.uploads.delete(frame.stream);
143
- return;
144
- }
145
- case "Error": {
146
- await upload.handle?.close();
147
- this.uploads.delete(frame.stream);
148
- return;
225
+ }
226
+ case "Chunk": {
227
+ if (!upload.handle)
228
+ return;
229
+ await upload.handle.write(Buffer.from(frame.data));
230
+ upload.bytesWritten += frame.data.length;
231
+ return;
232
+ }
233
+ case "End": {
234
+ if (!upload.handle)
235
+ return this.finishUpload(session, frame.stream, upload, "no_begin");
236
+ stage = "close";
237
+ const handle = upload.handle;
238
+ upload.handle = null;
239
+ await handle.close();
240
+ return this.finishUpload(session, frame.stream, upload);
241
+ }
242
+ case "Error": {
243
+ await upload.handle?.close();
244
+ upload.handle = null;
245
+ return this.finishUpload(session, frame.stream, upload, frame.message || "client_error");
246
+ }
149
247
  }
150
248
  }
249
+ catch (err) {
250
+ // A failed Begin/Chunk/End: report it, free the stream, and leave whatever was written on
251
+ // disk (deleting a partial file is a separate decision, see the spec).
252
+ await upload.handle?.close().catch(() => { });
253
+ upload.handle = null;
254
+ this.finishUpload(session, frame.stream, upload, failureText(stage, err));
255
+ }
256
+ }
257
+ /** Release the stream; push `file_upload_complete` if the client asked for it. */
258
+ finishUpload(session, stream, upload, error) {
259
+ if (upload.done)
260
+ return;
261
+ upload.done = true;
262
+ if (this.uploads.get(stream) === upload)
263
+ this.uploads.delete(stream);
264
+ if (!upload.ack || !session.isOpen)
265
+ return;
266
+ const message = {
267
+ type: "file_upload_complete",
268
+ transferId: upload.transferId,
269
+ stream,
270
+ ok: error === undefined,
271
+ bytesWritten: upload.bytesWritten,
272
+ ...(error === undefined ? {} : { error }),
273
+ };
274
+ session.send({ type: "session", message });
151
275
  }
152
276
  }
153
277
  //# sourceMappingURL=file-transfer.js.map
@@ -19,6 +19,7 @@ function toClientInfo(session) {
19
19
  return {
20
20
  clientId: session.clientId,
21
21
  clientType: session.clientType,
22
+ ...(session.platform !== undefined ? { platform: session.platform } : {}),
22
23
  ...(session.appVersion !== undefined ? { appVersion: session.appVersion } : {}),
23
24
  connectedAt: session.connectedAt,
24
25
  ...(session.remoteAddress !== undefined ? { remoteAddress: session.remoteAddress } : {}),
@@ -17,6 +17,8 @@ export interface TestClient {
17
17
  ws: WebSocket;
18
18
  /** Every top-level frame received so far, in arrival order (the handshake `status` first). */
19
19
  frames: WireFrame[];
20
+ /** Every binary frame received so far (file-transfer / terminal streams), in arrival order. */
21
+ binaryFrames: Uint8Array[];
20
22
  /** The handshake `status` frame. */
21
23
  status: WireFrame;
22
24
  /** Sends a raw top-level frame as JSON. */
@@ -22,9 +22,14 @@ export async function connectTestClient(port, options = {}) {
22
22
  const ws = new WebSocket(`ws://127.0.0.1:${port}`);
23
23
  const frames = [];
24
24
  const replies = new Map();
25
+ const binaryFrames = [];
25
26
  const handshake = Promise.withResolvers();
26
27
  ws.once("error", handshake.reject);
27
- ws.on("message", (data) => {
28
+ ws.on("message", (data, isBinary) => {
29
+ if (isBinary) {
30
+ binaryFrames.push(new Uint8Array(data));
31
+ return;
32
+ }
28
33
  const frame = JSON.parse(data.toString("utf8"));
29
34
  frames.push(frame);
30
35
  const requestId = messageOf(frame).requestId;
@@ -73,6 +78,7 @@ export async function connectTestClient(port, options = {}) {
73
78
  return {
74
79
  ws,
75
80
  frames,
81
+ binaryFrames,
76
82
  status,
77
83
  send: (frame) => ws.send(JSON.stringify(frame)),
78
84
  rpcFrame,
@@ -1,4 +1,8 @@
1
+ import { mkdtemp, rm, writeFile } from "node:fs/promises";
2
+ import { tmpdir } from "node:os";
3
+ import { join } from "node:path";
1
4
  import { PassThrough } from "node:stream";
5
+ import { encodeFileTransferFrame } from "@av-pi-studio/protocol";
2
6
  import { MOCK_REBIND_ENTRY_ID } from "../agent/providers/mock/mock-provider.js";
3
7
  import { LogTap } from "../logging/log-tap.js";
4
8
  import { createLogger } from "../logging/logger.js";
@@ -70,6 +74,17 @@ export function variantKey(frame) {
70
74
  case "interrupt_response":
71
75
  case "agent_ui_list_response":
72
76
  case "rpc_error":
77
+ case "file_download_token_response":
78
+ case "file_download_response":
79
+ case "file_upload_response":
80
+ case "file_upload_complete":
81
+ case "create_terminal_response":
82
+ case "subscribe_terminal_response":
83
+ case "list_terminals_response":
84
+ case "rename_terminal_response":
85
+ case "capture_terminal_response":
86
+ case "kill_terminal_response":
87
+ case "terminals_update":
73
88
  return type;
74
89
  default:
75
90
  return undefined;
@@ -86,6 +101,81 @@ const isType = (type, extra = () => true) => (frame) => {
86
101
  const m = messageOf(frame);
87
102
  return m.type === type && extra(m);
88
103
  };
104
+ /** Text of the file the scenario downloads; the fixtures only pin its shape, never its bytes. */
105
+ const SCENARIO_DOWNLOAD_TEXT = "synthetic fixture download body\n";
106
+ /** `Begin → Chunk → End` upload frames (client → daemon) for `stream`, with fake literal content. */
107
+ function uploadFrames(stream, transferId) {
108
+ return [
109
+ encodeFileTransferFrame({ opcode: "Begin", stream, meta: { transferId, fileName: "up.txt" } }),
110
+ encodeFileTransferFrame({
111
+ opcode: "Chunk",
112
+ stream,
113
+ data: new TextEncoder().encode("synthetic fixture upload body\n"),
114
+ }),
115
+ encodeFileTransferFrame({ opcode: "End", stream, ok: true }),
116
+ ];
117
+ }
118
+ /**
119
+ * File transfer, all inside a temp dir: token → download of a small file; upload with `ack: true`
120
+ * driven as a client (Begin/Chunk/End), then the `file_upload_complete` push.
121
+ */
122
+ async function runFileTransferSteps(client) {
123
+ const dir = await mkdtemp(join(tmpdir(), "pi-studio-fixture-"));
124
+ try {
125
+ const downloadPath = join(dir, "download.txt");
126
+ await writeFile(downloadPath, SCENARIO_DOWNLOAD_TEXT);
127
+ const tokenResponse = await client.rpc("file_download_token_request", { path: downloadPath });
128
+ await client.rpc("file_download_request", { token: String(tokenResponse.token) });
129
+ const transferId = "scenario-upload";
130
+ const uploadPath = join(dir, "upload.txt");
131
+ const upload = await client.rpc("file_upload_request", {
132
+ path: uploadPath,
133
+ transferId,
134
+ ack: true,
135
+ });
136
+ for (const frame of uploadFrames(Number(upload.stream), transferId))
137
+ client.ws.send(frame);
138
+ await client.waitFor(isType("file_upload_complete"));
139
+ }
140
+ finally {
141
+ await rm(dir, { recursive: true, force: true });
142
+ }
143
+ }
144
+ /**
145
+ * Terminal control RPCs against one real PTY running a plain `/bin/sh` (never the user's shell or
146
+ * its rc files). The terminal is always killed, even when a step fails.
147
+ */
148
+ async function runTerminalSteps(client) {
149
+ const dir = await mkdtemp(join(tmpdir(), "pi-studio-fixture-"));
150
+ let slot;
151
+ try {
152
+ const created = await client.rpc("create_terminal_request", {
153
+ workspaceId: "workspace-1",
154
+ cwd: dir,
155
+ shell: "/bin/sh",
156
+ name: "terminal-1",
157
+ cols: 80,
158
+ rows: 24,
159
+ });
160
+ const terminal = created.terminal;
161
+ if (typeof terminal !== "object" || terminal === null || !("slot" in terminal)) {
162
+ throw new Error("create_terminal_response carries no terminal slot");
163
+ }
164
+ slot = Number(terminal.slot);
165
+ await client.waitFor(isType("terminals_update"));
166
+ await client.rpc("subscribe_terminal_request", { slot, cols: 80, rows: 24 });
167
+ await client.rpc("list_terminals_request");
168
+ await client.rpc("rename_terminal_request", { slot, name: "scenario-renamed" });
169
+ await client.rpc("capture_terminal_request", { slot });
170
+ await client.rpc("kill_terminal_request", { slot });
171
+ slot = undefined;
172
+ }
173
+ finally {
174
+ if (slot !== undefined)
175
+ await client.rpc("kill_terminal_request", { slot });
176
+ await rm(dir, { recursive: true, force: true });
177
+ }
178
+ }
89
179
  export async function runExternalFixtureScenario(dev, client) {
90
180
  const { rpc, waitFor } = client;
91
181
  const createAgent = async (initialPrompt) => {
@@ -204,6 +294,8 @@ export async function runExternalFixtureScenario(dev, client) {
204
294
  dev.logger.info("external fixture live line");
205
295
  await waitFor(isType("daemon_log_lines"), 2000);
206
296
  await rpc("daemon_logs_unsubscribe_request");
297
+ await runFileTransferSteps(client);
298
+ await runTerminalSteps(client);
207
299
  const captured = new Map();
208
300
  for (const frame of client.frames) {
209
301
  const key = variantKey(frame);
@@ -8,6 +8,8 @@ export declare class Session {
8
8
  readonly id: string;
9
9
  readonly clientId: string;
10
10
  readonly clientType: string;
11
+ /** The hello's `platform` (e.g. `"desktop"`), verbatim when the client sent one. Informational. */
12
+ readonly platform: string | undefined;
11
13
  capabilities: Record<string, boolean>;
12
14
  /** Epoch ms of the handshake. A wall-clock fact for the connected-clients list. */
13
15
  readonly connectedAt: number;
@@ -21,6 +23,7 @@ export declare class Session {
21
23
  id: string;
22
24
  clientId: string;
23
25
  clientType: string;
26
+ platform?: string;
24
27
  capabilities: Record<string, boolean>;
25
28
  socket: WebSocket;
26
29
  connectedAt?: number;
@@ -34,6 +37,14 @@ export declare class Session {
34
37
  send(envelope: unknown): void;
35
38
  /** Send raw bytes as a binary frame (terminal/file streams). */
36
39
  sendBinary(bytes: Uint8Array): void;
40
+ /**
41
+ * Bytes queued on the socket and not yet flushed, or `undefined` when the socket cannot say (the
42
+ * relay's stand-in socket forwards each frame into an encrypted channel and has no queue to
43
+ * read). Bulk senders pace themselves on it; `undefined` means "do not pace".
44
+ */
45
+ get bufferedAmount(): number | undefined;
46
+ /** False once the socket is closing or closed. A socket with no `readyState` (relay) is open. */
47
+ get isOpen(): boolean;
37
48
  close(code?: number, reason?: string): void;
38
49
  }
39
50
  //# sourceMappingURL=session.d.ts.map
@@ -1,4 +1,6 @@
1
1
  import { supports } from "@av-pi-studio/protocol";
2
+ /** `WebSocket.OPEN` (the `ws` package's readyState for an open socket). */
3
+ const WS_OPEN = 1;
2
4
  /**
3
5
  * A per-connection session (architecture/websocket-protocol.md § Behavior). Holds the client
4
6
  * identity, the (rehydrated) capability set, and the socket. The wire boundary asks exactly one
@@ -8,6 +10,8 @@ export class Session {
8
10
  id;
9
11
  clientId;
10
12
  clientType;
13
+ /** The hello's `platform` (e.g. `"desktop"`), verbatim when the client sent one. Informational. */
14
+ platform;
11
15
  capabilities;
12
16
  /** Epoch ms of the handshake. A wall-clock fact for the connected-clients list. */
13
17
  connectedAt;
@@ -21,6 +25,7 @@ export class Session {
21
25
  this.id = opts.id;
22
26
  this.clientId = opts.clientId;
23
27
  this.clientType = opts.clientType;
28
+ this.platform = opts.platform;
24
29
  this.capabilities = opts.capabilities;
25
30
  this.connectedAt = opts.connectedAt ?? Date.now();
26
31
  this.appVersion = opts.appVersion;
@@ -40,6 +45,20 @@ export class Session {
40
45
  sendBinary(bytes) {
41
46
  this.socket.send(bytes);
42
47
  }
48
+ /**
49
+ * Bytes queued on the socket and not yet flushed, or `undefined` when the socket cannot say (the
50
+ * relay's stand-in socket forwards each frame into an encrypted channel and has no queue to
51
+ * read). Bulk senders pace themselves on it; `undefined` means "do not pace".
52
+ */
53
+ get bufferedAmount() {
54
+ const queued = this.socket.bufferedAmount;
55
+ return typeof queued === "number" ? queued : undefined;
56
+ }
57
+ /** False once the socket is closing or closed. A socket with no `readyState` (relay) is open. */
58
+ get isOpen() {
59
+ const state = this.socket.readyState;
60
+ return typeof state !== "number" || state === WS_OPEN;
61
+ }
43
62
  close(code, reason) {
44
63
  this.socket.close(code, reason);
45
64
  }
@@ -71,6 +71,7 @@ export function createWebSocketServer(httpServer, deps) {
71
71
  id: randomUUID(),
72
72
  clientId: hello.data.clientId,
73
73
  clientType: hello.data.clientType,
74
+ platform: hello.data.platform,
74
75
  capabilities,
75
76
  socket: ws,
76
77
  appVersion: hello.data.appVersion,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@av-pi-studio/server",
3
- "version": "0.0.117",
3
+ "version": "0.0.118",
4
4
  "bin": {
5
5
  "pi-studio-daemon": "dist/daemon/main.js"
6
6
  },
@@ -24,8 +24,8 @@
24
24
  "clean": "rm -rf dist *.tsbuildinfo"
25
25
  },
26
26
  "dependencies": {
27
- "@av-pi-studio/protocol": "^0.0.117",
28
- "@av-pi-studio/relay": "^0.0.117",
27
+ "@av-pi-studio/protocol": "^0.0.118",
28
+ "@av-pi-studio/relay": "^0.0.118",
29
29
  "@earendil-works/pi-coding-agent": "^1.4.0",
30
30
  "@xterm/addon-serialize": "^0.14.0",
31
31
  "@xterm/headless": "^6.0.0",