@oh-my-pi/pi-coding-agent 15.12.3 → 15.13.0

package/dist/types/session/session-migrations.d.ts

@@ -0,0 +1,12 @@
+import { type FileEntry } from "./session-entries";
+/** Generate a unique short ID (8 hex chars, collision-checked) */
+export declare function generateId(byId: {
+    has(id: string): boolean;
+}): string;
+/**
+ * Run all necessary migrations to bring entries to current version.
+ * Mutates entries in place. Returns true if any migration was applied.
+ */
+export declare function migrateToCurrentVersion(entries: FileEntry[]): boolean;
+/** Exported for testing */
+export declare function migrateSessionEntries(entries: FileEntry[]): void;

package/dist/types/session/session-paths.d.ts

@@ -0,0 +1,25 @@
+import type { SessionStorage } from "./session-storage";
+export declare function resolveManagedSessionRoot(sessionDir: string, cwd: string): string | undefined;
+/**
+ * Compute the default session directory for a cwd.
+ * Classifies cwd by canonical location so symlink/alias paths resolve to the
+ * same home-relative or temp-root directory names as their real targets.
+ */
+export declare function computeDefaultSessionDir(cwd: string, storage: SessionStorage, sessionsRoot?: string): string;
+/**
+ * Write a breadcrumb linking the current terminal to a session file.
+ * The breadcrumb contains the cwd and session path so --continue can
+ * find "this terminal's last session" even when running concurrent instances.
+ */
+export declare function writeTerminalBreadcrumb(cwd: string, sessionFile: string): void;
+export interface TerminalBreadcrumb {
+    cwd: string;
+    sessionFile: string;
+}
+/**
+ * Read the raw terminal breadcrumb for the current terminal.
+ * Returns the recorded cwd + session file (verified to exist) regardless of
+ * whether the recorded cwd still matches the current one. Callers decide how
+ * to interpret a cwd mismatch (e.g. a moved/renamed worktree).
+ */
+export declare function readTerminalBreadcrumbEntry(): Promise<TerminalBreadcrumb | null>;

package/dist/types/session/session-persistence.d.ts

@@ -0,0 +1,8 @@
+import { type BlobStore } from "./blob-store";
+import type { FileEntry } from "./session-entries";
+export declare function isImageBlock(value: unknown): value is {
+    type: "image";
+    data: string;
+    mimeType?: string;
+};
+export declare function prepareEntryForPersistence(entry: FileEntry, blobStore: BlobStore): FileEntry;

package/dist/types/session/session-storage.d.ts

@@ -4,17 +4,17 @@ export interface SessionStorageStat {
     mtime: Date;
 }
 export interface SessionStorageWriter {
-    writeLine(line: string): Promise<void>;
     /**
-     * Synchronously append a single line. Returns once the bytes are handed to the kernel
-     * (page cache), so the data survives a non-graceful process death (OOM, SIGKILL, etc.)
-     * even though it has not yet been fsynced to the underlying disk.
+     * Append one newline-terminated line. File and memory storage perform the
+     * write synchronously in-body; indexed backends queue in call order.
      *
-     * `line` MUST already include the trailing newline. Throws synchronously on I/O error.
+     * `line` MUST include the trailing newline.
      */
-    writeLineSync(line: string): void;
+    append(line: string): Promise<void>;
+    /** Resolve once all queued appends complete. No fsync. */
     flush(): Promise<void>;
-    fsync(): Promise<void>;
+    /** False once close() has begun/finished. */
+    isOpen(): boolean;
     close(): Promise<void>;
     getError(): Error | undefined;
 }
@@ -29,6 +29,7 @@ export interface SessionStorage {
     /** Read the requested UTF-8 byte windows from the head and tail of the file. */
     readTextSlices(path: string, prefixBytes: number, suffixBytes: number): Promise<[string, string]>;
     writeText(path: string, content: string): Promise<void>;
+    writeTextAtomic(path: string, content: string): Promise<void>;
     rename(path: string, nextPath: string): Promise<void>;
     unlink(path: string): Promise<void>;
     deleteSessionWithArtifacts(sessionPath: string): Promise<void>;
@@ -38,6 +39,7 @@ export interface SessionStorage {
     }): SessionStorageWriter;
 }
 export declare class FileSessionStorage implements SessionStorage {
+    #private;
     ensureDirSync(dir: string): void;
     existsSync(path: string): boolean;
     writeTextSync(fpath: string, content: string): void;
@@ -47,6 +49,7 @@ export declare class FileSessionStorage implements SessionStorage {
     readText(path: string): Promise<string>;
     readTextSlices(path: string, prefixBytes: number, suffixBytes: number): Promise<[string, string]>;
     writeText(path: string, content: string): Promise<void>;
+    writeTextAtomic(fpath: string, content: string): Promise<void>;
     rename(path: string, nextPath: string): Promise<void>;
     unlink(path: string): Promise<void>;
     openWriter(path: string, options?: {
@@ -76,6 +79,7 @@ export declare class MemorySessionStorage implements SessionStorage {
     readText(path: string): Promise<string>;
     readTextSlices(path: string, prefixBytes: number, suffixBytes: number): Promise<[string, string]>;
     writeText(path: string, content: string): Promise<void>;
+    writeTextAtomic(path: string, content: string): Promise<void>;
     rename(path: string, nextPath: string): Promise<void>;
     unlink(path: string): Promise<void>;
     deleteSessionWithArtifacts(_sessionPath: string): Promise<void>;

package/dist/types/session/snapcompact-inline.d.ts

@@ -22,6 +22,16 @@ export interface SnapcompactInlineOptions {
     /** Frame variant override; `"auto"`/omitted picks the provider's eval winner. */
     shape?: snapcompact.ShapeVariantName | "auto";
 }
+/**
+ * Reports the per-tool-result tokens kept off the wire when a swap is applied.
+ * `savedTokens` is `textTokens - frames * shape.frameTokenEstimate` for each
+ * imaged tool result (always > 0; the savings gate guarantees it). Wired to the
+ * append-only savings journal; never throws into the request path.
+ */
+export type SnapcompactSavingsSink = (savings: ReadonlyArray<{
+    toolCallId: string;
+    savedTokens: number;
+}>, model: Model) => void;
 /** Tool-result swap candidate, in context order. */
 export interface InlineToolResultCandidate {
     /** Stable identifier for rendering cache key and applying the swap. */
@@ -129,6 +139,7 @@ export declare function estimateInlineSavings(input: {
 export declare class SnapcompactInlineTransformer {
     #private;
     private readonly options;
-    constructor(options: SnapcompactInlineOptions);
+    private readonly onToolResultSavings?;
+    constructor(options: SnapcompactInlineOptions, onToolResultSavings?: SnapcompactSavingsSink | undefined);
     transform(context: Context, model: Model): Context;
 }

package/dist/types/session/snapcompact-savings-journal.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Append-only journal of snapcompact tool-result savings.
+ *
+ * Snapcompact frames are transient — built per provider request in
+ * `transformProviderContext` and never written to session.jsonl — so the tokens
+ * they keep off the wire would otherwise leave no trace. This records one line
+ * the FIRST time a tool result is imaged in a session:
+ *
+ *   {"ts":<epochMs>,"session":<sessionFile>,"provider":..,"model":..,"toolCallId":..,"savedTokens":..}
+ *
+ * Newline-delimited JSON, opened with O_APPEND so concurrent appenders (parallel
+ * agents/subagents) never interleave a partial line. Writes are fire-and-forget;
+ * a failure is logged at debug and never propagates into the request hot path.
+ *
+ * Readers MUST dedup by (session, toolCallId): a session resumed in a fresh
+ * process re-images the same results and may append a second line. The savings
+ * for a given (session, toolCallId) are stable, so any-per-key is correct.
+ */
+import type { Model } from "@oh-my-pi/pi-ai";
+export interface SnapcompactSavingsRecord {
+    /** Epoch milliseconds when the swap was applied. */
+    ts: number;
+    /** Session file path (matches the stats `messages.session_file` key). */
+    session: string;
+    provider: string;
+    model: string;
+    toolCallId: string;
+    savedTokens: number;
+}
+/** `~/.omp/.../snapcompact-savings.jsonl`, colocated with stats.db. */
+export declare function snapcompactSavingsJournalPath(): string;
+/**
+ * Appends savings to the journal, deduped by toolCallId for the recorder's
+ * lifetime (one per session). Returns the in-flight append so callers/tests can
+ * await durability; the production transform leaves it floating (fire-and-forget,
+ * and it never rejects — I/O errors are swallowed to debug). `getSession` is read
+ * at write time so a session file assigned late is still captured; a null session
+ * (in-memory / SDK embedding) or non-positive savings skip the write.
+ */
+export type SnapcompactSavingsRecorder = (savings: ReadonlyArray<{
+    toolCallId: string;
+    savedTokens: number;
+}>, model: Model) => Promise<void>;
+export declare function createSnapcompactSavingsRecorder(getSession: () => string | null, journalPath?: string): SnapcompactSavingsRecorder;
+/** Read all journal records. Malformed lines are skipped; a missing file is empty. */
+export declare function readSnapcompactSavingsJournal(journalPath?: string): Promise<SnapcompactSavingsRecord[]>;

package/dist/types/session/tool-choice-queue.d.ts

@@ -6,12 +6,12 @@ export interface ResolveInfo {
 export interface RejectInfo {
     /** The ToolChoice that was yielded but never (or unsuccessfully) served. */
     choice: ToolChoice;
-    reason: "aborted" | "error" | "cleared" | "removed";
+    reason: "aborted" | "error" | "cleared" | "removed" | "unavailable" | "not_invoked";
 }
 /** "requeue" replays the lost yield next turn; "drop" (or void/undefined) discards it. */
 export type RejectOutcome = "requeue" | "drop";
 export interface DirectiveCallbacks {
-    /** Fires when the yield was served (LLM call completed). The directive is consumed. */
+    /** Fires when the yield completed; onInvoked directives require the requested tool to run first. */
     onResolved?: (info: ResolveInfo) => void;
     /**
      * Fires when the yield is being discarded. Return "requeue" to replay the
@@ -52,9 +52,9 @@ export declare class ToolChoiceQueue {
      */
     nextToolChoice(): ToolChoice | undefined;
     /**
-     * The in-flight yield was served — the LLM call completed normally.
-     * Fires onResolved, then clears in-flight state. The directive's generator
-     * remains in the queue if it has more values to yield.
+     * The in-flight yield completed normally. Directives with onInvoked are only
+     * consumed after their requested tool ran; a normal text turn or a different
+     * tool call requeues/rejects the directive instead.
      */
     resolve(): void;
     /**
@@ -65,7 +65,7 @@ export declare class ToolChoiceQueue {
     reject(reason: RejectInfo["reason"]): void;
     /** True if there is an in-flight yield that hasn't been resolved or rejected. */
     get hasInFlight(): boolean;
-    /** Peek the in-flight directive's onInvoked handler, if any. */
+    /** Return the in-flight directive's onInvoked handler and mark it when called. */
     peekInFlightInvoker(): ((input: unknown) => Promise<unknown> | unknown) | undefined;
     /** Remove all directives with the given label. Rejects in-flight if it matches. */
     removeByLabel(label: string): void;

package/dist/types/slash-commands/helpers/logout.d.ts

@@ -0,0 +1,15 @@
+import type { OAuthAccountIdentity, StoredAuthCredential } from "../../session/auth-storage";
+export interface LogoutAccount {
+    credentialId: number;
+    provider: string;
+    label: string;
+    detail: string;
+    type: "api_key" | "oauth";
+    active: boolean;
+}
+interface LogoutAccountOptions {
+    activeIdentity?: OAuthAccountIdentity;
+    activeApiKey?: boolean;
+}
+export declare function toLogoutAccounts(provider: string, credentials: StoredAuthCredential[], options?: LogoutAccountOptions): LogoutAccount[];
+export {};

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

@@ -0,0 +1,90 @@
+import type { Subprocess } from "bun";
+import type { SttProgressEvent, SttWorkerInbound, SttWorkerOutbound } from "./asr-protocol";
+import type { SttModelKey } from "./models";
+/**
+ * Abstraction over the speech-recognition subprocess. Modelled as a worker
+ * interface so the parent composes lifecycle, ping/pong, and request/response
+ * correlation uniformly; the runtime implementation is a Bun child process so
+ * `onnxruntime-node`'s NAPI finalizer never runs inside the main agent address
+ * space — that destructor segfaults Bun on shutdown (issue #1606).
+ */
+interface WorkerHandle {
+    send(message: SttWorkerInbound): void;
+    onMessage(handler: (message: SttWorkerOutbound) => void): () => void;
+    onError(handler: (error: Error) => void): () => void;
+    terminate(): Promise<void>;
+}
+export interface SttTranscribeOptions {
+    language?: string;
+    signal?: AbortSignal;
+}
+export interface SttDownloadOptions {
+    signal?: AbortSignal;
+    onProgress?: (event: SttProgressEvent) => void;
+}
+/** 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_stt_worker";
+interface SpawnedSubprocess {
+    proc: Subprocess<"ignore", "ignore", "ignore">;
+    inbound: Set<(message: SttWorkerOutbound) => void>;
+    errors: Set<(error: Error) => void>;
+    /**
+     * Flipped to `true` right before the parent SIGKILLs the child so `onExit`
+     * can distinguish the expected hard-kill from a crash/OOM/external signal.
+     */
+    intentionalExit: {
+        value: boolean;
+    };
+}
+/**
+ * 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;
+export declare class SttClient {
+    #private;
+    constructor(spawnWorker?: () => WorkerHandle);
+    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<boolean>;
+    terminate(): Promise<void>;
+}
+export declare const sttClient: SttClient;
+export declare function shutdownSttClient(): Promise<void>;
+export declare function smokeTestSttWorker({ timeoutMs, }?: {
+    timeoutMs?: number;
+}): Promise<void>;
+export {};

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

@@ -1,9 +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 already present in the local cache. For
+ * transformers.js Whisper tiers a complete download leaves `config.json` plus
+ * the `onnx/` weight files (a bare `config.json` from an interrupted fetch 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

@@ -1,3 +1,7 @@
+export * from "./asr-client";
+export * from "./asr-protocol";
 export * from "./downloader";
-export * from "./setup";
+export * from "./models";
 export * from "./stt-controller";
+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 {};