@av-pi-studio/server 0.0.117 → 0.0.119

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.
package/README.md CHANGED
@@ -41,7 +41,7 @@ A single daemon process owns all runtime state and mediates every operation:
41
41
  manages worktrees, and integrates with the GitHub API for PRs/issues.
42
42
  - **Orchestration** — chat rooms with `@mentions`, cron/interval **schedules** that fire agent
43
43
  prompts, and iterative worker+verifier **loops**.
44
- - **Files** — directory listing, text/binary file preview, and token-based chunked file download.
44
+ - **Files** — directory listing, text/binary file preview, and chunked file download by path (byte ranges, resume with `ifUnchanged`, cancel).
45
45
  - **Service proxy** — an HTTP reverse proxy that routes to localhost services started by agents.
46
46
 
47
47
  The daemon is **provider-agnostic**: the rest of the code only ever touches the `AgentClient` /
@@ -259,7 +259,8 @@ All communication rides a **single WebSocket connection** per client.
259
259
  ### Text frames — JSON envelopes discriminated by `type`
260
260
 
261
261
  - `hello` (Client→Server, first frame) — handshake with `clientId`, `clientType`
262
- (`mobile`/`browser`/`cli`/`mcp`), `protocolVersion`, optional `capabilities`.
262
+ (`mobile`/`browser`/`cli`/`mcp`), `protocolVersion`, optional `capabilities`, `platform` and `agentStreams`
263
+ (`"all"` default, or `"none"` to receive no `agent_stream` frames).
263
264
  - `status` (Server→Client) — `server_info` payload sent right after a successful hello.
264
265
  - `ping` / `pong` — **JSON** liveness (not RFC 6455 ping, which browsers/RN can't send).
265
266
  - `session` — the envelope wrapping every RPC request/response/broadcast (`{ type: "session",
@@ -274,9 +275,10 @@ are accepted via aliases but never generated.
274
275
 
275
276
  Layout: `[1-byte opcode][1-byte slot][payload]`. The `slot` (0–255) demultiplexes multiple
276
277
  terminals over the one connection. Codecs use `Uint8Array` (not Node `Buffer`) so they run
277
- unchanged in browsers and React Native. **File downloads** also ride binary frames: a client
278
- requests a token via the `file_download_token_request` RPC, then streams `Begin → Chunk* → End`
279
- frames via `file_download_request`; uploads consume the same frame format.
278
+ unchanged in browsers and React Native. **File downloads** also ride binary frames: a client sends
279
+ `file_download_request { path, offset?, length?, ifUnchanged? }`, gets a `file_download_response` (with the file's
280
+ size) first, then `Begin → Chunk* → End`; `file_download_cancel_request { stream }` stops one
281
+ (`Error` `cancelled`). Advertised as `fileDownloadRanges`. Uploads consume the same frame format.
280
282
 
281
283
  ### HTTP surface
282
284
 
@@ -388,7 +390,7 @@ src/
388
390
  terminal/ TerminalManager (PTY lifecycle, slot mux, snapshot, binary broadcast).
389
391
  projects/ Workspaces, projects, git ops, worktrees, GitHub, reconciliation.
390
392
  orchestration/ ChatService, ScheduleService, LoopService, cron.
391
- files/ File explorer + chunked download token store.
393
+ files/ File explorer + chunked download/upload transfer.
392
394
  proxy/ ServiceProxy + port registry for agent-started services.
393
395
  logging/ Pino logger factory.
394
396
  util/ Concurrency helpers.
@@ -1,6 +1,6 @@
1
1
  import type { AgentStreamEvent } from "@av-pi-studio/protocol";
2
2
  import type { Logger } from "../logging/logger.js";
3
- import type { Session } from "../ws/session.js";
3
+ import { type Session } from "../ws/session.js";
4
4
  import type { HandlerRegistry } from "../ws/router.js";
5
5
  import { AgentManager } from "./agent-manager.js";
6
6
  import type { AgentClient, AgentSession, RunOptions } from "./provider-contract.js";
@@ -1,4 +1,5 @@
1
1
  import { randomUUID } from "node:crypto";
2
+ import { agentStreamRecipients } from "../ws/session.js";
2
3
  import { AgentManager } from "./agent-manager.js";
3
4
  import { AgentTimelineStore } from "./timeline-store.js";
4
5
  import { composeSystemPrompt } from "./compose-system-prompt.js";
@@ -51,14 +52,14 @@ export function resetTimeline(agentId, rows) {
51
52
  */
52
53
  export function appendStreamEvent(agentId, event, broadcast, sessions) {
53
54
  if ((event.kind === "tool_call" && event.partial) || event.kind === "queue_update") {
54
- broadcast(sessions, {
55
+ broadcast(agentStreamRecipients(sessions), {
55
56
  type: "session",
56
57
  message: { type: "agent_stream", agentId, timestamp: new Date().toISOString(), event },
57
58
  });
58
59
  return;
59
60
  }
60
61
  const row = getOrCreateTimeline(agentId).append(event);
61
- broadcast(sessions, {
62
+ broadcast(agentStreamRecipients(sessions), {
62
63
  type: "session",
63
64
  message: {
64
65
  type: "agent_stream",
@@ -283,7 +284,7 @@ export class AgentService {
283
284
  text: prompt,
284
285
  images: opts.images,
285
286
  });
286
- this.broadcastAll(getSessions(), {
287
+ this.broadcastAll(agentStreamRecipients(getSessions()), {
287
288
  type: "session",
288
289
  message: {
289
290
  type: "agent_stream",
@@ -309,7 +310,7 @@ export class AgentService {
309
310
  text: prompt,
310
311
  images: opts.images,
311
312
  });
312
- this.broadcastAll(getSessions(), {
313
+ this.broadcastAll(agentStreamRecipients(getSessions()), {
313
314
  type: "session",
314
315
  message: {
315
316
  type: "agent_stream",
@@ -1,4 +1,4 @@
1
- import type { Session } from "../ws/session.js";
1
+ import { type Session } from "../ws/session.js";
2
2
  import type { HandlerRegistry } from "../ws/router.js";
3
3
  import type { AgentManager } from "./agent-manager.js";
4
4
  import type { AgentClient } from "./provider-contract.js";
@@ -1,4 +1,5 @@
1
1
  import { randomUUID } from "node:crypto";
2
+ import { agentStreamRecipients } from "../ws/session.js";
2
3
  import { getTimeline, spawnOrResumeSession } from "./agent-service.js";
3
4
  export class SessionOperationsService {
4
5
  deps;
@@ -72,7 +73,7 @@ export class SessionOperationsService {
72
73
  if (timeline) {
73
74
  const messageId = msg.clientMessageId ?? randomUUID();
74
75
  const row = timeline.append({ kind: "user_message", messageId, text: message, images });
75
- this.broadcastAll(getSessions(), {
76
+ this.broadcastAll(agentStreamRecipients(getSessions()), {
76
77
  type: "session",
77
78
  message: {
78
79
  type: "agent_stream",
@@ -459,9 +459,9 @@ export function startDaemon(opts) {
459
459
  broadcast,
460
460
  getActiveSessions,
461
461
  }).registerHandlers(registry, getActiveSessions);
462
- // ── Files: explorer (with download tokens) + transfer + filesystem watch ──────
462
+ // ── Files: explorer + transfer + filesystem watch ──────
463
463
  const fileTransfer = new FileTransferService();
464
- new FileExplorerService({ issueDownloadToken: fileTransfer.issueDownloadToken }).registerHandlers(registry);
464
+ new FileExplorerService().registerHandlers(registry);
465
465
  fileTransfer.registerHandlers(registry);
466
466
  const fileTransferBinary = fileTransfer.binaryHandler();
467
467
  const fileWatchService = new FileWatchService({ logger });
@@ -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,8 @@ 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,
722
+ agentStreams: hello.data.agentStreams,
719
723
  capabilities,
720
724
  appVersion: hello.data.appVersion,
721
725
  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,22 @@ 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.
269
+ //
270
+ // Same wiring as production `bootstrap.ts`: the transfer service owns the download / upload RPCs
271
+ // and the upload binary handler.
272
+ const fileTransfer = new FileTransferService();
265
273
  new FileExplorerService().registerHandlers(registry);
274
+ fileTransfer.registerHandlers(registry);
275
+ const fileTransferBinary = fileTransfer.binaryHandler();
276
+ // ── Terminals: manager + control RPCs + binary stream (same wiring as production) ──────────
277
+ const terminalManager = new TerminalManager({ logger });
278
+ registerTerminalHandlers(registry, {
279
+ manager: terminalManager,
280
+ broadcast,
281
+ restoreModesEnabled: true,
282
+ projectConfigPath: (cwd) => join(cwd, "pi-studio.json"),
283
+ }, getActiveSessions);
284
+ const terminalBinaryHandler = makeTerminalBinaryHandler(terminalManager, broadcast, getActiveSessions);
266
285
  // Simple file diff RPC for the POC UI. Untracked (brand-new) files have no git-tracked "before"
267
286
  // state, so a plain `git diff` against them is always empty — git only diffs a path once it's
268
287
  // in the index or committed. Fall back to `git diff --no-index /dev/null <path>` (exit code 1
@@ -289,8 +308,7 @@ export function startDevDaemon(opts) {
289
308
  return { type: "file_diff_response", ok: true, path: filePath, patch };
290
309
  });
291
310
  // 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
311
+ // UTF-8 text; larger files must use the chunked binary download path instead). Async so a
294
312
  // multi-MB read/decode never blocks the event loop.
295
313
  registry.register("file_read_request", async (ctx) => {
296
314
  const filePath = String(ctx.message.path ?? "");
@@ -337,12 +355,19 @@ export function startDevDaemon(opts) {
337
355
  onSessionClose: (session) => {
338
356
  daemonStatusService.disposeSession(session);
339
357
  daemonLogsService.disposeSession(session);
358
+ fileTransfer.disposeSession(session);
340
359
  },
341
360
  onMessage: (session, frame) => {
342
361
  if ("text" in frame) {
343
362
  void routeTextFrame(session, frame.text, registry);
344
363
  }
345
- // Binary (terminal) frames not wired in dev bootstrap yet.
364
+ else {
365
+ // Binary frames: try terminal (Input/Resize) then file-transfer (upload) decoders.
366
+ routeBinaryFrame(session, frame.binary, (s, bytes) => {
367
+ terminalBinaryHandler(s, bytes);
368
+ fileTransferBinary(s, bytes);
369
+ });
370
+ }
346
371
  },
347
372
  });
348
373
  // Now that the WS server exists, point the holder at its live session set.
@@ -360,6 +385,7 @@ export function startDevDaemon(opts) {
360
385
  close: async () => {
361
386
  logger.info("dev daemon shutting down");
362
387
  daemonStatusService.dispose();
388
+ terminalManager.killAll();
363
389
  daemonLogsService.dispose();
364
390
  await wsHandle.close();
365
391
  await new Promise((resolve) => httpServer.close(() => resolve()));
@@ -30,14 +30,11 @@ export type FileExplorerResult = {
30
30
  mtimeMs: number;
31
31
  mimeHint: string;
32
32
  };
33
- transferToken: string;
34
33
  } | {
35
34
  ok: false;
36
35
  error: string;
37
36
  };
38
37
  export interface FileExplorerDeps {
39
- /** Issue a download token for a binary file (task-005 supplies the real store). */
40
- issueDownloadToken?: (resolvedPath: string) => string;
41
38
  previewBytes?: number;
42
39
  }
43
40
  export declare class FileExplorerService {
@@ -341,14 +341,12 @@ export class FileExplorerService {
341
341
  if (sniffLen > 0)
342
342
  await handle.read(sniff, 0, sniffLen, 0);
343
343
  if (isBinary(sniff)) {
344
- const transferToken = this.deps.issueDownloadToken?.(resolvedPath) ?? randomUUID();
345
344
  return {
346
345
  ok: true,
347
346
  kind: "binary",
348
347
  path: inputPath,
349
348
  resolvedPath,
350
349
  metadata: { size, mtimeMs, mimeHint: mimeHintForFile(resolvedPath) },
351
- transferToken,
352
350
  };
353
351
  }
354
352
  const readLen = Math.min(size, previewBytes);
@@ -1,35 +1,99 @@
1
+ import type { Session } from "../ws/session.js";
1
2
  import type { BinaryHandler, HandlerRegistry } from "../ws/router.js";
2
- import { DownloadTokenStore } from "./download-token-store.js";
3
+ /**
4
+ * A download stops reading from disk while this many bytes are queued on the session's socket (32
5
+ * default chunks) and resumes below the low mark. Chosen, not measured: big enough that the read
6
+ * never starves a fast LAN link between polls, small enough that a stalled client costs the daemon
7
+ * about a megabyte instead of the whole file. Injectable through `FileTransferDeps`.
8
+ */
9
+ export declare const DOWNLOAD_HIGH_WATER_BYTES: number;
10
+ export declare const DOWNLOAD_LOW_WATER_BYTES: number;
3
11
  export interface FileTransferDeps {
4
- tokenStore?: DownloadTokenStore;
5
12
  chunkBytes?: number;
13
+ highWaterBytes?: number;
14
+ lowWaterBytes?: number;
15
+ /** How often a paused download re-reads the socket's queue. */
16
+ drainPollMs?: number;
17
+ }
18
+ /** What a download needs to know about the socket it writes to. Absent means "do not pace". */
19
+ export interface DownloadPacing {
20
+ /** Bytes queued and not yet flushed; `undefined` when the socket cannot say. */
21
+ bufferedAmount(): number | undefined;
22
+ /** False once the socket is closing or closed: the transfer ends without further frames. */
23
+ isOpen(): boolean;
6
24
  }
7
25
  export declare class FileTransferService {
8
- readonly tokenStore: DownloadTokenStore;
9
26
  private readonly chunkBytes;
27
+ private readonly highWaterBytes;
28
+ private readonly lowWaterBytes;
29
+ private readonly drainPollMs;
10
30
  /** Pending uploads keyed by stream id. */
11
31
  private readonly uploads;
12
32
  /** Rotating hand-out point in the one-byte stream id space (see `nextFreeSlot`). */
13
33
  private streamCursor;
34
+ /** Accepted downloads by session id, then stream id: download ids are scoped to the session. */
35
+ private readonly downloads;
36
+ /** Rotating hand-out point for a download the client did not number itself. */
37
+ private downloadCursor;
14
38
  constructor(deps?: FileTransferDeps);
15
- /** Issue a download token for a resolved path (also used by the file explorer for binary files). */
16
- issueDownloadToken: (resolvedPath: string) => string;
17
- registerHandlers(registry: HandlerRegistry): void;
18
- /** Hand out the next stream id for a transfer this service does not track (a download the
19
- * client didn't number itself). Rotates through the one-byte space instead of counting past
20
- * 255, which `encodeFileTransferFrame` rejects outright. */
21
- private takeStream;
22
39
  /**
23
- * Validate + consume the token, then stream the file as `Begin → Chunk* → End` binary frames.
40
+ * Answer a `file_download_request` from session `sessionId`. `response` is the
41
+ * `file_download_response` to send; `run` is present only when the download was accepted, and
42
+ * streams the file once called (after the response has gone out). The caller must call `run`
43
+ * exactly once: it owns the open file.
24
44
  */
25
- startDownload(token: string, stream: number, sink: (frame: Uint8Array) => void): Promise<{
26
- ok: boolean;
27
- error?: string;
28
- transferId?: string;
45
+ beginDownload(sessionId: string, message: Record<string, unknown>): Promise<{
46
+ response: Record<string, unknown>;
47
+ run?: (sink: (frame: Uint8Array) => void, pacing: DownloadPacing) => Promise<void>;
29
48
  }>;
49
+ /**
50
+ * Stop `sessionId`'s download on `stream`: it sends `Error` `cancelled` and reads no further.
51
+ * False when that session has no download on `stream` (never started, or already finished).
52
+ */
53
+ cancelDownload(sessionId: string, stream: number): boolean;
54
+ registerHandlers(registry: HandlerRegistry): void;
55
+ /**
56
+ * Validate a download request, reserve its stream id on the session and open its file. Nothing is
57
+ * sent: the caller answers first and then calls `streamDownload`, which owns (and closes) the
58
+ * returned handle and releases the reservation.
59
+ *
60
+ * `offset` defaults to 0 and `length` to "to the end of the file"; `length` is clamped to it. An
61
+ * `offset` equal to the size is a legal empty range, one beyond it is `range_not_satisfiable`.
62
+ * `ifUnchanged` that does not equal the file's current size and modification time (a malformed
63
+ * one never does) is `changed`.
64
+ */
65
+ private openDownload;
66
+ private openFile;
67
+ /** Forget a finished or rejected download. A no-op once the session's downloads were dropped. */
68
+ private release;
69
+ private releaseSession;
70
+ /**
71
+ * Stream an opened download as `Begin → Chunk* → End` binary frames, then close its file.
72
+ *
73
+ * The disk read pauses while the socket's queue is above the high-water mark, so a client that
74
+ * reads slowly costs the daemon about that much memory, not the whole file. A read error, or a
75
+ * file that ended before the announced length, sends one `Error` frame and no `End`; a socket
76
+ * that closed mid-transfer ends it silently. Never rejects: it runs detached from the request.
77
+ */
78
+ private streamDownload;
79
+ private pipeRange;
80
+ /**
81
+ * Resolves `true` once the socket's queue is at or below the low-water mark; `false` if it closed
82
+ * or the download ended (`ended`) while waiting.
83
+ */
84
+ private waitForDrain;
30
85
  /** 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. */
86
+ * stream so an in-flight `Begin` (open) completes before any `Chunk` writes. A frame is applied
87
+ * only if it comes from the session that opened the stream. */
32
88
  binaryHandler(): BinaryHandler;
89
+ /**
90
+ * Release everything a session left open: its pending uploads lose their stream id and their file
91
+ * handle is closed once frames already in flight finish; its downloads stop reading and lose
92
+ * their stream id and file handle. Nothing is sent (the session is gone).
93
+ */
94
+ disposeSession(session: Session): void;
33
95
  private handleUploadFrame;
96
+ /** Release the stream; push `file_upload_complete` if the client asked for it. */
97
+ private finishUpload;
34
98
  }
35
99
  //# sourceMappingURL=file-transfer.d.ts.map