@sonara/client 0.21.6

package/dist/cjs/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @sonara/client: talk to the Sonara runtime (protocol v1) from Node 18+
+ * or an Electron main process. Zero dependencies.
+ *
+ *     const sonara = await connect({ clientName: "my-app", runtimePath });
+ *     sonara.onState((s) => render(s));
+ *     await sonara.speak("Hello.");
+ */
+export { connect } from "./connect.js";
+export type { ConnectOptions } from "./connect.js";
+export { SonaraClient } from "./client.js";
+export type { Unsubscribe } from "./client.js";
+export { SonaraError } from "./errors.js";
+export type { ErrorCode } from "./errors.js";
+export { AgentApi, ChannelsApi, SystemApi } from "./extensions.js";
+export { EnginesApi } from "./engines.js";
+export type { EngineAddOptions, EngineModelsDraft, EngineProfile, SendMode, EngineTestOptions, } from "./engines.js";
+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";

package/dist/cjs/index.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VERSION = exports.PROTOCOL = exports.resolveHome = exports.readRuntime = exports.EnginesApi = exports.SystemApi = exports.ChannelsApi = exports.AgentApi = exports.SonaraError = exports.SonaraClient = exports.connect = void 0;
+/**
+ * @sonara/client: talk to the Sonara runtime (protocol v1) from Node 18+
+ * or an Electron main process. Zero dependencies.
+ *
+ *     const sonara = await connect({ clientName: "my-app", runtimePath });
+ *     sonara.onState((s) => render(s));
+ *     await sonara.speak("Hello.");
+ */
+var connect_js_1 = require("./connect.js");
+Object.defineProperty(exports, "connect", { enumerable: true, get: function () { return connect_js_1.connect; } });
+var client_js_1 = require("./client.js");
+Object.defineProperty(exports, "SonaraClient", { enumerable: true, get: function () { return client_js_1.SonaraClient; } });
+var errors_js_1 = require("./errors.js");
+Object.defineProperty(exports, "SonaraError", { enumerable: true, get: function () { return errors_js_1.SonaraError; } });
+var extensions_js_1 = require("./extensions.js");
+Object.defineProperty(exports, "AgentApi", { enumerable: true, get: function () { return extensions_js_1.AgentApi; } });
+Object.defineProperty(exports, "ChannelsApi", { enumerable: true, get: function () { return extensions_js_1.ChannelsApi; } });
+Object.defineProperty(exports, "SystemApi", { enumerable: true, get: function () { return extensions_js_1.SystemApi; } });
+var engines_js_1 = require("./engines.js");
+Object.defineProperty(exports, "EnginesApi", { enumerable: true, get: function () { return engines_js_1.EnginesApi; } });
+var discovery_js_1 = require("./discovery.js");
+Object.defineProperty(exports, "readRuntime", { enumerable: true, get: function () { return discovery_js_1.readRuntime; } });
+Object.defineProperty(exports, "resolveHome", { enumerable: true, get: function () { return discovery_js_1.resolveHome; } });
+var version_js_1 = require("./version.js");
+Object.defineProperty(exports, "PROTOCOL", { enumerable: true, get: function () { return version_js_1.PROTOCOL; } });
+Object.defineProperty(exports, "VERSION", { enumerable: true, get: function () { return version_js_1.VERSION; } });

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/cjs/types.d.ts

@@ -0,0 +1,111 @@
+/** Queue mode of `speak`: after everything queued, or drop the unread items first. */
+export type SpeakMode = "append" | "replace";
+/** Core playback controls (protocol v1, `control`). */
+export type ControlAction = "play" | "pause" | "toggle" | "stop" | "skip" | "previous" | "next" | "restart" | "mute" | "unmute";
+/** Core setting keys (protocol v1, `set` / `get`). */
+export type SettingKey = "volume" | "rate" | "voice" | "engine";
+export interface SpeakOptions {
+    /** `append` (default) or `replace` (drop unread items, never the current one). */
+    mode?: SpeakMode;
+    /** Also cut the current item and start this one now. */
+    interrupt?: boolean;
+    /** Shown in `state.now_playing.label`. */
+    label?: string;
+}
+export interface NowPlaying {
+    item_id: number;
+    label: string | null;
+    /** The chunk being read. */
+    text: string;
+    chunk: number;
+    chunks: number;
+    [extra: string]: unknown;
+}
+/** A `state` event: a full snapshot, sent on change only. */
+export interface State {
+    seq: number;
+    now_playing: NowPlaying | null;
+    queued: number;
+    paused: boolean;
+    muted: boolean;
+    volume: number;
+    rate: number;
+    voice: string | null;
+    engine_status: EngineStatus;
+    [extra: string]: unknown;
+}
+/**
+ * `state.engine_status`. Protocol 1.1 adds readiness: Kokoro is `loading`,
+ * `downloading` (with `progress`), `waiting` to retry or `unavailable`
+ * until it is `ready`, and names the engine speaking meanwhile in
+ * `fallback`. A 1.0 runtime sends only `engine`.
+ */
+export interface EngineStatus {
+    engine: string;
+    ready?: boolean;
+    status?: "ready" | "loading" | "downloading" | "waiting" | "unavailable";
+    progress?: {
+        done: number;
+        total: number;
+    };
+    fallback?: string;
+    message?: string;
+    /**
+     * Protocol 1.2: why an external engine is not speaking itself
+     * (`no_key`, `auth`, `quota`, `rate_limited`, `network`, `timeout`,
+     * `server`, `bad_voice`, `bad_config`, `format`).
+     */
+    reason?: string;
+    [extra: string]: unknown;
+}
+export type ItemPhase = "started" | "finished" | "skipped" | "failed";
+/** An `item` event. */
+export interface ItemEvent {
+    item_id: number;
+    phase: ItemPhase;
+    [extra: string]: unknown;
+}
+/** A `log` event. */
+export interface LogEvent {
+    message: string;
+    [extra: string]: unknown;
+}
+export interface Voice {
+    id: string;
+    name: string;
+    language: string;
+    engine: string;
+    license_class: "permissive" | "os" | "external";
+    installed: boolean;
+    [extra: string]: unknown;
+}
+/** The `hello` reply: what the runtime offers. */
+export interface HelloInfo {
+    version: string;
+    protocol: {
+        major: number;
+        minor: number;
+    };
+    capabilities: string[];
+    extensions: string[];
+    /** Requested extensions this runtime lacks. */
+    unavailable: string[];
+    [extra: string]: unknown;
+}
+/** Contents of `runtime.json` (protocol v1, Discovery). */
+export interface RuntimeInfo {
+    pid: number;
+    port: number;
+    http_port: number;
+    token: string;
+    version: string;
+    protocol: {
+        major: number;
+        minor: number;
+    };
+    capabilities: string[];
+    started_at: string;
+    [extra: string]: unknown;
+}
+/** Any reply with `ok: true`; the fields depend on the request. */
+export type Reply = Record<string, unknown>;

package/dist/cjs/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/version.d.ts

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

package/dist/cjs/version.js

@@ -0,0 +1,7 @@
+"use strict";
+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.21.6";
+/** Protocol this client speaks. */
+exports.PROTOCOL = { major: 1, minor: 0 };

package/dist/esm/client.d.ts

@@ -0,0 +1,87 @@
+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";
+export type Unsubscribe = () => void;
+type Listener<T> = (value: T) => void;
+/** Opens and greets one more connection (the event connection). */
+export type Dial = () => Promise<Connection>;
+/**
+ * A connected Sonara client. Requests use one connection; events
+ * (`onState`, `onItem`, `onLog`) arrive on a second one, opened on the first
+ * listener and subscribed to every stream.
+ */
+export declare class SonaraClient {
+    /** The runtime's `hello` reply: version, protocol, capabilities, extensions. */
+    readonly info: HelloInfo;
+    /** `runtime.json` of the instance this client talks to. */
+    readonly runtime: Readonly<RuntimeInfo>;
+    /** Extension `channels` (pass-through; needs a runtime that offers it). */
+    readonly channels: ChannelsApi;
+    /** Extension `agent` (pass-through). */
+    readonly agent: AgentApi;
+    /** Extension `system` (pass-through). */
+    readonly system: SystemApi;
+    /** External engines (protocol 1.2, capability `engines`; pass-through). */
+    readonly engines: EnginesApi;
+    private readonly conn;
+    private readonly dial;
+    private eventConn;
+    private eventsOpening;
+    private eventsFailed;
+    /** The newest `state` snapshot, handed to a state listener added later. */
+    private lastState;
+    private closing;
+    private readonly stateListeners;
+    private readonly itemListeners;
+    private readonly logListeners;
+    private readonly closeListeners;
+    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>;
+    /** Add `text` as one item; resolves with its item id. */
+    speak(text: string, opts?: SpeakOptions): Promise<number>;
+    /** Playback control: play, pause, toggle, stop, skip, previous, next, restart, mute, unmute. */
+    control(action: ControlAction): Promise<void>;
+    /** Change a setting; resolves with the value now in force. */
+    set(key: SettingKey, value: unknown): Promise<unknown>;
+    /** Read a setting. */
+    get(key: SettingKey): Promise<unknown>;
+    /**
+     * Voices of one engine, or of all. `refresh` asks an external engine's
+     * provider again (protocol 1.2).
+     */
+    voices(engine?: string, opts?: {
+        refresh?: boolean;
+    }): Promise<Voice[]>;
+    /**
+     * Call `cb` with every `state` snapshot. The first is the current state,
+     * also for a listener added after others: the runtime sends state on
+     * change only, so the latest snapshot is replayed to it (asynchronously).
+     */
+    onState(cb: Listener<State>): Unsubscribe;
+    /** Call `cb` with every `item` event (started, finished, skipped, failed). */
+    onItem(cb: Listener<ItemEvent>): Unsubscribe;
+    /** Call `cb` with every `log` event. */
+    onLog(cb: Listener<LogEvent>): Unsubscribe;
+    /**
+     * Call `cb` once the request connection closes for any reason. A drop of
+     * the event connection alone is reported to `onLog` ("event stream
+     * closed"); the next listener added opens a new one.
+     */
+    onClose(cb: () => void): Unsubscribe;
+    /**
+     * Resolves once the event connection is subscribed (opened by the first
+     * listener), so nothing that follows is missed. Rejects when that failed;
+     * the next listener added tries again.
+     */
+    eventsReady(): Promise<void>;
+    /** Close both connections. The runtime keeps running for other clients and exits on its own when idle. */
+    close(): Promise<void>;
+    private listen;
+    private openEvents;
+    private dispatch;
+}
+export {};

package/dist/esm/client.js

@@ -0,0 +1,192 @@
+import { SonaraError } from "./errors.js";
+import { EnginesApi } from "./engines.js";
+import { AgentApi, ChannelsApi, SystemApi } from "./extensions.js";
+/**
+ * A connected Sonara client. Requests use one connection; events
+ * (`onState`, `onItem`, `onLog`) arrive on a second one, opened on the first
+ * listener and subscribed to every stream.
+ */
+export class SonaraClient {
+    constructor(conn, runtime, info, dial) {
+        this.eventConn = null;
+        this.eventsOpening = null;
+        this.eventsFailed = false;
+        /** The newest `state` snapshot, handed to a state listener added later. */
+        this.lastState = null;
+        this.closing = false;
+        this.stateListeners = new Set();
+        this.itemListeners = new Set();
+        this.logListeners = new Set();
+        this.closeListeners = new Set();
+        this.conn = conn;
+        this.runtime = runtime;
+        this.info = info;
+        this.dial = dial;
+        const send = (type, fields) => this.request(type, fields);
+        this.channels = new ChannelsApi(send);
+        this.agent = new AgentApi(send);
+        this.system = new SystemApi(send);
+        this.engines = new EnginesApi(send);
+        conn.onClose = () => {
+            this.eventConn?.close();
+            for (const cb of [...this.closeListeners])
+                cb();
+        };
+    }
+    /** True once the connection closed (close(), a takeover or the runtime exited). */
+    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);
+    }
+    /** Add `text` as one item; resolves with its item id. */
+    async speak(text, opts = {}) {
+        const fields = { text };
+        if (opts.mode !== undefined)
+            fields.mode = opts.mode;
+        if (opts.interrupt !== undefined)
+            fields.interrupt = opts.interrupt;
+        if (opts.label !== undefined)
+            fields.label = opts.label;
+        const r = await this.request("speak", fields);
+        return r.item_id;
+    }
+    /** Playback control: play, pause, toggle, stop, skip, previous, next, restart, mute, unmute. */
+    async control(action) {
+        await this.request("control", { action });
+    }
+    /** Change a setting; resolves with the value now in force. */
+    async set(key, value) {
+        const r = await this.request("set", { key, value });
+        return r.value;
+    }
+    /** Read a setting. */
+    async get(key) {
+        const r = await this.request("get", { key });
+        return r.value;
+    }
+    /**
+     * Voices of one engine, or of all. `refresh` asks an external engine's
+     * provider again (protocol 1.2).
+     */
+    async voices(engine, opts = {}) {
+        const fields = engine === undefined ? {} : { engine };
+        if (opts.refresh !== undefined)
+            fields.refresh = opts.refresh;
+        const r = await this.request("voices", fields);
+        return r.voices;
+    }
+    /**
+     * Call `cb` with every `state` snapshot. The first is the current state,
+     * also for a listener added after others: the runtime sends state on
+     * change only, so the latest snapshot is replayed to it (asynchronously).
+     */
+    onState(cb) {
+        const off = this.listen(this.stateListeners, cb);
+        const last = this.lastState;
+        if (last) {
+            queueMicrotask(() => {
+                // Skip it when unsubscribed meanwhile or a newer state already came.
+                if (this.stateListeners.has(cb) && this.lastState === last)
+                    cb(last);
+            });
+        }
+        return off;
+    }
+    /** Call `cb` with every `item` event (started, finished, skipped, failed). */
+    onItem(cb) {
+        return this.listen(this.itemListeners, cb);
+    }
+    /** Call `cb` with every `log` event. */
+    onLog(cb) {
+        return this.listen(this.logListeners, cb);
+    }
+    /**
+     * Call `cb` once the request connection closes for any reason. A drop of
+     * the event connection alone is reported to `onLog` ("event stream
+     * closed"); the next listener added opens a new one.
+     */
+    onClose(cb) {
+        this.closeListeners.add(cb);
+        return () => {
+            this.closeListeners.delete(cb);
+        };
+    }
+    /**
+     * Resolves once the event connection is subscribed (opened by the first
+     * listener), so nothing that follows is missed. Rejects when that failed;
+     * the next listener added tries again.
+     */
+    eventsReady() {
+        return this.eventsOpening ?? Promise.resolve();
+    }
+    /** Close both connections. The runtime keeps running for other clients and exits on its own when idle. */
+    async close() {
+        this.closing = true;
+        this.eventConn?.close();
+        this.conn.close();
+    }
+    listen(set, cb) {
+        set.add(cb);
+        // A failed attempt is retried by the next listener.
+        if ((!this.eventsOpening || this.eventsFailed) && !this.closing) {
+            this.eventsFailed = false;
+            this.eventsOpening = this.openEvents();
+            // The failure is reported to log listeners; eventsReady() still rejects.
+            this.eventsOpening.catch(() => undefined);
+        }
+        return () => {
+            set.delete(cb);
+        };
+    }
+    async openEvents() {
+        try {
+            const conn = await this.dial();
+            if (this.closing) {
+                conn.close();
+                return;
+            }
+            this.eventConn = conn;
+            conn.onEvent = (e) => this.dispatch(e);
+            await conn.request("subscribe", { events: ["state", "items", "log"] });
+            // The event connection can drop on its own (the request connection
+            // reports through onClose). Once subscribed, tell log listeners, and
+            // let the next listener open a new one.
+            conn.onClose = () => {
+                if (this.eventConn === conn)
+                    this.eventConn = null;
+                // A new event connection starts with the then current state.
+                this.lastState = null;
+                if (this.closing || this.conn.closed)
+                    return;
+                this.eventsFailed = true;
+                for (const cb of [...this.logListeners])
+                    cb({ message: "event stream closed" });
+            };
+        }
+        catch (err) {
+            this.eventsFailed = true;
+            const message = `event stream failed: ${err.message}`;
+            for (const cb of [...this.logListeners])
+                cb({ message });
+            throw err instanceof SonaraError ? err : new SonaraError("E_CLOSED", message);
+        }
+    }
+    dispatch(e) {
+        const { event, ...body } = e;
+        if (event === "state") {
+            const state = body;
+            this.lastState = state;
+            for (const cb of [...this.stateListeners])
+                cb(state);
+        }
+        else if (event === "item")
+            for (const cb of [...this.itemListeners])
+                cb(body);
+        else if (event === "log")
+            for (const cb of [...this.logListeners])
+                cb(body);
+    }
+}

package/dist/esm/connect.d.ts

@@ -0,0 +1,44 @@
+import { SonaraClient } from "./client.js";
+export interface ConnectOptions {
+    /** Your app's name, sent in `hello` (informational). */
+    clientName: string;
+    /** Your app's version (default: this package's version). */
+    clientVersion?: string;
+    /**
+     * The bundled `sonarad.exe`, started when no usable runtime is running.
+     * Default: `SONARA_RUNTIME` from the environment. With
+     * `@sonara/runtime-win32-x64`: `runtimePath()` from that package.
+     */
+    runtimePath?: string;
+    /** Home folder (default: `SONARA_HOME`, else `%LOCALAPPDATA%\Sonara`). */
+    home?: string;
+    /** Start the bundled runtime when none is usable (default true). */
+    autostart?: boolean;
+    /** Capabilities or extensions this client cannot work without. */
+    require?: string[];
+    /** Extensions to enable (`channels`, `agent`, `system`). */
+    extensions?: string[];
+    /** Keep the runtime running after the last client left. */
+    keepAlive?: boolean;
+    /** Extra command-line arguments for a started runtime (tests: `["--engine", "fake"]`). */
+    runtimeArgs?: string[];
+    /** Wait for a started runtime's `runtime.json` (default 5000 ms). */
+    startTimeoutMs?: number;
+    /** Retry the takeover of a busy, incompatible runtime this long (default 30000 ms). */
+    takeoverTimeoutMs?: number;
+    /** Wait between takeover retries (default 250 ms). */
+    takeoverRetryMs?: number;
+}
+/**
+ * Connect to the shared Sonara runtime (spec section 3):
+ *
+ * 1. Read `runtime.json` in the home; when its pid is alive, connect and
+ *    send `hello`.
+ * 2. Use it when it speaks protocol 1 and offers everything in `require`.
+ * 3. Otherwise (and with `autostart`), start `runtimePath --home <home>`,
+ *    wait up to 5 s for its `runtime.json`, then `hello`.
+ * 4. An incompatible running instance is first asked to step down
+ *    (`hello` with `takeover: true`); while it is busy the takeover is
+ *    retried for up to 30 s, then `E_INCOMPATIBLE`.
+ */
+export declare function connect(opts: ConnectOptions): Promise<SonaraClient>;

package/dist/esm/connect.js

@@ -0,0 +1,154 @@
+import { SonaraClient } from "./client.js";
+import { Connection } from "./connection.js";
+import { liveRuntime, resolveHome, sleep, startRuntime, waitExit } from "./discovery.js";
+import { SonaraError } from "./errors.js";
+import { PROTOCOL, VERSION } from "./version.js";
+const CONNECT_TIMEOUT_MS = 5000;
+const EXIT_WAIT_MS = 5000;
+/** Why an instance cannot serve this client. */
+class Incompatible extends Error {
+}
+/**
+ * Connect to the shared Sonara runtime (spec section 3):
+ *
+ * 1. Read `runtime.json` in the home; when its pid is alive, connect and
+ *    send `hello`.
+ * 2. Use it when it speaks protocol 1 and offers everything in `require`.
+ * 3. Otherwise (and with `autostart`), start `runtimePath --home <home>`,
+ *    wait up to 5 s for its `runtime.json`, then `hello`.
+ * 4. An incompatible running instance is first asked to step down
+ *    (`hello` with `takeover: true`); while it is busy the takeover is
+ *    retried for up to 30 s, then `E_INCOMPATIBLE`.
+ */
+export async function connect(opts) {
+    if (!opts || typeof opts.clientName !== "string" || !opts.clientName) {
+        throw new SonaraError("E_BAD_REQUEST", "connect() needs a clientName");
+    }
+    const home = resolveHome(opts.home);
+    const runtimePath = opts.runtimePath ?? process.env.SONARA_RUNTIME;
+    const canStart = (opts.autostart ?? true) && !!runtimePath;
+    const require = opts.require ?? [];
+    const hello = {
+        client: { name: opts.clientName, version: opts.clientVersion ?? VERSION },
+        protocol: { ...PROTOCOL },
+        require,
+        extensions: opts.extensions ?? [],
+    };
+    if (opts.keepAlive)
+        hello.keep_alive = true;
+    const greeting = { hello, require };
+    const running = liveRuntime(home);
+    if (running) {
+        try {
+            const client = await greet(running, greeting);
+            if (client)
+                return client;
+        }
+        catch (err) {
+            if (!(err instanceof Incompatible))
+                throw err;
+            if (!canStart) {
+                throw new SonaraError("E_INCOMPATIBLE", `the running Sonara ${running.version} cannot serve this client (${err.message}) and there is no runtime to start in its place`);
+            }
+            await takeOver(home, opts, err.message);
+        }
+    }
+    if (!canStart) {
+        throw new SonaraError("E_NOT_RUNNING", runtimePath
+            ? "no Sonara runtime is running and autostart is off"
+            : "no Sonara runtime is running and no runtimePath to start one");
+    }
+    const started = await startRuntime(runtimePath, home, opts.runtimeArgs ?? [], opts.startTimeoutMs ?? 5000);
+    try {
+        const client = await greet(started, greeting);
+        if (client)
+            return client;
+        throw new SonaraError("E_CLOSED", "the started runtime closed the connection");
+    }
+    catch (err) {
+        if (err instanceof Incompatible) {
+            throw new SonaraError("E_INCOMPATIBLE", `the bundled Sonara ${started.version} cannot serve this client: ${err.message}`);
+        }
+        throw err;
+    }
+}
+/**
+ * Connect and send `hello`. Null when the instance cannot be reached (it is
+ * exiting); throws Incompatible when it answers but cannot serve us.
+ */
+async function greet(info, g) {
+    const dial = async () => {
+        const conn = await Connection.open(info.port, CONNECT_TIMEOUT_MS);
+        try {
+            await conn.request("hello", { ...g.hello, token: info.token });
+        }
+        catch (err) {
+            conn.close();
+            throw err;
+        }
+        return conn;
+    };
+    let conn;
+    try {
+        conn = await Connection.open(info.port, CONNECT_TIMEOUT_MS);
+    }
+    catch {
+        return null;
+    }
+    let reply;
+    try {
+        reply = await conn.request("hello", { ...g.hello, token: info.token });
+    }
+    catch (err) {
+        conn.close();
+        if (err instanceof SonaraError && (err.code === "E_INCOMPATIBLE" || err.code === "E_UNSUPPORTED")) {
+            throw new Incompatible(err.message);
+        }
+        if (err instanceof SonaraError && err.code === "E_CLOSED")
+            return null;
+        throw err;
+    }
+    const helloInfo = reply;
+    const offered = new Set([...(helloInfo.capabilities ?? []), ...(helloInfo.extensions ?? [])]);
+    const missing = g.require.filter((r) => !offered.has(r));
+    if (helloInfo.protocol?.major !== PROTOCOL.major || missing.length) {
+        conn.close();
+        throw new Incompatible(missing.length ? `it does not offer ${missing.join(", ")}` : `it speaks protocol ${helloInfo.protocol?.major}`);
+    }
+    return new SonaraClient(conn, info, helloInfo, dial);
+}
+/**
+ * Ask the running instance to exit so the bundled runtime can start. It
+ * accepts only when idle; while it is busy, retry until `takeoverTimeoutMs`.
+ * Each attempt uses a fresh connection: the runtime closes one that has no
+ * successful `hello` within 5 s.
+ */
+async function takeOver(home, opts, why) {
+    const deadline = Date.now() + (opts.takeoverTimeoutMs ?? 30000);
+    const retryMs = opts.takeoverRetryMs ?? 250;
+    const client = { name: opts.clientName, version: opts.clientVersion ?? VERSION };
+    for (;;) {
+        const cur = liveRuntime(home);
+        if (!cur)
+            return;
+        let conn = null;
+        try {
+            conn = await Connection.open(cur.port, CONNECT_TIMEOUT_MS);
+            await conn.request("hello", { token: cur.token, client, takeover: true });
+            conn.close();
+            if (await waitExit(cur.pid, EXIT_WAIT_MS))
+                return;
+        }
+        catch (err) {
+            conn?.close();
+            const code = err instanceof SonaraError ? err.code : "";
+            if (code !== "E_BUSY" && code !== "E_CLOSED") {
+                throw new SonaraError("E_INCOMPATIBLE", `the running Sonara cannot serve this client (${why}) and refused a takeover: ${err.message}`);
+            }
+        }
+        if (Date.now() >= deadline) {
+            throw new SonaraError("E_INCOMPATIBLE", `the running Sonara cannot serve this client (${why}) and stayed busy; gave up the takeover`);
+        }
+        await sleep(retryMs);
+    }
+}