@sonara/client 0.21.6

package/dist/esm/connection.d.ts

@@ -0,0 +1,25 @@
+import type { Reply } from "./types.js";
+/**
+ * One TCP JSON-lines connection to the runtime. Requests carry an `id`;
+ * replies (with `ok`) settle the matching promise, events (with `event`) go
+ * to `onEvent`.
+ */
+export declare class Connection {
+    onEvent: ((event: Record<string, unknown>) => void) | null;
+    onClose: (() => void) | null;
+    private readonly sock;
+    private buf;
+    private nextId;
+    private readonly pending;
+    private closedFlag;
+    private constructor();
+    /** Connect to `127.0.0.1:<port>`; rejects after `timeoutMs`. */
+    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>;
+    close(): void;
+    private onData;
+    private onLine;
+    private finish;
+}

package/dist/esm/connection.js

@@ -0,0 +1,117 @@
+import * as net from "node:net";
+import { SonaraError } from "./errors.js";
+/**
+ * One TCP JSON-lines connection to the runtime. Requests carry an `id`;
+ * replies (with `ok`) settle the matching promise, events (with `event`) go
+ * to `onEvent`.
+ */
+export class Connection {
+    constructor(sock) {
+        this.onEvent = null;
+        this.onClose = null;
+        this.buf = "";
+        this.nextId = 1;
+        this.pending = new Map();
+        this.closedFlag = false;
+        this.sock = sock;
+        sock.setEncoding("utf8");
+        sock.setNoDelay(true);
+        sock.on("data", (chunk) => this.onData(chunk));
+        sock.on("error", () => {
+            // "close" follows and settles everything.
+        });
+        sock.on("close", () => this.finish());
+    }
+    /** Connect to `127.0.0.1:<port>`; rejects after `timeoutMs`. */
+    static open(port, timeoutMs) {
+        return new Promise((resolve, reject) => {
+            const sock = net.connect({ host: "127.0.0.1", port });
+            const timer = setTimeout(() => {
+                sock.destroy();
+                reject(new SonaraError("E_CLOSED", `no connection to 127.0.0.1:${port} within ${timeoutMs} ms`));
+            }, timeoutMs);
+            sock.once("connect", () => {
+                clearTimeout(timer);
+                sock.removeAllListeners("error");
+                resolve(new Connection(sock));
+            });
+            sock.once("error", (err) => {
+                clearTimeout(timer);
+                reject(new SonaraError("E_CLOSED", `cannot connect to 127.0.0.1:${port}: ${err.message}`));
+            });
+        });
+    }
+    get closed() {
+        return this.closedFlag;
+    }
+    /** Send `{type, ...fields}`; resolves with the `ok: true` reply, rejects with a SonaraError. */
+    request(type, fields = {}) {
+        if (this.closedFlag) {
+            return Promise.reject(new SonaraError("E_CLOSED", "the connection is closed"));
+        }
+        const id = this.nextId++;
+        const msg = { ...fields, type, id };
+        return new Promise((resolve, reject) => {
+            this.pending.set(id, { resolve, reject });
+            this.sock.write(JSON.stringify(msg) + "\n");
+        });
+    }
+    close() {
+        this.sock.end();
+        this.sock.destroy();
+        this.finish();
+    }
+    onData(chunk) {
+        this.buf += chunk;
+        let nl;
+        while ((nl = this.buf.indexOf("\n")) >= 0) {
+            const line = this.buf.slice(0, nl).trim();
+            this.buf = this.buf.slice(nl + 1);
+            if (line)
+                this.onLine(line);
+        }
+    }
+    onLine(line) {
+        let msg;
+        try {
+            msg = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        if (typeof msg !== "object" || msg === null)
+            return;
+        const m = msg;
+        if (typeof m.event === "string") {
+            this.onEvent?.(m);
+            return;
+        }
+        if (!("ok" in m))
+            return;
+        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;
+        if (key === undefined)
+            return;
+        const p = this.pending.get(key);
+        this.pending.delete(key);
+        if (m.ok === true) {
+            p.resolve(m);
+        }
+        else {
+            const err = (m.error ?? {});
+            p.reject(new SonaraError(err.code ?? "E_BAD_REQUEST", err.message ?? "request failed", err.reason));
+        }
+    }
+    finish() {
+        if (this.closedFlag)
+            return;
+        this.closedFlag = true;
+        for (const p of this.pending.values()) {
+            p.reject(new SonaraError("E_CLOSED", "the connection closed before the reply"));
+        }
+        this.pending.clear();
+        this.onClose?.();
+    }
+}

package/dist/esm/discovery.d.ts

@@ -0,0 +1,23 @@
+import type { RuntimeInfo } from "./types.js";
+/** The home folder: `home`, else `SONARA_HOME`, else `%LOCALAPPDATA%\Sonara`. */
+export declare function resolveHome(home?: string, env?: NodeJS.ProcessEnv): string;
+/** `runtime.json` of `home`, or null when it is missing or unreadable. */
+export declare function readRuntime(home: string): RuntimeInfo | null;
+/** True while process `pid` exists. */
+export declare function pidAlive(pid: number): boolean;
+/** `runtime.json` of `home` when its pid is alive. */
+export declare function liveRuntime(home: string): RuntimeInfo | null;
+export declare const sleep: (ms: number) => Promise<void>;
+/**
+ * Start `runtimePath --home <home> [...args]` without a console window and
+ * wait up to `timeoutMs` for a `runtime.json` written by it. When another
+ * client started one at the same moment (the new process exits with code 3),
+ * the other's `runtime.json` is used instead.
+ */
+export declare function startRuntime(runtimePath: string, home: string, args: readonly string[], timeoutMs: number): Promise<RuntimeInfo>;
+/**
+ * Wait until process `pid` has ended (after an accepted takeover it releases
+ * the single-instance lock, removes runtime.json and exits). False when it is
+ * still running after `timeoutMs`.
+ */
+export declare function waitExit(pid: number, timeoutMs: number): Promise<boolean>;

package/dist/esm/discovery.js

@@ -0,0 +1,106 @@
+import { spawn } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { SonaraError } from "./errors.js";
+/** Exit code of a second `sonarad` for the same user and home. */
+const EXIT_ALREADY_RUNNING = 3;
+const POLL_MS = 50;
+/** The home folder: `home`, else `SONARA_HOME`, else `%LOCALAPPDATA%\Sonara`. */
+export function resolveHome(home, env = process.env) {
+    if (home)
+        return home;
+    if (env.SONARA_HOME)
+        return env.SONARA_HOME;
+    if (env.LOCALAPPDATA)
+        return join(env.LOCALAPPDATA, "Sonara");
+    throw new SonaraError("E_NOT_RUNNING", "no home folder: pass home, or set SONARA_HOME or LOCALAPPDATA");
+}
+/** `runtime.json` of `home`, or null when it is missing or unreadable. */
+export function readRuntime(home) {
+    try {
+        const info = JSON.parse(readFileSync(join(home, "runtime.json"), "utf8"));
+        if (typeof info.pid !== "number" || typeof info.port !== "number" || typeof info.token !== "string") {
+            return null;
+        }
+        return info;
+    }
+    catch {
+        return null;
+    }
+}
+/** True while process `pid` exists. */
+export function pidAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        // EPERM: it exists but belongs to someone else.
+        return err.code === "EPERM";
+    }
+}
+/** `runtime.json` of `home` when its pid is alive. */
+export function liveRuntime(home) {
+    const info = readRuntime(home);
+    return info && pidAlive(info.pid) ? info : null;
+}
+export const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * Start `runtimePath --home <home> [...args]` without a console window and
+ * wait up to `timeoutMs` for a `runtime.json` written by it. When another
+ * client started one at the same moment (the new process exits with code 3),
+ * the other's `runtime.json` is used instead.
+ */
+export async function startRuntime(runtimePath, home, args, timeoutMs) {
+    let exitCode = null;
+    let spawnError = null;
+    const child = spawn(runtimePath, ["--home", home, ...args], {
+        detached: true,
+        stdio: "ignore",
+        windowsHide: true,
+    });
+    child.on("error", (err) => {
+        spawnError = err;
+    });
+    child.on("exit", (code) => {
+        exitCode = code ?? -1;
+    });
+    // The runtime outlives this process: it is shared and exits on its own
+    // once no client is left.
+    child.unref();
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (spawnError) {
+            throw new SonaraError("E_START_FAILED", `cannot start ${runtimePath}: ${spawnError.message}`);
+        }
+        const info = readRuntime(home);
+        if (info && info.pid === child.pid)
+            return info;
+        if (exitCode !== null) {
+            if (exitCode !== EXIT_ALREADY_RUNNING) {
+                throw new SonaraError("E_START_FAILED", `${runtimePath} exited with code ${exitCode}`);
+            }
+            const other = liveRuntime(home);
+            if (other)
+                return other;
+        }
+        await sleep(POLL_MS);
+    }
+    throw new SonaraError("E_START_FAILED", `${runtimePath} wrote no runtime.json within ${timeoutMs} ms`);
+}
+/**
+ * Wait until process `pid` has ended (after an accepted takeover it releases
+ * the single-instance lock, removes runtime.json and exits). False when it is
+ * still running after `timeoutMs`.
+ */
+export async function waitExit(pid, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (!pidAlive(pid))
+            return true;
+        await sleep(POLL_MS);
+    }
+    return !pidAlive(pid);
+}

package/dist/esm/engines.d.ts

@@ -0,0 +1,99 @@
+/**
+ * External engines (protocol 1.2, capability `engines`): speech engines the
+ * user adds at run time, such as OpenAI or a local OpenAI-compatible server.
+ * Each method sends one core message as is. The profile is named by the
+ * `engine` field (a request's `id` is its correlation id). A runtime that refuses external
+ * engines (`sonarad --no-external-engines`) answers `E_UNSUPPORTED`.
+ *
+ * A key is sent only in `add` (`secret`), `setKey`, or with a draft profile
+ * in `models`; the runtime stores it in Windows Credential Manager (a
+ * draft's only for that request) and never returns it.
+ *
+ * Sonara names no model or voice of its own (protocol 1.5, runtime 0.19.0):
+ * `models` and `voices` list the provider's live, and a profile without one
+ * it needs says so in `engine_list` (`missing`).
+ *
+ * "Send to the engine" (`send_mode`, runtime 0.19.0, #235): `"message"` sends
+ * a whole released message in one request (the default of the cloud kinds),
+ * `"sentence"` each sentence as it comes (the default of a program and a
+ * server on this PC). The view in `engine_list` tells the mode in force, and
+ * `explicit.send_mode` whether the profile chose it.
+ *
+ * A `command` engine (a program on the user's PC) is never added or changed
+ * through the protocol: `add` of one, or replacing one, is `E_FORBIDDEN`
+ * (protocol 1.3). The user adds it locally (`sonara engines add <id> --kind
+ * command`, or `engines.json`); `reload` makes a running runtime read
+ * `engines.json` again. Listing, testing, selecting and removing one work.
+ */
+import type { Reply } from "./types.js";
+export type Send = (type: string, fields: Record<string, unknown>) => Promise<Reply>;
+/** How text goes to an engine (#235): a whole message, or each sentence. */
+export type SendMode = "message" | "sentence";
+/** A profile as sent in `engine_add` (spec section 5). */
+export interface EngineProfile {
+    id: string;
+    kind: string;
+    label?: string;
+    url?: string;
+    model?: string;
+    voice?: string;
+    /** `"none"`, `"credman"` or `"env:NAME"`. */
+    key_ref?: string | null;
+    /** Unset (or null): the kind's default (`message` for the cloud). */
+    send_mode?: SendMode | null;
+    options?: Record<string, unknown>;
+}
+export interface EngineAddOptions {
+    /** Stored in Credential Manager (forces `key_ref` `credman` when unset). */
+    secret?: string;
+    /** Change an existing profile; its stored key is kept unless `secret` is given. */
+    replace?: boolean;
+}
+/** `engine_models` of a profile not saved yet (the key typed in a form). */
+export interface EngineModelsDraft {
+    /** The profile as it would be added (its `id` and `model` may be missing). */
+    profile: Omit<EngineProfile, "id"> & {
+        id?: string;
+    };
+    /** Used for this request only, never stored. */
+    secret?: string;
+}
+export interface EngineTestOptions {
+    text?: string;
+    voice?: string;
+    /** Play it over whatever is read (default true). */
+    play?: boolean;
+}
+export declare class EnginesApi {
+    private readonly send;
+    constructor(send: Send);
+    /** `engine_list`: the profiles, the built-in engines, kinds and presets. */
+    list(): Promise<Reply>;
+    /** `engine_add`. It does not select the engine: `set engine` does. */
+    add(profile: EngineProfile, opts?: EngineAddOptions): Promise<Reply>;
+    /**
+     * `engine_reload` (protocol 1.3): the runtime reads `engines.json` again.
+     * It takes no profile. Replies like `list`, plus `problems`.
+     */
+    reload(): Promise<Reply>;
+    /** `engine_remove`; the stored key goes too unless `forgetKey` is false. */
+    remove(id: string, opts?: {
+        forgetKey?: boolean;
+    }): Promise<Reply>;
+    /** `engine_key`: store a key, or delete it with `null`. */
+    setKey(id: string, secret: string | null): Promise<Reply>;
+    /** `engine_test`: one synthesis with no fallback, at the current rate. */
+    test(id: string, opts?: EngineTestOptions): Promise<Reply>;
+    /**
+     * `engine_models` (protocol 1.5): the provider's models now, of a saved
+     * engine (`refresh` asks the provider again) or of a draft profile.
+     * Replies `{models: [{id, name}], list, takes_model, required, error?}`.
+     */
+    models(engine: string | EngineModelsDraft, opts?: {
+        refresh?: boolean;
+    }): Promise<Reply>;
+    /** `voices` of one engine; `refresh` asks the provider again. */
+    voices(engine: string, opts?: {
+        refresh?: boolean;
+    }): Promise<Reply>;
+}

package/dist/esm/engines.js

@@ -0,0 +1,71 @@
+export class EnginesApi {
+    constructor(send) {
+        this.send = send;
+    }
+    /** `engine_list`: the profiles, the built-in engines, kinds and presets. */
+    list() {
+        return this.send("engine_list", {});
+    }
+    /** `engine_add`. It does not select the engine: `set engine` does. */
+    add(profile, opts = {}) {
+        const fields = { engine: profile };
+        if (opts.secret !== undefined)
+            fields.secret = opts.secret;
+        if (opts.replace !== undefined)
+            fields.replace = opts.replace;
+        return this.send("engine_add", fields);
+    }
+    /**
+     * `engine_reload` (protocol 1.3): the runtime reads `engines.json` again.
+     * It takes no profile. Replies like `list`, plus `problems`.
+     */
+    reload() {
+        return this.send("engine_reload", {});
+    }
+    /** `engine_remove`; the stored key goes too unless `forgetKey` is false. */
+    remove(id, opts = {}) {
+        const fields = { engine: id };
+        if (opts.forgetKey !== undefined)
+            fields.forget_key = opts.forgetKey;
+        return this.send("engine_remove", fields);
+    }
+    /** `engine_key`: store a key, or delete it with `null`. */
+    setKey(id, secret) {
+        return this.send("engine_key", { engine: id, secret });
+    }
+    /** `engine_test`: one synthesis with no fallback, at the current rate. */
+    test(id, opts = {}) {
+        const fields = { engine: id };
+        if (opts.text !== undefined)
+            fields.text = opts.text;
+        if (opts.voice !== undefined)
+            fields.voice = opts.voice;
+        if (opts.play !== undefined)
+            fields.play = opts.play;
+        return this.send("engine_test", fields);
+    }
+    /**
+     * `engine_models` (protocol 1.5): the provider's models now, of a saved
+     * engine (`refresh` asks the provider again) or of a draft profile.
+     * Replies `{models: [{id, name}], list, takes_model, required, error?}`.
+     */
+    models(engine, opts = {}) {
+        if (typeof engine !== "string") {
+            const fields = { profile: engine.profile };
+            if (engine.secret !== undefined)
+                fields.secret = engine.secret;
+            return this.send("engine_models", fields);
+        }
+        const fields = { engine };
+        if (opts.refresh !== undefined)
+            fields.refresh = opts.refresh;
+        return this.send("engine_models", fields);
+    }
+    /** `voices` of one engine; `refresh` asks the provider again. */
+    voices(engine, opts = {}) {
+        const fields = { engine };
+        if (opts.refresh !== undefined)
+            fields.refresh = opts.refresh;
+        return this.send("voices", fields);
+    }
+}

package/dist/esm/errors.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 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.
+ */
+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). */
+ | "E_FORBIDDEN"
+/** No runtime is running and none could be started (autostart off or no runtimePath). */
+ | "E_NOT_RUNNING"
+/** 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 & {});
+/** Any failure of a Sonara call: a coded protocol error or a client-side one. */
+export declare class SonaraError extends Error {
+    readonly code: ErrorCode;
+    /**
+     * Protocol 1.2: why an external engine failed (`auth`, `quota`,
+     * `network`...), on an `E_ENGINE` of `engine_test`.
+     */
+    readonly reason?: string;
+    constructor(code: ErrorCode, message: string, reason?: string);
+}

package/dist/esm/errors.js

@@ -0,0 +1,10 @@
+/** Any failure of a Sonara call: a coded protocol error or a client-side one. */
+export class SonaraError extends Error {
+    constructor(code, message, reason) {
+        super(`${code}: ${message}`);
+        this.name = "SonaraError";
+        this.code = code;
+        if (reason !== undefined)
+            this.reason = reason;
+    }
+}

package/dist/esm/extensions.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Extension namespaces (spec sections 4.2 to 4.4). Each method sends one
+ * protocol message as is; all behaviour lives in the runtime. A runtime that
+ * does not offer the extension (or no client enabled it in `hello`) answers
+ * `E_UNSUPPORTED`. `extra` fields are sent along unchanged, for fields a later
+ * protocol minor adds.
+ */
+import type { ControlAction, Reply, SpeakOptions } from "./types.js";
+export type Send = (type: string, fields: Record<string, unknown>) => Promise<Reply>;
+type Extra = Record<string, unknown>;
+export type ChannelPolicy = "latest" | "queue";
+export interface ChannelOpenOptions {
+    label?: string;
+    host_tab?: string;
+    policy?: ChannelPolicy;
+    /** Keep the label an open channel already has (runtime 0.20.3). */
+    keep_label?: boolean;
+}
+/** `channels`: named sources, each with its own queue and policy. */
+export declare class ChannelsApi {
+    private readonly send;
+    constructor(send: Send);
+    /** `channel_open`. */
+    open(channel: string, opts?: ChannelOpenOptions, extra?: Extra): Promise<Reply>;
+    /** `channel_close`. */
+    close(channel: string, extra?: Extra): Promise<Reply>;
+    /** `focus`: bring a channel to the front. */
+    focus(channel: string, extra?: Extra): Promise<Reply>;
+    /** `speak` on a channel; resolves with the item id. */
+    speak(channel: string, text: string, opts?: SpeakOptions, extra?: Extra): Promise<number>;
+    /** `control` scoped to a channel. */
+    control(channel: string, action: ControlAction | "next_channel", extra?: Extra): Promise<void>;
+    /** `control` `next_channel`. */
+    nextChannel(extra?: Extra): Promise<void>;
+    /** `control` `flush`: stop only the session being read (the flush hotkey, #228). */
+    flush(extra?: Extra): Promise<Reply>;
+}
+export type AskKind = "question" | "permission" | "plan";
+export interface StreamMessage {
+    channel: string;
+    turn: string | number;
+    delta: string;
+    index: number;
+    final: boolean;
+    /** Sender start time, so late text from a previous turn is dropped. */
+    t?: number;
+    [extra: string]: unknown;
+}
+/** `agent` (needs `channels`): streaming turns, decisions, earcons. */
+export declare class AgentApi {
+    private readonly send;
+    constructor(send: Send);
+    /** `stream`: one delta of a turn's text. */
+    stream(msg: StreamMessage): Promise<Reply>;
+    /** `turn_start`. */
+    turnStart(channel: string, turn: string | number, extra?: Extra): Promise<Reply>;
+    /** `turn_end`. */
+    turnEnd(channel: string, turn: string | number, extra?: Extra): Promise<Reply>;
+    /** `ask`: a question, permission or plan, spoken with priority. */
+    ask(channel: string, kind: AskKind, text: string, options?: unknown[], extra?: Extra): Promise<Reply>;
+    /** `earcon`. */
+    earcon(kind: string, extra?: Extra): Promise<Reply>;
+    /** `set mute_level` 0, 1 or 2. */
+    setMuteLevel(level: 0 | 1 | 2): Promise<Reply>;
+    /** `set summaries`. */
+    setSummaries(value: Record<string, unknown>): Promise<Reply>;
+}
+export type AudioMode = "duck" | "pause" | "off";
+/** `system` (Windows): other apps' audio, global hotkeys, the settings page. */
+export declare class SystemApi {
+    private readonly send;
+    constructor(send: Send);
+    /** `set audio_mode`. */
+    setAudioMode(mode: AudioMode): Promise<Reply>;
+    /** `set duck_level`. */
+    setDuckLevel(level: number): Promise<Reply>;
+    /** `set hotkeys`. */
+    setHotkeys(hotkeys: Record<string, unknown>): Promise<Reply>;
+    /** `get settings_url`. */
+    settingsUrl(): Promise<string>;
+}
+export {};

package/dist/esm/extensions.js

@@ -0,0 +1,100 @@
+/** Drop undefined fields so the runtime sees only what the caller set. */
+function defined(fields) {
+    const out = {};
+    for (const [k, v] of Object.entries(fields))
+        if (v !== undefined)
+            out[k] = v;
+    return out;
+}
+/** `channels`: named sources, each with its own queue and policy. */
+export class ChannelsApi {
+    constructor(send) {
+        this.send = send;
+    }
+    /** `channel_open`. */
+    open(channel, opts = {}, extra = {}) {
+        return this.send("channel_open", defined({ ...extra, ...opts, channel }));
+    }
+    /** `channel_close`. */
+    close(channel, extra = {}) {
+        return this.send("channel_close", defined({ ...extra, channel }));
+    }
+    /** `focus`: bring a channel to the front. */
+    focus(channel, extra = {}) {
+        return this.send("focus", defined({ ...extra, channel }));
+    }
+    /** `speak` on a channel; resolves with the item id. */
+    async speak(channel, text, opts = {}, extra = {}) {
+        const r = await this.send("speak", defined({ ...extra, ...opts, text, channel }));
+        return r.item_id;
+    }
+    /** `control` scoped to a channel. */
+    async control(channel, action, extra = {}) {
+        await this.send("control", defined({ ...extra, action, channel }));
+    }
+    /** `control` `next_channel`. */
+    async nextChannel(extra = {}) {
+        await this.send("control", defined({ ...extra, action: "next_channel" }));
+    }
+    /** `control` `flush`: stop only the session being read (the flush hotkey, #228). */
+    flush(extra = {}) {
+        return this.send("control", defined({ ...extra, action: "flush" }));
+    }
+}
+/** `agent` (needs `channels`): streaming turns, decisions, earcons. */
+export class AgentApi {
+    constructor(send) {
+        this.send = send;
+    }
+    /** `stream`: one delta of a turn's text. */
+    stream(msg) {
+        return this.send("stream", defined({ ...msg }));
+    }
+    /** `turn_start`. */
+    turnStart(channel, turn, extra = {}) {
+        return this.send("turn_start", defined({ ...extra, channel, turn }));
+    }
+    /** `turn_end`. */
+    turnEnd(channel, turn, extra = {}) {
+        return this.send("turn_end", defined({ ...extra, channel, turn }));
+    }
+    /** `ask`: a question, permission or plan, spoken with priority. */
+    ask(channel, kind, text, options, extra = {}) {
+        return this.send("ask", defined({ ...extra, channel, kind, text, options }));
+    }
+    /** `earcon`. */
+    earcon(kind, extra = {}) {
+        return this.send("earcon", defined({ ...extra, kind }));
+    }
+    /** `set mute_level` 0, 1 or 2. */
+    setMuteLevel(level) {
+        return this.send("set", { key: "mute_level", value: level });
+    }
+    /** `set summaries`. */
+    setSummaries(value) {
+        return this.send("set", { key: "summaries", value });
+    }
+}
+/** `system` (Windows): other apps' audio, global hotkeys, the settings page. */
+export class SystemApi {
+    constructor(send) {
+        this.send = send;
+    }
+    /** `set audio_mode`. */
+    setAudioMode(mode) {
+        return this.send("set", { key: "audio_mode", value: mode });
+    }
+    /** `set duck_level`. */
+    setDuckLevel(level) {
+        return this.send("set", { key: "duck_level", value: level });
+    }
+    /** `set hotkeys`. */
+    setHotkeys(hotkeys) {
+        return this.send("set", { key: "hotkeys", value: hotkeys });
+    }
+    /** `get settings_url`. */
+    async settingsUrl() {
+        const r = await this.send("get", { key: "settings_url" });
+        return r.value;
+    }
+}