jeopi-cli 16.2.14 → 16.2.15

package/dist/types/ssh/file-transfer.d.ts

@@ -0,0 +1,79 @@
+import { type SSHConnectionTarget } from "./connection-manager";
+export interface RemoteFileReadOptions {
+    /** Maximum bytes to materialize; the helper fetches one extra byte to detect truncation. */
+    maxBytes: number;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}
+export interface RemoteFileReadResult {
+    /** Raw file bytes, capped at `maxBytes`. */
+    bytes: Uint8Array;
+    /** True when the remote file was larger than `maxBytes` (`bytes` is the prefix). */
+    truncated: boolean;
+}
+export interface RemoteFileWriteOptions {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}
+/**
+ * Read a remote file's raw bytes. Fetches `maxBytes + 1` so the caller can
+ * distinguish an exactly-`maxBytes` file from a larger (truncated) one.
+ *
+ * Throws `ptree.NonZeroExitError` (carrying the remote stderr tail) when the
+ * file is missing/unreadable or the host is unreachable.
+ */
+export declare function readRemoteFile(target: SSHConnectionTarget, remotePath: string, opts: RemoteFileReadOptions): Promise<RemoteFileReadResult>;
+/**
+ * Write `content` to a remote file byte-exact. Stdin is always staged first into
+ * a uniquely named temp in the destination directory (so the remote never blocks
+ * on an unread pipe and a dropped connection lands in the temp, never the
+ * destination). The destination then dictates the commit:
+ *  - a directory — or a symlink to one, since the `-d` test follows links — is
+ *    refused (a plain `mv tmp dir` would move the temp INTO it).
+ *  - an existing non-symlink regular file is rewritten IN PLACE from the staged
+ *    temp, preserving its inode and therefore its ordinary permission bits (a
+ *    `0600` secret stays `0600` on overwrite), ACLs, xattrs, and hardlinks. The
+ *    setuid/setgid bits may be cleared by the write (per POSIX). This commit is
+ *    not fully atomic — a remote-side failure during the local temp->dest copy
+ *    (e.g. the disk filling) can truncate the destination — but the slow network
+ *    transfer has already landed in the temp, and the temp is removed on failure.
+ *    It also needs write permission on the file itself (a read-only file is
+ *    refused, not silently replaced).
+ *  - an existing special file (FIFO/socket/device) is refused, not replaced.
+ *  - anything else (a new path, a symlink to a non-directory, a dangling symlink)
+ *    is committed with an atomic rename, which REPLACES a symlink with a regular
+ *    file rather than writing through it (resolving the link target is not
+ *    portable across the macOS/Linux hosts this stack supports).
+ * Throws `ptree.NonZeroExitError` when the remote path is unwritable or the host
+ * is unreachable.
+ */
+export declare function writeRemoteFile(target: SSHConnectionTarget, remotePath: string, content: Uint8Array, opts: RemoteFileWriteOptions): Promise<void>;
+/** Classification of a remote path, used by the read handler's directory dispatch. */
+export type RemotePathKind = "file" | "directory" | "other" | "missing";
+/**
+ * Classify a remote path with POSIX `test` (portable across Linux/BSD/macOS):
+ * `directory`, regular `file`, `other` (special file), or `missing`.
+ */
+export declare function statRemotePath(target: SSHConnectionTarget, remotePath: string, opts?: {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}): Promise<RemotePathKind>;
+/** A single entry in a remote directory listing. */
+export interface RemoteDirEntry {
+    /** Entry name (no path component), trailing `/` stripped. */
+    name: string;
+    /** True when the entry is a directory. */
+    isDirectory: boolean;
+}
+/**
+ * List a remote directory one level deep with `ls -1Ap` (one per line; all
+ * entries incl. dotfiles but not `.`/`..`; trailing `/` marks directories).
+ * Plain `ls` (no `| head`) so a permission/race failure surfaces as a non-zero
+ * exit instead of being masked as an empty listing. Entries are returned in
+ * full, sorted directories-first then by name to mirror the local
+ * directory-resource contract, so the read tool can paginate the listing.
+ */
+export declare function listRemoteDir(target: SSHConnectionTarget, remotePath: string, opts?: {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}): Promise<RemoteDirEntry[]>;

package/dist/types/ssh/ssh-executor.d.ts

@@ -0,0 +1,37 @@
+import { type SSHConnectionTarget } from "./connection-manager";
+export interface SSHExecutorOptions {
+    /** Timeout in milliseconds */
+    timeout?: number;
+    /** Callback for streaming output chunks (already sanitized) */
+    onChunk?: (chunk: string) => void;
+    /** AbortSignal for cancellation */
+    signal?: AbortSignal;
+    /** Remote path to mount when sshfs is available */
+    remotePath?: string;
+    /** Wrap commands in a POSIX shell for compat mode */
+    compatEnabled?: boolean;
+    /** Artifact path/id for full output storage */
+    artifactPath?: string;
+    artifactId?: string;
+}
+export interface SSHResult {
+    /** Combined stdout + stderr output (sanitized, possibly truncated) */
+    output: string;
+    /** Process exit code (undefined if killed/cancelled) */
+    exitCode: number | undefined;
+    /** Whether the command was cancelled via signal */
+    cancelled: boolean;
+    /** Whether the output was truncated */
+    truncated: boolean;
+    /** Total number of lines in the output stream */
+    totalLines: number;
+    /** Total number of bytes in the output stream */
+    totalBytes: number;
+    /** Number of lines included in the output text */
+    outputLines: number;
+    /** Number of bytes included in the output text */
+    outputBytes: number;
+    /** Artifact ID if full output was saved to artifact storage */
+    artifactId?: string;
+}
+export declare function executeSSH(host: SSHConnectionTarget, command: string, options?: SSHExecutorOptions): Promise<SSHResult>;

package/dist/types/ssh/sshfs-mount.d.ts

@@ -0,0 +1,6 @@
+import { type SSHConnectionTarget } from "./connection-manager";
+export declare function hasSshfs(): boolean;
+export declare function isMounted(path: string): Promise<boolean>;
+export declare function mountRemote(host: SSHConnectionTarget, remotePath?: string): Promise<string | undefined>;
+export declare function unmountRemote(host: SSHConnectionTarget): Promise<boolean>;
+export declare function unmountAll(): Promise<void>;

package/dist/types/ssh/utils.d.ts

@@ -0,0 +1,24 @@
+export declare function sanitizeHostName(name: string): string;
+export declare function buildSshTarget(username: string | undefined, host: string): string;
+/**
+ * Single-quote a path for a POSIX remote shell, escaping embedded single quotes.
+ * Mirrors the private `quoteRemotePath` in `tools/ssh.ts`; shared here for the
+ * `ssh://` file-transfer helpers.
+ */
+export declare function quotePosixPath(value: string): string;
+/**
+ * Wrap a POSIX command in `<shell> -c '<command>'` so it runs under the
+ * named shell rather than whatever `$SHELL` happens to be on the remote.
+ *
+ * Used by the `ssh://` transfer helpers and the Windows compat dispatch:
+ * OpenSSH passes our snippets to `<login-shell> -c`, so a remote whose
+ * login shell is fish/csh/tcsh (or cmd/powershell on Windows compat)
+ * can't parse `if [ … ]; then …`. Wrapping forces parsing under the
+ * shell OMP actually verified can run the snippet.
+ *
+ * `-c` (not `-lc`): the transfer snippets only call absolute POSIX
+ * builtins (`head`/`cat`/`mv`/`test`/`ls`/`mkdir`/`rm`/`dirname`) and
+ * don't need login-profile setup. Capability *probing* still uses
+ * `-lc` to mirror the user's real environment.
+ */
+export declare function wrapInPosixShell(shell: "sh" | "bash" | "zsh", command: string): string;

package/dist/types/startup-splash.d.ts

@@ -0,0 +1,12 @@
+/** Inputs used to decide whether the optional startup splash may run for this process. */
+export interface StartupSplashDecisionOptions {
+    readonly configured: boolean;
+    readonly isInteractive: boolean;
+    readonly resuming: boolean;
+    readonly quiet: boolean;
+    readonly timing: boolean;
+    readonly stdinIsTTY: boolean | undefined;
+    readonly stdoutIsTTY: boolean | undefined;
+}
+/** Returns true only for explicitly enabled, normal interactive TTY startup. */
+export declare function shouldShowStartupSplash(options: StartupSplashDecisionOptions): boolean;

package/dist/types/stt/asr-client.d.ts

@@ -0,0 +1,68 @@
+import { type RefCountedWorkerHandle, type SpawnedSubprocess } from "../subprocess/worker-client";
+import type { SttProgressEvent, SttWorkerInbound, SttWorkerOutbound } from "./asr-protocol";
+import type { SttModelKey } from "./models";
+export interface SttTranscribeOptions {
+    language?: string;
+    signal?: AbortSignal;
+}
+export interface SttDownloadOptions {
+    signal?: AbortSignal;
+    onProgress?: (event: SttProgressEvent) => void;
+}
+export interface SttDownloadResult {
+    ok: boolean;
+    error?: string;
+}
+/** Live streaming session handle returned by {@link SttClient.startStream}. */
+export interface SttStreamHandle {
+    /** Feed 16 kHz mono float samples as the recorder produces them. */
+    pushAudio(audio: Float32Array): void;
+    /** Flush the trailing segment and resolve with the full joined transcript. */
+    stop(): Promise<string>;
+    /** Tear the session down without a final flush (resolves `stop()` with ""). */
+    cancel(): void;
+}
+export interface SttStreamOptions {
+    language?: string;
+    signal?: AbortSignal;
+    /** Volatile transcript of the in-progress segment, refreshed as audio arrives. */
+    onPartial?: (text: string) => void;
+    /** A finalized segment, emitted once when the endpointer commits it. */
+    onSegment?: (text: string, index: number) => void;
+}
+/**
+ * Hidden subcommand on the main CLI that boots the speech-recognition worker in
+ * the spawned subprocess. Kept in sync with the dispatch in `cli.ts`.
+ */
+export declare const STT_WORKER_ARG = "__omp_worker_stt";
+/**
+ * Spawn the speech worker as a subprocess. Exported for tests and the smoke
+ * probe; production callers go through {@link spawnSttWorker}.
+ */
+export declare function createSttSubprocess(): SpawnedSubprocess<SttWorkerOutbound>;
+export declare class SttClient {
+    #private;
+    constructor(spawnWorker?: () => RefCountedWorkerHandle<SttWorkerInbound, SttWorkerOutbound>);
+    onProgress(listener: (event: SttProgressEvent) => void): () => void;
+    /**
+     * Transcribe 16 kHz mono audio on the warm worker. Rejects with the worker
+     * error on failure and with an `AbortError` when the signal fires (the warm
+     * worker keeps the model loaded across calls — the model is never reloaded).
+     */
+    transcribe(modelKey: SttModelKey, audio: Float32Array, options?: SttTranscribeOptions): Promise<string>;
+    /**
+     * Open a live streaming session on the warm worker. Audio fed through the
+     * returned handle is segmented by the worker's endpointer: `onSegment` fires
+     * once per committed segment and `onPartial` for the volatile in-progress
+     * preview. `stop()` resolves with the full joined transcript; `cancel()` (or
+     * an aborted signal) tears the session down and resolves `stop()` with "".
+     */
+    startStream(modelKey: SttModelKey, options?: SttStreamOptions): SttStreamHandle;
+    downloadModel(modelKey: SttModelKey, options?: SttDownloadOptions): Promise<SttDownloadResult>;
+    terminate(): Promise<void>;
+}
+export declare const sttClient: SttClient;
+export declare function shutdownSttClient(): Promise<void>;
+export declare function smokeTestSttWorker({ timeoutMs, }?: {
+    timeoutMs?: number;
+}): Promise<void>;

package/dist/types/stt/asr-protocol.d.ts

@@ -0,0 +1,97 @@
+import type { SttModelKey } from "./models";
+export type SttProgressStatus = "initiate" | "download" | "progress" | "progress_total" | "done" | "ready" | "error";
+export interface SttProgressFileState {
+    loaded: number;
+    total: number;
+}
+export interface SttProgressEvent {
+    modelKey: SttModelKey;
+    status: SttProgressStatus;
+    name?: string;
+    file?: string;
+    progress?: number;
+    loaded?: number;
+    total?: number;
+    files?: Record<string, SttProgressFileState>;
+    task?: string;
+    model?: string;
+}
+export type SttWorkerInbound = {
+    type: "ping";
+    id: string;
+} | {
+    type: "transcribe";
+    id: string;
+    modelKey: SttModelKey;
+    audio: Float32Array;
+    language?: string;
+} | {
+    type: "download";
+    id: string;
+    modelKey: SttModelKey;
+} | {
+    type: "stream_start";
+    id: string;
+    modelKey: SttModelKey;
+    language?: string;
+} | {
+    type: "stream_audio";
+    id: string;
+    audio: Float32Array;
+} | {
+    type: "stream_stop";
+    id: string;
+} | {
+    type: "stream_cancel";
+    id: string;
+};
+export type SttWorkerOutbound = {
+    type: "pong";
+    id: string;
+} | {
+    type: "transcription";
+    id: string;
+    text: string;
+} | {
+    type: "downloaded";
+    id: string;
+} | {
+    type: "error";
+    id: string;
+    error: string;
+} | {
+    type: "progress";
+    id: string;
+    event: SttProgressEvent;
+} | {
+    type: "log";
+    level: "debug" | "warn" | "error";
+    msg: string;
+    meta?: Record<string, unknown>;
+} | {
+    type: "partial";
+    id: string;
+    text: string;
+} | {
+    type: "segment";
+    id: string;
+    index: number;
+    text: string;
+} | {
+    type: "stream_done";
+    id: string;
+    text: string;
+};
+/**
+ * Wire transport between the parent (`SttClient`) and the speech-recognition
+ * subprocess. The parent owns the subprocess lifecycle (graceful work, hard
+ * SIGKILL on shutdown); the protocol therefore carries no explicit close
+ * handshake — once the parent decides to terminate, it signals the OS to reap
+ * the child so `onnxruntime-node`'s NAPI finalizer never runs in any shared
+ * address space (the destructor segfaults Bun on shutdown; issue #1606). See
+ * `asr-client.ts` for the spawn/kill glue.
+ */
+export interface SttTransport {
+    send(message: SttWorkerOutbound): void;
+    onMessage(handler: (message: SttWorkerInbound) => void): () => void;
+}

package/dist/types/stt/asr-worker.d.ts

@@ -0,0 +1,2 @@
+import type { SttTransport } from "./asr-protocol";
+export declare function startSttWorker(transport: SttTransport): void;

package/dist/types/stt/downloader.d.ts

@@ -0,0 +1,47 @@
+import type { SttProgressStatus } from "./asr-protocol";
+export interface DownloadProgress {
+    stage: string;
+    percent?: number;
+}
+export interface EnsureOptions {
+    modelName?: string;
+    signal?: AbortSignal;
+    onProgress?: (progress: DownloadProgress) => void;
+}
+/**
+ * Real-progress event for a speech-model download, surfaced to UI callers.
+ * `percent` is an integer 0–100 aggregated across all model files (encoder +
+ * decoder shards), so it advances monotonically toward completion.
+ */
+export interface SttDownloadProgress {
+    status: SttProgressStatus;
+    /** Integer 0–100 aggregated across files. */
+    percent: number;
+    /** Bytes downloaded so far across all files. */
+    loaded: number;
+    /** Total bytes across all files seen so far. */
+    total: number;
+    /** The file currently downloading, when known. */
+    file?: string;
+    repo: string;
+    label: string;
+}
+/**
+ * Whether the selected model is fully present in the local cache. For
+ * transformers.js Whisper tiers a complete download leaves `config.json` plus
+ * matching `encoder*.onnx` and `decoder*.onnx` shards under `onnx/` (a partial
+ * fetch with only one shard, or a bare `config.json`, reads as not-cached); for
+ * sherpa-onnx tiers every model file (encoder/decoder/joiner + tokens) must be
+ * present (`.part` sidecars from an interrupted fetch are ignored).
+ */
+export declare function isSttModelCached(key: string): Promise<boolean>;
+/**
+ * Download (or warm from cache) the selected ONNX Whisper model via the speech
+ * worker, resolving once the model is fully present and loaded. Streams real
+ * Hub progress with an aggregated integer percent. Rejects if the worker cannot
+ * obtain the model. Safe to call non-interactively.
+ */
+export declare function downloadSttModel(key: string, onProgress?: (progress: SttDownloadProgress) => void, options?: {
+    signal?: AbortSignal;
+}): Promise<void>;
+export declare function ensureSTTDependencies(options?: EnsureOptions): Promise<void>;

package/dist/types/stt/endpointer.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Energy-based speech endpointer for live transcription.
+ *
+ * The on-device ASR models we ship are non-streaming: the sherpa-onnx Parakeet
+ * recognizer and the transformers.js Whisper pipelines both decode a complete
+ * waveform in one shot. To transcribe *while the user is still speaking*, this
+ * splits the continuous 16 kHz mono float stream into speech segments at natural
+ * pauses — each segment is decoded and committed as it finalizes, and the
+ * in-progress segment is re-decoded periodically for a volatile live preview.
+ *
+ * Segmentation is pure short-time-energy VAD with an adaptive noise floor, so it
+ * needs no extra model and is engine-agnostic (it runs the same way whether the
+ * downstream model is sherpa or transformers). It is deliberately simple and
+ * fully deterministic so it can be unit-tested with synthetic signals.
+ */
+/** Tunable thresholds for {@link StreamEndpointer}. All durations in ms. */
+export interface EndpointerConfig {
+    /** Input sample rate (the recorder always delivers 16 kHz mono). */
+    sampleRate: number;
+    /** Short-time analysis frame size. */
+    frameMs: number;
+    /** Trailing silence inside a segment that finalizes (commits) it. */
+    endSilenceMs: number;
+    /** Shortest speech run that is committed; shorter runs are discarded as noise. */
+    minSpeechMs: number;
+    /** Hard cap on segment length so long pause-free speech still commits periodically. */
+    maxSegmentMs: number;
+    /** Audio retained before onset so the first phoneme of a segment is never clipped. */
+    preRollMs: number;
+    /** Cadence of volatile partial emissions for the in-progress segment. */
+    partialIntervalMs: number;
+    /** Speech threshold is `max(minThreshold, noiseFloor * energyRatio)`. */
+    energyRatio: number;
+    /** EMA weight tracking the ambient noise floor on non-speech frames. */
+    floorAttack: number;
+    /** Absolute RMS floor so a near-silent room never trips speech detection. */
+    minThreshold: number;
+}
+export declare const DEFAULT_ENDPOINTER_CONFIG: EndpointerConfig;
+/**
+ * Emitted by {@link StreamEndpointer.push} / {@link StreamEndpointer.flush}.
+ * `partial` is the volatile in-progress segment (decode and show as preview,
+ * never commit); `segment` is a finalized run (decode and commit once).
+ */
+export type EndpointerEvent = {
+    kind: "partial";
+    audio: Float32Array;
+} | {
+    kind: "segment";
+    audio: Float32Array;
+};
+export declare class StreamEndpointer {
+    #private;
+    constructor(config?: Partial<EndpointerConfig>);
+    /** Feed newly-captured samples; returns ordered partial/segment events. */
+    push(samples: Float32Array): EndpointerEvent[];
+    /** End the stream; returns a trailing committed segment if one is pending. */
+    flush(): EndpointerEvent[];
+}

package/dist/types/stt/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./asr-client";
+export * from "./asr-protocol";
+export * from "./downloader";
+export * from "./models";
+export * from "./stt-controller";
+export * from "./submit-trigger";
+export * from "./transcriber";
+export * from "./wav";

package/dist/types/stt/models.d.ts

@@ -0,0 +1,120 @@
+import type { TinyModelDtype } from "../tiny/dtype";
+/**
+ * On-device speech-to-text model registry. Each tier maps a stable settings key
+ * onto a locally-runnable ASR model and the engine that loads it:
+ *
+ * - `transformers` — a transformers.js / ONNX Whisper repo, loaded by the
+ *   `@huggingface/transformers` `automatic-speech-recognition` pipeline.
+ * - `sherpa` — a sherpa-onnx (Next-gen Kaldi) offline model, loaded by the
+ *   native `sherpa-onnx-node` addon. Used for NVIDIA Parakeet, the Open ASR
+ *   Leaderboard accuracy/speed leader.
+ *
+ * The worker resolves the spec by key and loads the model lazily (kept warm
+ * afterwards). Both engines run inside the hard-killed subprocess worker.
+ */
+/** ASR runtime that loads a given tier's model. */
+export type SttEngine = "transformers" | "sherpa";
+interface SttModelBase {
+    /** Stable key persisted in `stt.modelName` and sent over the worker protocol. */
+    key: string;
+    engine: SttEngine;
+    /** Hugging Face repo id (transformers.js ONNX repo, or sherpa-onnx model repo). */
+    repo: string;
+    /** English-only checkpoint: rejects a configured source `language`. */
+    englishOnly: boolean;
+    label: string;
+    description: string;
+    /** Approximate on-disk download size for the shipped weights (UI hint). */
+    sizeHint: string;
+}
+/** A Whisper-family tier loaded via the transformers.js ASR pipeline. */
+export interface TransformersSttModelSpec extends SttModelBase {
+    engine: "transformers";
+    /** ONNX precision used unless overridden by `PI_TINY_DTYPE` / `providers.tinyModelDtype`. */
+    dtype: TinyModelDtype;
+}
+/** A sherpa-onnx offline tier (e.g. NeMo Parakeet transducer) loaded natively. */
+export interface SherpaSttModelSpec extends SttModelBase {
+    engine: "sherpa";
+    /** sherpa-onnx offline model family (e.g. `nemo_transducer`). */
+    modelType: string;
+    /** Model files (relative to the repo root) fetched into the local cache. */
+    files: {
+        encoder: string;
+        decoder: string;
+        joiner: string;
+        tokens: string;
+    };
+}
+export type SttModelSpec = TransformersSttModelSpec | SherpaSttModelSpec;
+/**
+ * Speech model tiers, ordered light → SoTA. Defaults to {@link DEFAULT_STT_MODEL_KEY}.
+ * `fast`/`balanced`/`turbo` are multilingual Whisper checkpoints on transformers.js;
+ * `parakeet` is NVIDIA Parakeet TDT 0.6B v3 on sherpa-onnx — the Open ASR
+ * Leaderboard leader (lower WER and far higher throughput than Whisper).
+ */
+export declare const STT_MODELS: readonly [{
+    readonly key: "fast";
+    readonly engine: "transformers";
+    readonly repo: "onnx-community/whisper-base";
+    readonly dtype: "q8";
+    readonly englishOnly: false;
+    readonly label: "Fast (Whisper base)";
+    readonly description: "Whisper base, multilingual. Smallest + fastest; lowest accuracy. Best for low-resource machines.";
+    readonly sizeHint: "~60 MB";
+}, {
+    readonly key: "balanced";
+    readonly engine: "transformers";
+    readonly repo: "onnx-community/whisper-small";
+    readonly dtype: "q8";
+    readonly englishOnly: false;
+    readonly label: "Balanced (Whisper small)";
+    readonly description: "Whisper small, multilingual. More accurate than Fast, still light on CPU/RAM.";
+    readonly sizeHint: "~190 MB";
+}, {
+    readonly key: "turbo";
+    readonly engine: "transformers";
+    readonly repo: "onnx-community/whisper-large-v3-turbo";
+    readonly dtype: "q4";
+    readonly englishOnly: false;
+    readonly label: "Turbo (Whisper large-v3)";
+    readonly description: "Whisper large-v3-turbo, 99 languages. Widest language coverage; large download, slower.";
+    readonly sizeHint: "~600 MB";
+}, {
+    readonly key: "parakeet";
+    readonly engine: "sherpa";
+    readonly repo: "csukuangfj/sherpa-onnx-nemo-parakeet-tdt-0.6b-v3-int8";
+    readonly modelType: "nemo_transducer";
+    readonly files: {
+        readonly encoder: "encoder.int8.onnx";
+        readonly decoder: "decoder.int8.onnx";
+        readonly joiner: "joiner.int8.onnx";
+        readonly tokens: "tokens.txt";
+    };
+    readonly englishOnly: false;
+    readonly label: "Parakeet TDT v3 (SoTA)";
+    readonly description: "NVIDIA Parakeet TDT 0.6B v3, 25 languages. Open ASR Leaderboard leader — best accuracy and far fastest decoding. Default.";
+    readonly sizeHint: "~680 MB";
+}];
+/**
+ * SoTA default — NVIDIA Parakeet TDT 0.6B v3 (sherpa-onnx). Tops the Open ASR
+ * Leaderboard on accuracy while decoding ~20× faster than Whisper large-v3.
+ */
+export declare const DEFAULT_STT_MODEL_KEY = "parakeet";
+export type SttModelKey = (typeof STT_MODELS)[number]["key"];
+/** A concrete entry from {@link STT_MODELS}; `key` is the literal tier union. */
+export type SttModel = (typeof STT_MODELS)[number];
+export declare const STT_MODEL_VALUES: readonly ["fast", "balanced", "turbo", "parakeet"];
+export declare const STT_MODEL_OPTIONS: {
+    value: "balanced" | "fast" | "parakeet" | "turbo";
+    label: "Balanced (Whisper small)" | "Fast (Whisper base)" | "Parakeet TDT v3 (SoTA)" | "Turbo (Whisper large-v3)";
+    description: "NVIDIA Parakeet TDT 0.6B v3, 25 languages. Open ASR Leaderboard leader — best accuracy and far fastest decoding. Default." | "Whisper base, multilingual. Smallest + fastest; lowest accuracy. Best for low-resource machines." | "Whisper large-v3-turbo, 99 languages. Widest language coverage; large download, slower." | "Whisper small, multilingual. More accurate than Fast, still light on CPU/RAM.";
+}[];
+export declare function isSttModelKey(value: string): value is SttModelKey;
+export declare function getSttModelSpec(key: string): SttModel | undefined;
+/**
+ * Resolve a (possibly stale or legacy) `stt.modelName` value onto a concrete
+ * spec, falling back to the SoTA default when the key is unknown.
+ */
+export declare function resolveSttModelSpec(key: string | undefined): SttModel;
+export {};

package/dist/types/stt/recorder.d.ts

@@ -0,0 +1,30 @@
+export interface RecordingHandle {
+    stop(): Promise<void>;
+}
+/**
+ * Returns available recording tools in priority order.
+ */
+export declare function detectRecordingTools(): string[];
+export interface ResolvedRecorder {
+    tool: "sox" | "ffmpeg" | "arecord" | "powershell";
+    bin: string;
+}
+export declare function detectRecorder(): ResolvedRecorder | null;
+/**
+ * Ensure a recorder is available, downloading the static ffmpeg binary when
+ * nothing is already present. Returns the resolved recorder.
+ */
+export declare function ensureRecorder(onProgress?: (p: {
+    stage: string;
+    percent?: number;
+}) => void, signal?: AbortSignal): Promise<ResolvedRecorder>;
+export declare function startRecording(outputPath: string): Promise<RecordingHandle>;
+/**
+ * Verify a recorded audio file is usable.
+ * Returns the file size in bytes, or throws.
+ */
+export declare function verifyRecordingFile(filePath: string): Promise<number>;
+export interface StreamingRecordingHandle {
+    stop(): Promise<void>;
+}
+export declare function startStreamingRecording(onAudio: (samples: Float32Array) => void): Promise<StreamingRecordingHandle | null>;

package/dist/types/stt/stt-controller.d.ts

@@ -0,0 +1,24 @@
+export type SttState = "idle" | "recording" | "transcribing";
+interface ToggleOptions {
+    showWarning(msg: string): void;
+    showStatus(msg: string): void;
+    onStateChange(state: SttState): void;
+    /** Force a redraw after async edits to the composer (live segment/preview inserts). */
+    requestRender?(): void;
+}
+/** The slice of the composer editor the controller drives. */
+interface Editor {
+    insertText(text: string): void;
+    setVolatileText(text: string): void;
+    clearVolatileText(): void;
+    commitVolatileText(text: string): void;
+    submit(): void;
+    deleteBeforeCursor(count: number): void;
+}
+export declare class STTController {
+    #private;
+    get state(): SttState;
+    toggle(editor: Editor, options: ToggleOptions): Promise<void>;
+    dispose(): void;
+}
+export {};

package/dist/types/stt/submit-trigger.d.ts

@@ -0,0 +1,30 @@
+/**
+ * TTS/STT Submit Trigger options and evaluation logic.
+ */
+export declare const STT_SUBMIT_TRIGGER_VALUES: readonly ["never", "release", "release-complete", "say-submit"];
+export type SttSubmitTrigger = (typeof STT_SUBMIT_TRIGGER_VALUES)[number];
+export declare const STT_SUBMIT_TRIGGER_OPTIONS: ({
+    value: "never";
+    label: string;
+    description: string;
+} | {
+    value: "release";
+    label: string;
+    description: string;
+} | {
+    value: "release-complete";
+    label: string;
+    description: string;
+} | {
+    value: "say-submit";
+    label: string;
+    description: string;
+})[];
+/**
+ * Evaluate the submit trigger against a transcribed utterance.
+ * Returns whether to submit, and the number of characters to trim from the end of the utterance.
+ */
+export declare function evaluateSubmitTrigger(utterance: string, trigger: SttSubmitTrigger): {
+    submit: boolean;
+    trimTrailing: number;
+};