@av-pi-studio/client 0.0.117 → 0.0.119

package/README.md

@@ -92,6 +92,7 @@ interface DaemonClientOptions {
   protocolVersion?: number;              // defaults to the current protocol version
   appVersion?: string;
   capabilities?: Record<string, boolean>; // CLIENT_CAPS flags to advertise in `hello`
+  agentStreams?: "all" | "none";          // "none": the daemon sends no `agent_stream` frames (0.0.119+)
   transport?: Transport;                  // inject a stub for tests; defaults to native WebSocket
   rpcTimeoutMs?: number;                  // per-request timeout; never tears down the socket
   now?: () => number;                     // inject a clock for deterministic tests

package/dist/daemon-client.d.ts

@@ -21,6 +21,19 @@ export interface DaemonClientOptions {
     url: string;
     clientId: string;
     clientType: ClientType;
+    /**
+     * Free-form platform label sent as `hello.platform` when set (the desktop app sends `"desktop"`
+     * with `clientType: "browser"`). Informational; daemons that predate the field ignore it.
+     */
+    platform?: string;
+    /**
+     * `"none"` opens a quiet connection: the daemon (feature `agentStreamsMode`) sends it no
+     * `agent_stream` frame, so no `timeline.subscribe` listener ever fires; `agent_update`,
+     * `agent_ui_*` and everything else still arrive. Sent as `hello.agentStreams` only when set.
+     * Against a daemon without `agentStreamsMode` the field is ignored and every stream arrives, so
+     * a consumer must tolerate them. Fixed for the connection; reconnect to change it.
+     */
+    agentStreams?: "all" | "none";
     protocolVersion?: number;
     appVersion?: string;
     capabilities?: Record<string, boolean>;
@@ -67,6 +80,8 @@ export declare class DaemonClient {
     get serverId(): string | null;
     get features(): Record<string, unknown>;
     get serverCapabilities(): Record<string, unknown>;
+    /** The transport's unsent byte count, or `undefined` when the transport cannot report one. */
+    get bufferedAmount(): number | undefined;
     /** True iff the daemon advertised the given `server_info.features.*` flag truthy. */
     hasFeature(flag: string): boolean;
     /**

package/dist/daemon-client.js

@@ -70,6 +70,10 @@ export class DaemonClient {
     get serverCapabilities() {
         return this._serverCapabilities;
     }
+    /** The transport's unsent byte count, or `undefined` when the transport cannot report one. */
+    get bufferedAmount() {
+        return this.transport.bufferedAmount;
+    }
     /** True iff the daemon advertised the given `server_info.features.*` flag truthy. */
     hasFeature(flag) {
         return Boolean(this._features[flag]);
@@ -90,6 +94,8 @@ export class DaemonClient {
             type: "hello",
             clientId: this.options.clientId,
             clientType: this.options.clientType,
+            platform: this.options.platform,
+            agentStreams: this.options.agentStreams,
             protocolVersion: this.options.protocolVersion ?? PROTOCOL_VERSION,
             appVersion: this.options.appVersion,
             capabilities: this.options.capabilities,
@@ -227,8 +233,7 @@ export class DaemonClient {
      */
     handleBinaryFrame(bytes) {
         const opcodeByte = bytes[0];
-        const isFileTransfer = opcodeByte !== undefined &&
-            Object.values(FileTransferOpcode).includes(opcodeByte);
+        const isFileTransfer = opcodeByte !== undefined && Object.values(FileTransferOpcode).includes(opcodeByte);
         if (isFileTransfer) {
             const frame = tryDecodeFileTransferFrame(bytes);
             if (!frame)

package/dist/file-transfer-client.d.ts

@@ -1,8 +1,56 @@
 import { type DaemonClient } from "./daemon-client.js";
-export interface DownloadedFile {
-    bytes: Uint8Array;
+/**
+ * Upload pacing: `upload` waits before each chunk while the transport reports more than this many
+ * unsent bytes, so the socket queue stays within this plus one chunk. 1 MiB (32 chunks) is a
+ * chosen value, not a measured one — big enough to keep a fast link busy across a poll interval,
+ * small enough that a stalled link holds little memory and a cancel takes effect quickly.
+ */
+export declare const UPLOAD_HIGH_WATER_BYTES: number;
+/** What `FileTransferClient.upload` can stream from. */
+export type UploadSource = Uint8Array | Blob | AsyncIterable<Uint8Array>;
+export interface UploadOptions {
+    /** Called after each chunk is queued; `sent` is cumulative, `total` is unknown (`undefined`) for an async iterable. */
+    onProgress?(sent: number, total?: number): void;
+    /** Aborting sends an `Error` frame for the stream and rejects `upload` with an `AbortError`. */
+    signal?: AbortSignal;
+}
+export interface FileTransferClientOptions {
+    /** Override {@link UPLOAD_HIGH_WATER_BYTES} (tests). */
+    highWaterBytes?: number;
+    /** Override the pacing timer (tests); resolves after `ms`. */
+    sleep?(ms: number): Promise<void>;
+}
+/** What a download reports besides its bytes, as announced by the daemon's `Begin` frame. */
+export interface DownloadResult {
     fileName?: string;
     mimeType?: string;
+    /** The whole file's size when the transfer began — not the range's. */
+    totalBytes: number;
+    /** The file's modification time (ms) when the transfer began. */
+    mtimeMs: number;
+    /** First byte of the range, as served. */
+    offset: number;
+    /** Bytes in the range, as served (clamped to the end of the file). */
+    length: number;
+}
+/** `FileTransferClient.download`'s result: the range's bytes plus {@link DownloadResult}. */
+export interface DownloadedFile extends DownloadResult {
+    bytes: Uint8Array;
+}
+export interface DownloadOptions {
+    /** First byte to read; default 0. */
+    offset?: number;
+    /** Bytes to read from `offset`; default (and cap) is to the end of the file. */
+    length?: number;
+    /** Refuse (`changed`) unless the file still has this size and modification time. */
+    ifUnchanged?: {
+        size: number;
+        mtimeMs: number;
+    };
+    /** Aborting sends a cancel request for the stream and rejects with an `AbortError`. */
+    signal?: AbortSignal;
+    /** After each chunk: bytes received so far in this range, and the range's length. */
+    onProgress?(received: number, length: number): void;
 }
 export declare class FileTransferClient {
     private readonly daemon;
@@ -10,31 +58,97 @@ export declare class FileTransferClient {
     /** Rotating hand-out point in the one-byte stream id space — ids are a pool, not a counter. */
     private streamCursor;
     private detach;
-    constructor(daemon: DaemonClient);
+    /** Present only while a download is pending: rejects them when the connection leaves `open`. */
+    private detachState;
+    private readonly uploads;
+    private readonly highWaterBytes;
+    private readonly sleep;
+    constructor(daemon: DaemonClient, options?: FileTransferClientOptions);
+    /** Uploads that have not settled yet (0 once every upload has resolved, rejected, or been aborted). */
+    get pendingUploads(): number;
+    /**
+     * Downloads still holding a stream id: in flight, or aborted and waiting for the daemon's last
+     * frame. 0 once every download has finished and the daemon is done with its stream.
+     */
+    get pendingDownloads(): number;
     /** Begin routing inbound file-transfer frames. Idempotent. */
     start(): void;
-    /** Stop routing inbound frames. Any downloads still pending are rejected. */
+    /** Stop routing inbound frames. Any downloads and uploads still pending are rejected. */
     stop(): void;
     /**
-     * Download the file at `path`: requests a single-use token, then requests the chunked
-     * transfer, assembling `Begin → Chunk* → End` frames into one buffer.
+     * Download a byte range of the file at `path` into `sink`, which is called once per `Chunk` in
+     * wire order. The client keeps no reference to a chunk after the call, so memory stays at about
+     * one chunk however large the range is. With no `offset`/`length` the whole file is requested.
+     *
+     * - **`sink` is synchronous.** Frames are handled in arrival order on the transport's delivery
+     *   path, so the sink cannot make the daemon wait. A consumer that must wait (writing to disk)
+     *   has to buffer, or pace itself by asking for ranges one after the other. A sink (or
+     *   `onProgress`) that throws aborts the download: the daemon is told to stop and this rejects
+     *   with that error.
+     * - **Resolves** after `End` with the range's metadata, taken from the `Begin` frame:
+     *   `{ fileName?, mimeType?, totalBytes, mtimeMs, offset, length }`. `totalBytes`/`mtimeMs`
+     *   describe the whole file when the transfer began; keep them to resume with `ifUnchanged`.
+     * - **`onProgress(received, length)`** fires after every chunk with the bytes received so far in
+     *   this range (monotonic) and the range length; it ends at `length`.
+     * - **Rejects** with the daemon's error code when the request is refused (`not_found`,
+     *   `changed`, `stream_in_use`, …), with the `Error` frame's message (`read_failed`, `changed`,
+     *   `cancelled`) when the transfer fails midway, and when the connection closes or {@link stop}
+     *   is called. It rejects before sending anything when the daemon did not advertise
+     *   `fileDownloadRanges`.
+     * - **Abort.** `signal` aborting rejects with an `AbortError` and sends
+     *   `file_download_cancel_request { stream }`. The stream id is held until the daemon has said
+     *   nothing more will arrive on it (a terminal frame, or a refusal), so a late frame can never
+     *   reach a later download that reuses the id; frames that do arrive meanwhile are ignored.
      *
-     * Retries exactly once on an expired token. The daemon's TTL runs from the moment it ISSUES a
-     * token, but the token only becomes usable once its response reaches us — queued behind every
-     * `Chunk` frame already in flight on this one socket. A large transfer ahead of it can hand us
-     * a token that is dead on arrival (relay makes this routine: base64-inflated frames, extra
-     * hop). By the time we see the rejection that backlog has drained, so a second attempt lands on
-     * a quiet socket; looping further would only spin on a genuinely broken link.
+     * The stream id is registered BEFORE the request is sent: the daemon answers first and streams
+     * right after, and a frame for an unregistered id would be dropped.
+     */
+    downloadTo(path: string, sink: (chunk: Uint8Array) => void, options?: DownloadOptions): Promise<DownloadResult>;
+    /**
+     * Download the file at `path` (or the range in `options`) into one buffer: {@link downloadTo}
+     * collecting the chunks. Prefer `downloadTo` for anything large.
      */
-    download(path: string): Promise<DownloadedFile>;
-    private attemptDownload;
+    download(path: string, options?: DownloadOptions): Promise<DownloadedFile>;
+    /** Settle a download for its caller, once. The stream id is released separately. */
+    private finish;
+    /** Give a download's stream id back — only if it still belongs to `entry`. */
+    private release;
     /**
-     * Upload `bytes` to `path` on the daemon: requests an upload stream, then pushes
+     * Reject a download now and tell the daemon to stop it. The id stays claimed until the daemon
+     * has nothing more to send on it: a terminal frame (see `dispatch`), a refused request, or a
+     * `not_found` cancel (nothing active — whatever it sent is already behind us on the socket).
+     */
+    private abortDownload;
+    /** Reject every download and free every id (stop, or the connection is gone). */
+    private failDownloads;
+    /** Watch the connection only while a download is pending, so an idle client holds no listener. */
+    private watchConnection;
+    private unwatchConnection;
+    /**
+     * Upload `source` to `path` on the daemon: requests an upload stream, then pushes
      * `Begin → Chunk* → End` binary frames the server writes to disk (creating parent dirs,
      * overwriting any existing file). The server keys the transfer by `transferId`, which the
-     * `Begin` frame must echo. Resolves once every frame is flushed to the socket.
+     * `Begin` frame must echo.
+     *
+     * - **Streaming.** A `Blob` is sliced and read chunk by chunk and an async iterable is pulled one
+     *   item at a time, so memory stays at about one chunk (plus the pacing window) regardless of the
+     *   file size. `total` in `onProgress` is the byte length for a `Uint8Array`/`Blob` and
+     *   `undefined` for an async iterable.
+     * - **Pacing.** Before each chunk it waits while `transport.bufferedAmount` is above
+     *   {@link UPLOAD_HIGH_WATER_BYTES}; a transport that does not report it is never congested.
+     * - **Completion.** With the daemon's `fileTransferAck` feature it resolves when the matching
+     *   `file_upload_complete` push arrives and rejects with the daemon's error when `ok` is false;
+     *   there is no timeout on that wait. Without it, it resolves once the transport's buffer has
+     *   drained after `End` (the bytes have left this machine, not necessarily reached the disk).
+     * - **Cancel.** `signal` aborting sends an `Error` frame for the stream (so the daemon frees it)
+     *   and rejects with an `AbortError`. A dropped connection or {@link stop} rejects too.
+     *   Whatever way it ends, no listener or stream is left behind.
      */
-    upload(path: string, bytes: Uint8Array): Promise<void>;
+    upload(path: string, source: UploadSource, options?: UploadOptions): Promise<void>;
+    /** Poll `condition` on a timer until it clears, giving up as soon as the upload has failed. */
+    private waitWhile;
+    /** Best-effort `Error` frame for an upload stream; a dead connection has nothing to tell. */
+    private sendUploadError;
     private dispatch;
 }
 //# sourceMappingURL=file-transfer-client.d.ts.map

package/dist/file-transfer-client.js

@@ -1,17 +1,104 @@
 import { encodeFileTransferFrame, nextFreeSlot, SLOT_SPACE, } from "@av-pi-studio/protocol";
 import { randomId } from "./daemon-client.js";
 /**
- * Client-side demux + assembly for binary file downloads plus chunked uploads
+ * Client-side demux for binary file downloads plus chunked uploads
  * (features/file-explorer-transfer.md § Binary transfer frames). Mirrors `TerminalStreamRouter`'s
  * inbound-frame-routing shape, but a download is a one-shot request/response rather than a
- * persistent per-slot subscription: request a token, request the download, await the assembled
- * bytes. An upload is the inverse: request an upload stream, then push `Begin → Chunk* → End`
- * binary frames the server writes to the target path.
+ * persistent per-slot subscription: request the download by path (and optional byte range), then
+ * hand the `Begin → Chunk* → End` frames that follow to a sink or collect them. An upload is the
+ * inverse: request an upload stream, then push `Begin → Chunk* → End` binary frames the server
+ * writes to the target path.
  */
 /** Matches the server's default chunk size (`FileTransferService` DEFAULT_CHUNK_BYTES). */
 const UPLOAD_CHUNK_BYTES = 32 * 1024;
-/** The daemon's `startDownload` rejection when a token is unknown, spent, or past its TTL. */
-const EXPIRED_TOKEN = "invalid_or_expired_token";
+/**
+ * Upload pacing: `upload` waits before each chunk while the transport reports more than this many
+ * unsent bytes, so the socket queue stays within this plus one chunk. 1 MiB (32 chunks) is a
+ * chosen value, not a measured one — big enough to keep a fast link busy across a poll interval,
+ * small enough that a stalled link holds little memory and a cancel takes effect quickly.
+ */
+export const UPLOAD_HIGH_WATER_BYTES = 1024 * 1024;
+/** How often `upload` re-reads the transport's buffered amount while it is congested. */
+const UPLOAD_POLL_MS = 10;
+/** The message of the rejection when the daemon predates ranged downloads. */
+const RANGES_UNSUPPORTED = "This daemon does not support file downloads by path and range (feature fileDownloadRanges): update the daemon.";
+function createRun() {
+    // `new Promise`, not `Promise.withResolvers`: this SDK ships to browsers and React Native
+    // runtimes older than ES2024 (and compiles with `lib: ES2023`).
+    let reject;
+    const promise = new Promise((_, rej) => {
+        reject = rej;
+    });
+    promise.catch(() => { }); // only ever raced: never an unhandled rejection
+    let failed;
+    return {
+        failure: promise,
+        fail(error) {
+            if (failed)
+                return;
+            failed = error;
+            reject(error);
+        },
+        check() {
+            if (failed)
+                throw failed;
+        },
+    };
+}
+function abortError(what) {
+    return new DOMException(`The ${what} was aborted`, "AbortError");
+}
+function asError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}
+/** `Begin`'s range metadata, or null when the daemon left a field out. */
+function downloadResult(meta) {
+    const { fileName, mimeType, totalBytes, mtimeMs, offset, length } = meta;
+    if (totalBytes === undefined ||
+        mtimeMs === undefined ||
+        offset === undefined ||
+        length === undefined) {
+        return null;
+    }
+    return {
+        ...(fileName === undefined ? {} : { fileName }),
+        ...(mimeType === undefined ? {} : { mimeType }),
+        totalBytes,
+        mtimeMs,
+        offset,
+        length,
+    };
+}
+function isAbortError(error) {
+    return error instanceof Error && error.name === "AbortError";
+}
+function defaultSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function* sliceBytes(bytes) {
+    for (let offset = 0; offset < bytes.length; offset += UPLOAD_CHUNK_BYTES) {
+        yield bytes.subarray(offset, offset + UPLOAD_CHUNK_BYTES);
+    }
+}
+/** Reads one chunk at a time — the whole file is never in memory. */
+async function* sliceBlob(blob) {
+    for (let offset = 0; offset < blob.size; offset += UPLOAD_CHUNK_BYTES) {
+        yield new Uint8Array(await blob.slice(offset, offset + UPLOAD_CHUNK_BYTES).arrayBuffer());
+    }
+}
+/** Re-cuts whatever the iterable yields into chunks of at most `UPLOAD_CHUNK_BYTES`. */
+async function* splitItems(items) {
+    for await (const item of items)
+        yield* sliceBytes(item);
+}
+function uploadChunks(source) {
+    if (source instanceof Uint8Array)
+        return { total: source.length, chunks: sliceBytes(source) };
+    if (typeof Blob !== "undefined" && source instanceof Blob) {
+        return { total: source.size, chunks: sliceBlob(source) };
+    }
+    return { total: undefined, chunks: splitItems(source) };
+}
 function concat(chunks) {
     const total = chunks.reduce((sum, c) => sum + c.length, 0);
     const out = new Uint8Array(total);
@@ -28,8 +115,26 @@ export class FileTransferClient {
     /** Rotating hand-out point in the one-byte stream id space — ids are a pool, not a counter. */
     streamCursor = 1;
     detach = null;
-    constructor(daemon) {
+    /** Present only while a download is pending: rejects them when the connection leaves `open`. */
+    detachState = null;
+    uploads = new Set();
+    highWaterBytes;
+    sleep;
+    constructor(daemon, options = {}) {
         this.daemon = daemon;
+        this.highWaterBytes = options.highWaterBytes ?? UPLOAD_HIGH_WATER_BYTES;
+        this.sleep = options.sleep ?? defaultSleep;
+    }
+    /** Uploads that have not settled yet (0 once every upload has resolved, rejected, or been aborted). */
+    get pendingUploads() {
+        return this.uploads.size;
+    }
+    /**
+     * Downloads still holding a stream id: in flight, or aborted and waiting for the daemon's last
+     * frame. 0 once every download has finished and the daemon is done with its stream.
+     */
+    get pendingDownloads() {
+        return this.pending.size;
     }
     /** Begin routing inbound file-transfer frames. Idempotent. */
     start() {
@@ -37,115 +142,381 @@ export class FileTransferClient {
             return;
         this.detach = this.daemon.onFileTransferFrame((frame) => this.dispatch(frame));
     }
-    /** Stop routing inbound frames. Any downloads still pending are rejected. */
+    /** Stop routing inbound frames. Any downloads and uploads still pending are rejected. */
     stop() {
         this.detach?.();
         this.detach = null;
-        for (const [stream, pending] of this.pending) {
-            pending.reject(new Error("file transfer router stopped"));
-            this.pending.delete(stream);
-        }
+        this.failDownloads(new Error("file transfer router stopped"));
+        for (const run of this.uploads)
+            run.fail(new Error("file transfer router stopped"));
     }
     /**
-     * Download the file at `path`: requests a single-use token, then requests the chunked
-     * transfer, assembling `Begin → Chunk* → End` frames into one buffer.
+     * Download a byte range of the file at `path` into `sink`, which is called once per `Chunk` in
+     * wire order. The client keeps no reference to a chunk after the call, so memory stays at about
+     * one chunk however large the range is. With no `offset`/`length` the whole file is requested.
+     *
+     * - **`sink` is synchronous.** Frames are handled in arrival order on the transport's delivery
+     *   path, so the sink cannot make the daemon wait. A consumer that must wait (writing to disk)
+     *   has to buffer, or pace itself by asking for ranges one after the other. A sink (or
+     *   `onProgress`) that throws aborts the download: the daemon is told to stop and this rejects
+     *   with that error.
+     * - **Resolves** after `End` with the range's metadata, taken from the `Begin` frame:
+     *   `{ fileName?, mimeType?, totalBytes, mtimeMs, offset, length }`. `totalBytes`/`mtimeMs`
+     *   describe the whole file when the transfer began; keep them to resume with `ifUnchanged`.
+     * - **`onProgress(received, length)`** fires after every chunk with the bytes received so far in
+     *   this range (monotonic) and the range length; it ends at `length`.
+     * - **Rejects** with the daemon's error code when the request is refused (`not_found`,
+     *   `changed`, `stream_in_use`, …), with the `Error` frame's message (`read_failed`, `changed`,
+     *   `cancelled`) when the transfer fails midway, and when the connection closes or {@link stop}
+     *   is called. It rejects before sending anything when the daemon did not advertise
+     *   `fileDownloadRanges`.
+     * - **Abort.** `signal` aborting rejects with an `AbortError` and sends
+     *   `file_download_cancel_request { stream }`. The stream id is held until the daemon has said
+     *   nothing more will arrive on it (a terminal frame, or a refusal), so a late frame can never
+     *   reach a later download that reuses the id; frames that do arrive meanwhile are ignored.
      *
-     * Retries exactly once on an expired token. The daemon's TTL runs from the moment it ISSUES a
-     * token, but the token only becomes usable once its response reaches us — queued behind every
-     * `Chunk` frame already in flight on this one socket. A large transfer ahead of it can hand us
-     * a token that is dead on arrival (relay makes this routine: base64-inflated frames, extra
-     * hop). By the time we see the rejection that backlog has drained, so a second attempt lands on
-     * a quiet socket; looping further would only spin on a genuinely broken link.
+     * The stream id is registered BEFORE the request is sent: the daemon answers first and streams
+     * right after, and a frame for an unregistered id would be dropped.
      */
-    async download(path) {
-        try {
-            return await this.attemptDownload(path);
-        }
-        catch (error) {
-            if (!(error instanceof Error) || error.message !== EXPIRED_TOKEN)
-                throw error;
-            return await this.attemptDownload(path);
-        }
-    }
-    async attemptDownload(path) {
-        const tokenResponse = await this.daemon.request("file_download_token_request", {
-            path,
-        });
-        if (!tokenResponse.ok || !tokenResponse.token) {
-            throw new Error(tokenResponse.error ?? "failed to issue download token");
-        }
+    async downloadTo(path, sink, options = {}) {
+        const { offset, length, ifUnchanged, signal, onProgress } = options;
+        if (!this.daemon.hasFeature("fileDownloadRanges"))
+            throw new Error(RANGES_UNSUPPORTED);
+        if (signal?.aborted)
+            throw abortError("download");
+        if (this.daemon.state !== "open")
+            throw new Error("connection is not open");
         // Stream ids live in a single frame-header byte, so they are recycled as transfers finish;
         // an ever-incrementing counter would emit 256 and be rejected by the codec from then on.
         const stream = nextFreeSlot(this.pending, this.streamCursor);
         if (stream === null)
             throw new Error("no free download stream");
         this.streamCursor = (stream + 1) % SLOT_SPACE;
-        const result = new Promise((resolve, reject) => {
-            this.pending.set(stream, { chunks: [], meta: {}, resolve, reject });
+        return await new Promise((resolve, reject) => {
+            const entry = {
+                sink,
+                onProgress,
+                info: undefined,
+                received: 0,
+                progressed: false,
+                settled: false,
+                detachAbort: null,
+                resolve,
+                reject,
+            };
+            this.pending.set(stream, entry);
+            this.watchConnection();
+            if (signal) {
+                const onAbort = () => this.abortDownload(stream, entry, abortError("download"));
+                signal.addEventListener("abort", onAbort, { once: true });
+                entry.detachAbort = () => signal.removeEventListener("abort", onAbort);
+            }
+            // The response only says yes or no: the range metadata arrives in-band on `Begin`, which
+            // may be dispatched before this continuation runs.
+            this.daemon
+                .request("file_download_request", {
+                path,
+                stream,
+                offset,
+                length,
+                ifUnchanged,
+            })
+                .then((response) => {
+                if (response.ok)
+                    return;
+                // A refused request streams nothing, so nothing else would free the id.
+                this.finish(entry, { error: new Error(response.error ?? "download request failed") });
+                this.release(stream, entry);
+            }, (error) => {
+                // Timed out or socket killed: no frame will ever release the id.
+                this.finish(entry, { error: asError(error) });
+                this.release(stream, entry);
+            });
         });
-        let requestResponse;
+    }
+    /**
+     * Download the file at `path` (or the range in `options`) into one buffer: {@link downloadTo}
+     * collecting the chunks. Prefer `downloadTo` for anything large.
+     */
+    async download(path, options = {}) {
+        const chunks = [];
+        const result = await this.downloadTo(path, (chunk) => {
+            chunks.push(chunk);
+        }, options);
+        return { ...result, bytes: concat(chunks) };
+    }
+    /** Settle a download for its caller, once. The stream id is released separately. */
+    finish(entry, outcome) {
+        if (entry.settled)
+            return;
+        entry.settled = true;
+        entry.detachAbort?.();
+        entry.detachAbort = null;
+        if ("error" in outcome)
+            entry.reject(outcome.error);
+        else
+            entry.resolve(outcome.result);
+    }
+    /** Give a download's stream id back — only if it still belongs to `entry`. */
+    release(stream, entry) {
+        if (this.pending.get(stream) !== entry)
+            return;
+        this.pending.delete(stream);
+        if (this.pending.size === 0)
+            this.unwatchConnection();
+    }
+    /**
+     * Reject a download now and tell the daemon to stop it. The id stays claimed until the daemon
+     * has nothing more to send on it: a terminal frame (see `dispatch`), a refused request, or a
+     * `not_found` cancel (nothing active — whatever it sent is already behind us on the socket).
+     */
+    abortDownload(stream, entry, error) {
+        if (entry.settled)
+            return;
+        this.finish(entry, { error });
+        if (this.daemon.state !== "open") {
+            this.release(stream, entry);
+            return;
+        }
+        void this.daemon
+            .request("file_download_cancel_request", { stream })
+            .then((response) => {
+            if (!response.ok)
+                this.release(stream, entry);
+        }, () => this.release(stream, entry));
+    }
+    /** Reject every download and free every id (stop, or the connection is gone). */
+    failDownloads(error) {
+        const entries = [...this.pending.values()];
+        this.pending.clear();
+        this.unwatchConnection();
+        for (const entry of entries)
+            this.finish(entry, { error });
+    }
+    /** Watch the connection only while a download is pending, so an idle client holds no listener. */
+    watchConnection() {
+        if (this.detachState)
+            return;
+        this.detachState = this.daemon.onStateChange((state) => {
+            if (state !== "open")
+                this.failDownloads(new Error(`connection ${state} during download`));
+        });
+    }
+    unwatchConnection() {
+        this.detachState?.();
+        this.detachState = null;
+    }
+    /**
+     * Upload `source` to `path` on the daemon: requests an upload stream, then pushes
+     * `Begin → Chunk* → End` binary frames the server writes to disk (creating parent dirs,
+     * overwriting any existing file). The server keys the transfer by `transferId`, which the
+     * `Begin` frame must echo.
+     *
+     * - **Streaming.** A `Blob` is sliced and read chunk by chunk and an async iterable is pulled one
+     *   item at a time, so memory stays at about one chunk (plus the pacing window) regardless of the
+     *   file size. `total` in `onProgress` is the byte length for a `Uint8Array`/`Blob` and
+     *   `undefined` for an async iterable.
+     * - **Pacing.** Before each chunk it waits while `transport.bufferedAmount` is above
+     *   {@link UPLOAD_HIGH_WATER_BYTES}; a transport that does not report it is never congested.
+     * - **Completion.** With the daemon's `fileTransferAck` feature it resolves when the matching
+     *   `file_upload_complete` push arrives and rejects with the daemon's error when `ok` is false;
+     *   there is no timeout on that wait. Without it, it resolves once the transport's buffer has
+     *   drained after `End` (the bytes have left this machine, not necessarily reached the disk).
+     * - **Cancel.** `signal` aborting sends an `Error` frame for the stream (so the daemon frees it)
+     *   and rejects with an `AbortError`. A dropped connection or {@link stop} rejects too.
+     *   Whatever way it ends, no listener or stream is left behind.
+     */
+    async upload(path, source, options = {}) {
+        const { onProgress, signal } = options;
+        if (signal?.aborted)
+            throw abortError("upload");
+        const run = createRun();
+        this.uploads.add(run);
+        const cleanups = [];
+        let stream;
+        let endSent = false;
+        let daemonDone = false;
         try {
-            requestResponse = await this.daemon.request("file_download_request", { token: tokenResponse.token, stream });
+            if (signal) {
+                const onAbort = () => run.fail(abortError("upload"));
+                signal.addEventListener("abort", onAbort, { once: true });
+                cleanups.push(() => signal.removeEventListener("abort", onAbort));
+            }
+            cleanups.push(this.daemon.onStateChange((state) => {
+                if (state !== "open")
+                    run.fail(new Error(`connection ${state} during upload`));
+            }));
+            if (this.daemon.state !== "open")
+                throw new Error("connection is not open");
+            const transferId = randomId();
+            const ack = this.daemon.hasFeature("fileTransferAck");
+            const request = this.daemon.request("file_upload_request", {
+                path,
+                transferId,
+                ...(ack ? { ack: true } : {}),
+            });
+            let response;
+            try {
+                response = await Promise.race([request, run.failure]);
+            }
+            catch (error) {
+                // The daemon may still answer and hand out a stream nobody will use — give it back.
+                void request.then((late) => {
+                    if (late.ok && late.stream !== undefined)
+                        this.sendUploadError(late.stream, "client_error");
+                }, () => { });
+                throw error;
+            }
+            if (!response.ok || response.stream === undefined) {
+                throw new Error(response.error ?? "upload request failed");
+            }
+            stream = response.stream;
+            // Registered before any frame is sent, so an early failure (or the final ack) cannot be missed.
+            let complete;
+            const completed = new Promise((resolve) => {
+                complete = resolve;
+            });
+            if (ack) {
+                cleanups.push(this.daemon.onSessionMessage((message) => {
+                    if (message.type !== "file_upload_complete" || message.transferId !== transferId)
+                        return;
+                    daemonDone = true; // the daemon freed the stream: nothing left for us to cancel
+                    if (message.ok)
+                        complete();
+                    else
+                        run.fail(new Error(message.error ?? "upload failed"));
+                }));
+            }
+            this.daemon.sendBinary(encodeFileTransferFrame({ opcode: "Begin", stream, meta: { transferId } }));
+            const { total, chunks } = uploadChunks(source);
+            const iterator = chunks[Symbol.asyncIterator]();
+            cleanups.push(() => {
+                void Promise.resolve(iterator.return?.()).catch(() => { });
+            });
+            let sent = 0;
+            for (;;) {
+                await this.waitWhile(() => (this.daemon.bufferedAmount ?? 0) > this.highWaterBytes, run);
+                const next = iterator.next();
+                next.catch(() => { }); // if the race below is lost to a failure, `next` must not go unhandled
+                const step = await Promise.race([next, run.failure]);
+                if (step.done)
+                    break;
+                run.check();
+                this.daemon.sendBinary(encodeFileTransferFrame({ opcode: "Chunk", stream, data: step.value }));
+                sent += step.value.length;
+                onProgress?.(sent, total);
+            }
+            if (sent === 0)
+                onProgress?.(0, total);
+            run.check();
+            this.daemon.sendBinary(encodeFileTransferFrame({ opcode: "End", stream, ok: true }));
+            endSent = true;
+            if (ack)
+                await Promise.race([completed, run.failure]);
+            else
+                await this.waitWhile(() => (this.daemon.bufferedAmount ?? 0) > 0, run);
         }
         catch (error) {
-            // A timed-out or socket-killed request never streams `End`, so release the id here or it
-            // stays claimed for the life of the connection and eats the pool.
-            this.pending.delete(stream);
+            // Before `End` the daemon still holds the stream and an open file; tell it to let go.
+            if (stream !== undefined && !endSent && !daemonDone) {
+                this.sendUploadError(stream, isAbortError(error) ? "client_aborted" : "client_error");
+            }
             throw error;
         }
-        if (!requestResponse.ok) {
-            this.pending.delete(stream);
-            throw new Error(requestResponse.error ?? "download request failed");
+        finally {
+            for (const cleanup of cleanups)
+                cleanup();
+            this.uploads.delete(run);
         }
-        return result;
     }
-    /**
-     * Upload `bytes` to `path` on the daemon: requests an upload stream, then pushes
-     * `Begin → Chunk* → End` binary frames the server writes to disk (creating parent dirs,
-     * overwriting any existing file). The server keys the transfer by `transferId`, which the
-     * `Begin` frame must echo. Resolves once every frame is flushed to the socket.
-     */
-    async upload(path, bytes) {
-        const transferId = randomId();
-        const response = await this.daemon.request("file_upload_request", {
-            path,
-            transferId,
-        });
-        if (!response.ok || response.stream === undefined) {
-            throw new Error(response.error ?? "upload request failed");
+    /** Poll `condition` on a timer until it clears, giving up as soon as the upload has failed. */
+    async waitWhile(condition, run) {
+        while (condition()) {
+            run.check();
+            await Promise.race([this.sleep(UPLOAD_POLL_MS), run.failure]);
         }
-        const stream = response.stream;
-        this.daemon.sendBinary(encodeFileTransferFrame({ opcode: "Begin", stream, meta: { transferId } }));
-        for (let offset = 0; offset < bytes.length; offset += UPLOAD_CHUNK_BYTES) {
-            const data = bytes.subarray(offset, offset + UPLOAD_CHUNK_BYTES);
-            this.daemon.sendBinary(encodeFileTransferFrame({ opcode: "Chunk", stream, data }));
+    }
+    /** Best-effort `Error` frame for an upload stream; a dead connection has nothing to tell. */
+    sendUploadError(stream, message) {
+        if (this.daemon.state !== "open")
+            return;
+        try {
+            this.daemon.sendBinary(encodeFileTransferFrame({ opcode: "Error", stream, message }));
+        }
+        catch {
+            /* the socket died under us — the daemon frees the stream when it notices */
         }
-        this.daemon.sendBinary(encodeFileTransferFrame({ opcode: "End", stream, ok: true }));
     }
     dispatch(frame) {
-        const pending = this.pending.get(frame.stream);
-        if (!pending)
+        const entry = this.pending.get(frame.stream);
+        if (!entry)
             return; // not a download stream we're tracking (e.g. an upload) — ignore
+        // Everything below runs synchronously and in arrival order (see `transport.ts`): a frame that
+        // is handled later than its successors is a truncated download.
         switch (frame.opcode) {
-            case "Begin":
-                pending.meta.fileName = frame.meta.fileName;
-                pending.meta.mimeType = frame.meta.mimeType;
+            case "Begin": {
+                if (entry.settled)
+                    return;
+                const info = downloadResult(frame.meta);
+                if (!info) {
+                    this.abortDownload(frame.stream, entry, new Error("daemon sent a Begin frame without the range"));
+                    return;
+                }
+                entry.info = info;
                 return;
-            case "Chunk":
-                pending.chunks.push(frame.data);
+            }
+            case "Chunk": {
+                if (entry.settled)
+                    return; // aborted: the daemon may still have frames in flight
+                const { info } = entry;
+                if (!info) {
+                    this.abortDownload(frame.stream, entry, new Error("daemon sent a Chunk before Begin"));
+                    return;
+                }
+                try {
+                    entry.sink(frame.data);
+                    entry.received += frame.data.length;
+                    entry.progressed = true;
+                    entry.onProgress?.(entry.received, info.length);
+                }
+                catch (error) {
+                    this.abortDownload(frame.stream, entry, asError(error));
+                }
                 return;
-            case "End":
-                this.pending.delete(frame.stream);
-                if (frame.ok) {
-                    pending.resolve({ bytes: concat(pending.chunks), ...pending.meta });
+            }
+            case "End": {
+                this.release(frame.stream, entry);
+                if (entry.settled)
+                    return;
+                const { info } = entry;
+                if (!frame.ok) {
+                    this.finish(entry, { error: new Error("download failed") });
+                }
+                else if (!info) {
+                    this.finish(entry, { error: new Error("download ended before Begin") });
+                }
+                else if (entry.received !== info.length) {
+                    this.finish(entry, {
+                        error: new Error(`download ended after ${entry.received} of ${info.length} bytes`),
+                    });
                 }
                 else {
-                    pending.reject(new Error("download failed"));
+                    try {
+                        // An empty range sends no `Chunk`; progress still ends at `length`.
+                        if (!entry.progressed)
+                            entry.onProgress?.(0, info.length);
+                    }
+                    catch (error) {
+                        this.finish(entry, { error: asError(error) });
+                        return;
+                    }
+                    this.finish(entry, { result: info });
                 }
                 return;
+            }
             case "Error":
-                this.pending.delete(frame.stream);
-                pending.reject(new Error(frame.message));
+                this.release(frame.stream, entry);
+                this.finish(entry, { error: new Error(frame.message) });
                 return;
         }
     }

package/dist/pistudio-client.d.ts

@@ -78,7 +78,12 @@ export interface PiStudioAgentTimelineHandle {
         direction?: TimelineDirection;
         limit?: number;
     }): Promise<FetchAgentTimelineResponse>;
-    /** Subscribe to live `agent_stream` events for this agent. Returns an unsubscribe fn. */
+    /**
+     * Subscribe to live `agent_stream` events for this agent. Returns an unsubscribe fn. On a
+     * connection opened with `agentStreams: "none"` the handler never fires (against a daemon that
+     * honours it); against one without `agentStreamsMode` the option is ignored and streams arrive,
+     * so a handler must tolerate them.
+     */
     subscribe(handler: PiStudioAgentStreamHandler): () => void;
 }
 export interface PiStudioAgentActions {

package/dist/relay-transport.js

@@ -22,7 +22,7 @@
  * `packages/server/src/daemon/relay-transport.ts`'s choice (`{ type: "relay_register", sessionId
  * }`) — the real protocol is unresolved upstream (architecture/relay-e2ee.md § TODO(verify)).
  */
-import { createClientChannel, deriveRelaySessionId } from "@av-pi-studio/relay";
+import { createClientChannel, deriveRelaySessionId, } from "@av-pi-studio/relay";
 import { reasonString } from "./transport.js";
 /** Build the relay's own `ws://`/`wss://` dial URL from a pairing offer's `relay` info. */
 export function relayDialUrl(relay) {
@@ -49,6 +49,11 @@ export function createRelayTransport(opts) {
         get isOpen() {
             return ws !== null && ws.readyState === 1 && channel !== null && channel.ready;
         },
+        // The channel encrypts and writes synchronously, so the relay socket's queue is exactly the
+        // (base64-inflated) ciphertext still waiting to leave — the right number to pace against.
+        get bufferedAmount() {
+            return ws?.bufferedAmount;
+        },
         connect(url) {
             return new Promise((resolve, reject) => {
                 const create = opts.factory ?? (() => new WebSocket(url));

package/dist/transport.d.ts

@@ -16,6 +16,13 @@ export interface Transport {
     close(code?: number, reason?: string): void;
     /** Whether the transport is currently open and writeable. */
     readonly isOpen: boolean;
+    /**
+     * Bytes accepted by `sendText`/`sendBinary` but not yet handed to the network (the underlying
+     * socket's send queue). Optional: a transport that cannot report it leaves it `undefined` and
+     * is treated as never congested — `FileTransferClient.upload` then does not pace. Out-of-tree
+     * implementations (the desktop app's Rust bridge) may omit it.
+     */
+    readonly bufferedAmount?: number;
     onMessage: TransportMessageHandler | null;
     onClose: TransportCloseHandler | null;
     onError: TransportErrorHandler | null;
@@ -36,6 +43,8 @@ export type AnyWebSocket = {
     /** Browsers/RN default this to `"blob"`; Node's `ws` ignores it (always delivers `Buffer`).
      * `connect()` forces `"arraybuffer"` where the property exists — see its comment for why. */
     binaryType?: string;
+    /** Bytes queued by `send()` and not yet transmitted (browser/RN/`ws` all report it). */
+    readonly bufferedAmount?: number;
 };
 export type WsFactory = (url: string, protocols?: string[]) => AnyWebSocket;
 export declare function reasonString(reason: unknown): string;

package/dist/transport.js

@@ -23,6 +23,9 @@ export function createWebSocketTransport(factory) {
         get isOpen() {
             return ws !== null && ws.readyState === 1; // OPEN
         },
+        get bufferedAmount() {
+            return ws?.bufferedAmount;
+        },
         connect(url) {
             return new Promise((resolve, reject) => {
                 const create = factory ?? (() => new WebSocket(url));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@av-pi-studio/client",
-  "version": "0.0.117",
+  "version": "0.0.119",
   "files": [
     "dist",
     "!dist/**/*.map",
@@ -20,8 +20,8 @@
     "clean": "rm -rf dist *.tsbuildinfo"
   },
   "dependencies": {
-    "@av-pi-studio/protocol": "^0.0.117",
-    "@av-pi-studio/relay": "^0.0.117"
+    "@av-pi-studio/protocol": "^0.0.119",
+    "@av-pi-studio/relay": "^0.0.119"
   },
   "repository": {
     "type": "git",