@av-pi-studio/client 0.0.118 → 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

@@ -26,6 +26,14 @@ export interface DaemonClientOptions {
      * 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>;

package/dist/daemon-client.js

@@ -95,6 +95,7 @@ export class DaemonClient {
             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,

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

@@ -20,10 +20,37 @@ export interface FileTransferClientOptions {
     /** Override the pacing timer (tests); resolves after `ms`. */
     sleep?(ms: number): Promise<void>;
 }
-export interface DownloadedFile {
-    bytes: Uint8Array;
+/** 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;
@@ -31,29 +58,72 @@ 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;
+    /** 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 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, 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;
+    /**
+     * 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).
      */
-    download(path: string): Promise<DownloadedFile>;
-    private attemptDownload;
+    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,

package/dist/file-transfer-client.js

@@ -1,17 +1,16 @@
 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
@@ -21,6 +20,8 @@ const EXPIRED_TOKEN = "invalid_or_expired_token";
 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`).
@@ -44,8 +45,29 @@ function createRun() {
         },
     };
 }
-function abortError() {
-    return new DOMException("The upload was aborted", "AbortError");
+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";
@@ -93,6 +115,8 @@ 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;
+    /** Present only while a download is pending: rejects them when the connection leaves `open`. */
+    detachState = null;
     uploads = new Set();
     highWaterBytes;
     sleep;
@@ -105,6 +129,13 @@ export class FileTransferClient {
     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() {
         if (this.detach)
@@ -115,65 +146,165 @@ export class FileTransferClient {
     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;
-        try {
-            requestResponse = await this.daemon.request("file_download_request", { token: tokenResponse.token, stream });
-        }
-        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);
-            throw error;
-        }
-        if (!requestResponse.ok) {
-            this.pending.delete(stream);
-            throw new Error(requestResponse.error ?? "download request failed");
+    }
+    /**
+     * 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;
         }
-        return result;
+        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
@@ -198,7 +329,7 @@ export class FileTransferClient {
     async upload(path, source, options = {}) {
         const { onProgress, signal } = options;
         if (signal?.aborted)
-            throw abortError();
+            throw abortError("upload");
         const run = createRun();
         this.uploads.add(run);
         const cleanups = [];
@@ -207,7 +338,7 @@ export class FileTransferClient {
         let daemonDone = false;
         try {
             if (signal) {
-                const onAbort = () => run.fail(abortError());
+                const onAbort = () => run.fail(abortError("upload"));
                 signal.addEventListener("abort", onAbort, { once: true });
                 cleanups.push(() => signal.removeEventListener("abort", onAbort));
             }
@@ -317,29 +448,75 @@ export class FileTransferClient {
         }
     }
     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/package.json

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