@sonara/client 0.32.12 → 0.32.13

package/README.md

@@ -19,6 +19,7 @@ await sonara.close();
 - `control(action)`: `play`, `pause`, `toggle`, `stop`, `skip`, `previous`, `next`, `restart`, `mute`, `unmute`.
 - `set(key, value)` / `get(key)` for `volume` (0..100), `rate` (100..400 wpm), `voice`, `engine`; `voices(engine?)`.
 - `onState`, `onItem`, `onLog` return an unsubscribe function; events arrive on a second connection opened by the first listener. Every state listener, also one added later, gets the current state first. `onClose` fires when the runtime goes away.
+- `request(type, fields, { timeoutMs })` sends any message; with `timeoutMs` it rejects with `E_TIMEOUT` and the client stays open (no bound by default; `engine_test` may take a minute). A request over 1 MiB of UTF-8 is refused with `E_BAD_REQUEST` and the client stays open.
 - `channels`, `agent`, `system`: extension namespaces that send the protocol's extension messages as they are.
 - Errors are `SonaraError` with a `code` (`E_BUSY`, `E_NOT_RUNNING`, ...).
 

package/dist/cjs/client.d.ts

@@ -1,7 +1,7 @@
 import { Connection } from "./connection.js";
 import { EnginesApi } from "./engines.js";
 import { AgentApi, ChannelsApi, SystemApi } from "./extensions.js";
-import type { ControlAction, HelloInfo, ItemEvent, LogEvent, Reply, RuntimeInfo, SettingKey, SpeakOptions, State, Voice } from "./types.js";
+import type { ControlAction, HelloInfo, ItemEvent, LogEvent, Reply, RequestOptions, RuntimeInfo, SettingKey, SpeakOptions, State, Voice } from "./types.js";
 export type Unsubscribe = () => void;
 type Listener<T> = (value: T) => void;
 /** Opens and greets one more connection (the event connection). */
@@ -39,8 +39,11 @@ export declare class SonaraClient {
     constructor(conn: Connection, runtime: RuntimeInfo, info: HelloInfo, dial: Dial);
     /** True once the connection closed (close(), a takeover or the runtime exited). */
     get closed(): boolean;
-    /** Send any protocol message; resolves with the `ok: true` reply. */
-    request(type: string, fields?: Record<string, unknown>): Promise<Reply>;
+    /**
+     * Send any protocol message; resolves with the `ok: true` reply.
+     * `opts.timeoutMs` bounds this one request (`E_TIMEOUT`; default: none).
+     */
+    request(type: string, fields?: Record<string, unknown>, opts?: RequestOptions): Promise<Reply>;
     /** Add `text` as one item; resolves with its item id. */
     speak(text: string, opts?: SpeakOptions): Promise<number>;
     /**

package/dist/cjs/client.js

@@ -40,9 +40,12 @@ class SonaraClient {
     get closed() {
         return this.conn.closed;
     }
-    /** Send any protocol message; resolves with the `ok: true` reply. */
-    request(type, fields = {}) {
-        return this.conn.request(type, fields);
+    /**
+     * Send any protocol message; resolves with the `ok: true` reply.
+     * `opts.timeoutMs` bounds this one request (`E_TIMEOUT`; default: none).
+     */
+    request(type, fields = {}, opts = {}) {
+        return this.conn.request(type, fields, opts);
     }
     /** Add `text` as one item; resolves with its item id. */
     async speak(text, opts = {}) {

package/dist/cjs/connection.d.ts

@@ -1,4 +1,6 @@
-import type { Reply } from "./types.js";
+import type { Reply, RequestOptions } from "./types.js";
+/** Longest line the runtime accepts (bytes, newline included); a longer one closes the connection. */
+export declare const MAX_LINE: number;
 /**
  * One TCP JSON-lines connection to the runtime. Requests carry an `id`;
  * replies (with `ok`) settle the matching promise, events (with `event`) go
@@ -17,7 +19,7 @@ export declare class Connection {
     static open(port: number, timeoutMs: number): Promise<Connection>;
     get closed(): boolean;
     /** Send `{type, ...fields}`; resolves with the `ok: true` reply, rejects with a SonaraError. */
-    request(type: string, fields?: Record<string, unknown>): Promise<Reply>;
+    request(type: string, fields?: Record<string, unknown>, opts?: RequestOptions): Promise<Reply>;
     close(): void;
     private onData;
     private onLine;

package/dist/cjs/connection.js

@@ -1,8 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Connection = void 0;
+exports.Connection = exports.MAX_LINE = void 0;
 const net = require("node:net");
 const errors_js_1 = require("./errors.js");
+/** Longest line the runtime accepts (bytes, newline included); a longer one closes the connection. */
+exports.MAX_LINE = 1 << 20;
 /**
  * One TCP JSON-lines connection to the runtime. Requests carry an `id`;
  * replies (with `ok`) settle the matching promise, events (with `event`) go
@@ -48,15 +50,42 @@ class Connection {
         return this.closedFlag;
     }
     /** Send `{type, ...fields}`; resolves with the `ok: true` reply, rejects with a SonaraError. */
-    request(type, fields = {}) {
+    request(type, fields = {}, opts = {}) {
         if (this.closedFlag) {
             return Promise.reject(new errors_js_1.SonaraError("E_CLOSED", "the connection is closed"));
         }
         const id = this.nextId++;
-        const msg = { ...fields, type, id };
+        const line = JSON.stringify({ ...fields, type, id }) + "\n";
+        const bytes = Buffer.byteLength(line, "utf8");
+        if (bytes > exports.MAX_LINE) {
+            // Refused here, so the shared connection stays open (#54).
+            return Promise.reject(new errors_js_1.SonaraError("E_BAD_REQUEST", `line too long: ${bytes} bytes, at most ${exports.MAX_LINE}`));
+        }
         return new Promise((resolve, reject) => {
-            this.pending.set(id, { resolve, reject });
-            this.sock.write(JSON.stringify(msg) + "\n");
+            let timer;
+            const done = () => {
+                if (timer !== undefined)
+                    clearTimeout(timer);
+            };
+            this.pending.set(id, {
+                resolve: (r) => {
+                    done();
+                    resolve(r);
+                },
+                reject: (e) => {
+                    done();
+                    reject(e);
+                },
+            });
+            if (opts.timeoutMs !== undefined) {
+                timer = setTimeout(() => {
+                    // Replies carry their id, so a late one is dropped (onLine).
+                    if (this.pending.delete(id)) {
+                        reject(new errors_js_1.SonaraError("E_TIMEOUT", `no reply to ${type} within ${opts.timeoutMs} ms`));
+                    }
+                }, opts.timeoutMs);
+            }
+            this.sock.write(line);
         });
     }
     close() {
@@ -94,7 +123,10 @@ class Connection {
         const id = typeof m.id === "number" ? m.id : undefined;
         // Replies come in request order, so a reply without our id (the runtime
         // could not parse the request) belongs to the oldest pending request.
-        const key = id !== undefined && this.pending.has(id) ? id : this.pending.keys().next().value;
+        // One with an id no longer pending answers a request that timed out.
+        if (id !== undefined && !this.pending.has(id))
+            return;
+        const key = id !== undefined ? id : this.pending.keys().next().value;
         if (key === undefined)
             return;
         const p = this.pending.get(key);

package/dist/cjs/errors.d.ts

@@ -1,6 +1,6 @@
 /**
  * Error codes. The `E_*` codes of protocol v1 come from the runtime as is;
- * the client adds three of its own for what happens before or after a reply.
+ * the client adds four of its own for what happens before or after a reply.
  */
 export type ErrorCode = "E_AUTH" | "E_BAD_REQUEST" | "E_UNKNOWN_TYPE" | "E_UNSUPPORTED" | "E_INCOMPATIBLE" | "E_BUSY" | "E_ENGINE" | "E_NOT_FOUND"
 /** Protocol 1.3: never allowed over the protocol (adding or changing a `command` engine). */
@@ -10,7 +10,9 @@ export type ErrorCode = "E_AUTH" | "E_BAD_REQUEST" | "E_UNKNOWN_TYPE" | "E_UNSUP
 /** The bundled runtime did not start or wrote no runtime.json within the wait. */
  | "E_START_FAILED"
 /** The connection closed before the reply (the runtime exited or close() was called). */
- | "E_CLOSED" | (string & {});
+ | "E_CLOSED"
+/** No reply within the request's `timeoutMs`; the connection stays open. */
+ | "E_TIMEOUT" | (string & {});
 /** Any failure of a Sonara call: a coded protocol error or a client-side one. */
 export declare class SonaraError extends Error {
     readonly code: ErrorCode;

package/dist/cjs/extensions.d.ts

@@ -65,7 +65,10 @@ export declare class AgentApi {
     /**
      * `ask`: a question, permission or plan, spoken with priority. A question
      * of a set (protocol 1.6, runtime 0.22.0) carries `set_index` (0-based)
-     * and `set_size` in `extra`: only the first is read, "Question 1 of N.".
+     * and `set_size` in `extra`. By default (agent key `question_step` `"off"`,
+     * protocol 1.11, runtime 0.32.0) every question of the set is read in
+     * order, "Question k of N."; with `set question_step "on"` only question 1
+     * is read and the others wait for `nextQuestion`.
      */
     ask(channel: string, kind: AskKind, text: string, options?: unknown[], extra?: Extra): Promise<Reply>;
     /**

package/dist/cjs/extensions.js

@@ -73,7 +73,10 @@ class AgentApi {
     /**
      * `ask`: a question, permission or plan, spoken with priority. A question
      * of a set (protocol 1.6, runtime 0.22.0) carries `set_index` (0-based)
-     * and `set_size` in `extra`: only the first is read, "Question 1 of N.".
+     * and `set_size` in `extra`. By default (agent key `question_step` `"off"`,
+     * protocol 1.11, runtime 0.32.0) every question of the set is read in
+     * order, "Question k of N."; with `set question_step "on"` only question 1
+     * is read and the others wait for `nextQuestion`.
      */
     ask(channel, kind, text, options, extra = {}) {
         return this.send("ask", defined({ ...extra, channel, kind, text, options }));

package/dist/cjs/index.d.ts

@@ -18,4 +18,4 @@ export type { EngineAddOptions, EngineModelsDraft, EngineProfile, SendMode, Engi
 export type { AskKind, AudioMode, ChannelOpenOptions, ChannelPolicy, StreamMessage } from "./extensions.js";
 export { readRuntime, resolveHome } from "./discovery.js";
 export { PROTOCOL, VERSION } from "./version.js";
-export type { ControlAction, EngineStatus, HelloInfo, ItemEvent, ItemPhase, LogEvent, NowPlaying, Reply, RuntimeInfo, SettingKey, SpeakMode, SpeakOptions, State, Voice, } from "./types.js";
+export type { ControlAction, EngineStatus, HelloInfo, ItemEvent, ItemPhase, LogEvent, NowPlaying, Reply, RequestOptions, RuntimeInfo, SettingKey, SpeakMode, SpeakOptions, State, Voice, } from "./types.js";

package/dist/cjs/types.d.ts

@@ -14,6 +14,15 @@ export interface SpeakOptions {
     /** Shown in `state.now_playing.label`. */
     label?: string;
 }
+/** Options of one `request`. */
+export interface RequestOptions {
+    /**
+     * Reject with `E_TIMEOUT` when no reply came within this many ms (default:
+     * no bound). The connection stays open and a late reply is dropped.
+     * `engine_test` may take up to a profile's `timeout_ms` (60 s for Gemini).
+     */
+    timeoutMs?: number;
+}
 export interface NowPlaying {
     item_id: number;
     label: string | null;

package/dist/cjs/version.d.ts

@@ -1,5 +1,5 @@
 /** Version of this package, sent as `client.version` in `hello`. */
-export declare const VERSION = "0.32.12";
+export declare const VERSION = "0.32.13";
 /** Protocol this client speaks. */
 export declare const PROTOCOL: {
     readonly major: 1;

package/dist/cjs/version.js

@@ -2,6 +2,6 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PROTOCOL = exports.VERSION = void 0;
 /** Version of this package, sent as `client.version` in `hello`. */
-exports.VERSION = "0.32.12";
+exports.VERSION = "0.32.13";
 /** Protocol this client speaks. */
 exports.PROTOCOL = { major: 1, minor: 0 };

package/dist/esm/client.d.ts

@@ -1,7 +1,7 @@
 import { Connection } from "./connection.js";
 import { EnginesApi } from "./engines.js";
 import { AgentApi, ChannelsApi, SystemApi } from "./extensions.js";
-import type { ControlAction, HelloInfo, ItemEvent, LogEvent, Reply, RuntimeInfo, SettingKey, SpeakOptions, State, Voice } from "./types.js";
+import type { ControlAction, HelloInfo, ItemEvent, LogEvent, Reply, RequestOptions, RuntimeInfo, SettingKey, SpeakOptions, State, Voice } from "./types.js";
 export type Unsubscribe = () => void;
 type Listener<T> = (value: T) => void;
 /** Opens and greets one more connection (the event connection). */
@@ -39,8 +39,11 @@ export declare class SonaraClient {
     constructor(conn: Connection, runtime: RuntimeInfo, info: HelloInfo, dial: Dial);
     /** True once the connection closed (close(), a takeover or the runtime exited). */
     get closed(): boolean;
-    /** Send any protocol message; resolves with the `ok: true` reply. */
-    request(type: string, fields?: Record<string, unknown>): Promise<Reply>;
+    /**
+     * Send any protocol message; resolves with the `ok: true` reply.
+     * `opts.timeoutMs` bounds this one request (`E_TIMEOUT`; default: none).
+     */
+    request(type: string, fields?: Record<string, unknown>, opts?: RequestOptions): Promise<Reply>;
     /** Add `text` as one item; resolves with its item id. */
     speak(text: string, opts?: SpeakOptions): Promise<number>;
     /**

package/dist/esm/client.js

@@ -37,9 +37,12 @@ export class SonaraClient {
     get closed() {
         return this.conn.closed;
     }
-    /** Send any protocol message; resolves with the `ok: true` reply. */
-    request(type, fields = {}) {
-        return this.conn.request(type, fields);
+    /**
+     * Send any protocol message; resolves with the `ok: true` reply.
+     * `opts.timeoutMs` bounds this one request (`E_TIMEOUT`; default: none).
+     */
+    request(type, fields = {}, opts = {}) {
+        return this.conn.request(type, fields, opts);
     }
     /** Add `text` as one item; resolves with its item id. */
     async speak(text, opts = {}) {

package/dist/esm/connection.d.ts

@@ -1,4 +1,6 @@
-import type { Reply } from "./types.js";
+import type { Reply, RequestOptions } from "./types.js";
+/** Longest line the runtime accepts (bytes, newline included); a longer one closes the connection. */
+export declare const MAX_LINE: number;
 /**
  * One TCP JSON-lines connection to the runtime. Requests carry an `id`;
  * replies (with `ok`) settle the matching promise, events (with `event`) go
@@ -17,7 +19,7 @@ export declare class Connection {
     static open(port: number, timeoutMs: number): Promise<Connection>;
     get closed(): boolean;
     /** Send `{type, ...fields}`; resolves with the `ok: true` reply, rejects with a SonaraError. */
-    request(type: string, fields?: Record<string, unknown>): Promise<Reply>;
+    request(type: string, fields?: Record<string, unknown>, opts?: RequestOptions): Promise<Reply>;
     close(): void;
     private onData;
     private onLine;

package/dist/esm/connection.js

@@ -1,5 +1,7 @@
 import * as net from "node:net";
 import { SonaraError } from "./errors.js";
+/** Longest line the runtime accepts (bytes, newline included); a longer one closes the connection. */
+export const MAX_LINE = 1 << 20;
 /**
  * One TCP JSON-lines connection to the runtime. Requests carry an `id`;
  * replies (with `ok`) settle the matching promise, events (with `event`) go
@@ -45,15 +47,42 @@ export class Connection {
         return this.closedFlag;
     }
     /** Send `{type, ...fields}`; resolves with the `ok: true` reply, rejects with a SonaraError. */
-    request(type, fields = {}) {
+    request(type, fields = {}, opts = {}) {
         if (this.closedFlag) {
             return Promise.reject(new SonaraError("E_CLOSED", "the connection is closed"));
         }
         const id = this.nextId++;
-        const msg = { ...fields, type, id };
+        const line = JSON.stringify({ ...fields, type, id }) + "\n";
+        const bytes = Buffer.byteLength(line, "utf8");
+        if (bytes > MAX_LINE) {
+            // Refused here, so the shared connection stays open (#54).
+            return Promise.reject(new SonaraError("E_BAD_REQUEST", `line too long: ${bytes} bytes, at most ${MAX_LINE}`));
+        }
         return new Promise((resolve, reject) => {
-            this.pending.set(id, { resolve, reject });
-            this.sock.write(JSON.stringify(msg) + "\n");
+            let timer;
+            const done = () => {
+                if (timer !== undefined)
+                    clearTimeout(timer);
+            };
+            this.pending.set(id, {
+                resolve: (r) => {
+                    done();
+                    resolve(r);
+                },
+                reject: (e) => {
+                    done();
+                    reject(e);
+                },
+            });
+            if (opts.timeoutMs !== undefined) {
+                timer = setTimeout(() => {
+                    // Replies carry their id, so a late one is dropped (onLine).
+                    if (this.pending.delete(id)) {
+                        reject(new SonaraError("E_TIMEOUT", `no reply to ${type} within ${opts.timeoutMs} ms`));
+                    }
+                }, opts.timeoutMs);
+            }
+            this.sock.write(line);
         });
     }
     close() {
@@ -91,7 +120,10 @@ export class Connection {
         const id = typeof m.id === "number" ? m.id : undefined;
         // Replies come in request order, so a reply without our id (the runtime
         // could not parse the request) belongs to the oldest pending request.
-        const key = id !== undefined && this.pending.has(id) ? id : this.pending.keys().next().value;
+        // One with an id no longer pending answers a request that timed out.
+        if (id !== undefined && !this.pending.has(id))
+            return;
+        const key = id !== undefined ? id : this.pending.keys().next().value;
         if (key === undefined)
             return;
         const p = this.pending.get(key);

package/dist/esm/errors.d.ts

@@ -1,6 +1,6 @@
 /**
  * Error codes. The `E_*` codes of protocol v1 come from the runtime as is;
- * the client adds three of its own for what happens before or after a reply.
+ * the client adds four of its own for what happens before or after a reply.
  */
 export type ErrorCode = "E_AUTH" | "E_BAD_REQUEST" | "E_UNKNOWN_TYPE" | "E_UNSUPPORTED" | "E_INCOMPATIBLE" | "E_BUSY" | "E_ENGINE" | "E_NOT_FOUND"
 /** Protocol 1.3: never allowed over the protocol (adding or changing a `command` engine). */
@@ -10,7 +10,9 @@ export type ErrorCode = "E_AUTH" | "E_BAD_REQUEST" | "E_UNKNOWN_TYPE" | "E_UNSUP
 /** The bundled runtime did not start or wrote no runtime.json within the wait. */
  | "E_START_FAILED"
 /** The connection closed before the reply (the runtime exited or close() was called). */
- | "E_CLOSED" | (string & {});
+ | "E_CLOSED"
+/** No reply within the request's `timeoutMs`; the connection stays open. */
+ | "E_TIMEOUT" | (string & {});
 /** Any failure of a Sonara call: a coded protocol error or a client-side one. */
 export declare class SonaraError extends Error {
     readonly code: ErrorCode;

package/dist/esm/extensions.d.ts

@@ -65,7 +65,10 @@ export declare class AgentApi {
     /**
      * `ask`: a question, permission or plan, spoken with priority. A question
      * of a set (protocol 1.6, runtime 0.22.0) carries `set_index` (0-based)
-     * and `set_size` in `extra`: only the first is read, "Question 1 of N.".
+     * and `set_size` in `extra`. By default (agent key `question_step` `"off"`,
+     * protocol 1.11, runtime 0.32.0) every question of the set is read in
+     * order, "Question k of N."; with `set question_step "on"` only question 1
+     * is read and the others wait for `nextQuestion`.
      */
     ask(channel: string, kind: AskKind, text: string, options?: unknown[], extra?: Extra): Promise<Reply>;
     /**

package/dist/esm/extensions.js

@@ -69,7 +69,10 @@ export class AgentApi {
     /**
      * `ask`: a question, permission or plan, spoken with priority. A question
      * of a set (protocol 1.6, runtime 0.22.0) carries `set_index` (0-based)
-     * and `set_size` in `extra`: only the first is read, "Question 1 of N.".
+     * and `set_size` in `extra`. By default (agent key `question_step` `"off"`,
+     * protocol 1.11, runtime 0.32.0) every question of the set is read in
+     * order, "Question k of N."; with `set question_step "on"` only question 1
+     * is read and the others wait for `nextQuestion`.
      */
     ask(channel, kind, text, options, extra = {}) {
         return this.send("ask", defined({ ...extra, channel, kind, text, options }));

package/dist/esm/index.d.ts

@@ -18,4 +18,4 @@ export type { EngineAddOptions, EngineModelsDraft, EngineProfile, SendMode, Engi
 export type { AskKind, AudioMode, ChannelOpenOptions, ChannelPolicy, StreamMessage } from "./extensions.js";
 export { readRuntime, resolveHome } from "./discovery.js";
 export { PROTOCOL, VERSION } from "./version.js";
-export type { ControlAction, EngineStatus, HelloInfo, ItemEvent, ItemPhase, LogEvent, NowPlaying, Reply, RuntimeInfo, SettingKey, SpeakMode, SpeakOptions, State, Voice, } from "./types.js";
+export type { ControlAction, EngineStatus, HelloInfo, ItemEvent, ItemPhase, LogEvent, NowPlaying, Reply, RequestOptions, RuntimeInfo, SettingKey, SpeakMode, SpeakOptions, State, Voice, } from "./types.js";

package/dist/esm/types.d.ts

@@ -14,6 +14,15 @@ export interface SpeakOptions {
     /** Shown in `state.now_playing.label`. */
     label?: string;
 }
+/** Options of one `request`. */
+export interface RequestOptions {
+    /**
+     * Reject with `E_TIMEOUT` when no reply came within this many ms (default:
+     * no bound). The connection stays open and a late reply is dropped.
+     * `engine_test` may take up to a profile's `timeout_ms` (60 s for Gemini).
+     */
+    timeoutMs?: number;
+}
 export interface NowPlaying {
     item_id: number;
     label: string | null;

package/dist/esm/version.d.ts

@@ -1,5 +1,5 @@
 /** Version of this package, sent as `client.version` in `hello`. */
-export declare const VERSION = "0.32.12";
+export declare const VERSION = "0.32.13";
 /** Protocol this client speaks. */
 export declare const PROTOCOL: {
     readonly major: 1;

package/dist/esm/version.js

@@ -1,4 +1,4 @@
 /** Version of this package, sent as `client.version` in `hello`. */
-export const VERSION = "0.32.12";
+export const VERSION = "0.32.13";
 /** Protocol this client speaks. */
 export const PROTOCOL = { major: 1, minor: 0 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sonara/client",
-  "version": "0.32.12",
+  "version": "0.32.13",
   "description": "Client for the Sonara text-to-speech runtime (protocol v1): connect, speak, control, live state. Zero dependencies.",
   "license": "MIT",
   "repository": {