@chatpanel/gateway 0.6.28 → 0.6.29

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chatpanel/gateway",
-  "version": "0.6.28",
+  "version": "0.6.29",
   "description": "Local privacy gateway — redacts PII out of OpenAI/Anthropic API traffic before it reaches a model, then restores it in the reply. Point opencode, codex, aider, Claude Code, etc. at it.",
   "type": "module",
   "bin": {
@@ -27,7 +27,7 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@chatpanel/pii": "^0.2.11",
+    "@chatpanel/pii": "^0.2.12",
     "@huggingface/transformers": "^4.2.0",
     "onnxruntime-web": "1.26.0-dev.20260416-b7804b056c"
   },

package/src/configstore.js

@@ -2,7 +2,7 @@
 // configure it live over the localhost API (GET/POST /config). The gateway stays
 // authoritative — the extension is just a UI client.
 
-import { writeFileSync, mkdirSync } from 'node:fs';
+import { writeFileSync, mkdirSync, chmodSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import os from 'node:os';
 import { usage } from './freegate.js';
@@ -15,7 +15,10 @@ export function configPath(env = process.env) {
 
 // Persist the user-editable subset (not derived runtime state).
 export function persistConfig(cfg, path = configPath()) {
-  mkdirSync(dirname(path), { recursive: true });
+  // 0700 the dir + 0600 the file: this JSON holds per-destination apiKeys, the
+  // detector key, and the entitlement/bridge tokens — same secret-at-rest posture
+  // as the history key/secret files, so it isn't left world-readable on a shared host.
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
   const out = {
     host: cfg.host, port: cfg.port, backend: cfg.backend,
     // Destinations (the configured agents + API models) MUST persist — otherwise a
@@ -25,7 +28,10 @@ export function persistConfig(cfg, path = configPath()) {
     ner: cfg.ner, stt: cfg.stt, allowedOrigins: cfg.allowedOrigins, maxBodyBytes: cfg.maxBodyBytes,
     pro: cfg.pro, logRequests: cfg.logRequests, logDetail: cfg.logDetail, tools: cfg.tools,
   };
-  writeFileSync(path, JSON.stringify(out, null, 2));
+  // mode on writeFileSync only applies when CREATING the file; chmod after covers an
+  // already-existing (pre-fix, possibly 0644) config too. Best-effort for non-POSIX.
+  writeFileSync(path, JSON.stringify(out, null, 2), { mode: 0o600 });
+  try { chmodSync(path, 0o600); } catch { /* platforms without POSIX perms */ }
 }
 
 // Safe view for GET /config — never leak secrets (the entitlement + bridge tokens

package/src/ner-engine.js

@@ -18,15 +18,39 @@ import os from 'node:os';
 import { join } from 'node:path';
 import { existsSync, mkdirSync } from 'node:fs';
 import { isKnownModel } from './models.js';
+import { isLoopbackHost, isPrivateHost, isMetadataHost } from '@chatpanel/pii';
 
 const DEFAULT_MODEL = 'Xenova/bert-base-NER';
+const DEFAULT_MODEL_HOST = 'https://dl.chatpanel.net/models/';
 
-// Download models from ChatPanel's own CDN (a branded, edge-cached proxy we
-// control) rather than directly from Hugging Face — so a clean install depends only
-// on chatpanel.net. Override with CHATPANEL_MODEL_BASE_URL (e.g. point at HF for
-// dev, or an air-gapped mirror). Must end with '/' (transformers appends the model
-// path template to it).
-const MODEL_HOST = (process.env.CHATPANEL_MODEL_BASE_URL || 'https://dl.chatpanel.net/models/').replace(/\/*$/, '/');
+// Where model weights are fetched from — ChatPanel's own edge-cached CDN by default,
+// so a clean install depends only on chatpanel.net. CHATPANEL_MODEL_BASE_URL can
+// override it (HF for dev, or an air-gapped LAN mirror) — but that env var is a
+// download-redirect vector: an attacker who sets it could serve a malicious ONNX
+// model into the runtime. So we VALIDATE the override before trusting it: http(s)
+// only, never cloud metadata, and no PLAINTEXT http to a PUBLIC host (a LAN/loopback
+// mirror on http is fine — that's the air-gap case). Anything else falls back to the
+// signed default and logs loudly. (True per-file checksum verification is the
+// remaining H3 step — needs a committed {model→sha256} manifest.)
+export function resolveModelHost() {
+  const raw = process.env.CHATPANEL_MODEL_BASE_URL;
+  if (!raw) return DEFAULT_MODEL_HOST;
+  const fallback = (why) => {
+    console.warn(`[models] ignoring CHATPANEL_MODEL_BASE_URL (${raw}): ${why} — using ${DEFAULT_MODEL_HOST}`);
+    return DEFAULT_MODEL_HOST;
+  };
+  let u;
+  try { u = new URL(raw); } catch { return fallback('not a valid URL'); }
+  if (u.protocol !== 'http:' && u.protocol !== 'https:') return fallback(`scheme ${u.protocol} not allowed`);
+  if (isMetadataHost(u.hostname)) return fallback('points at cloud metadata');
+  const localish = isLoopbackHost(u.hostname) || isPrivateHost(u.hostname);
+  if (u.protocol === 'http:' && !localish) return fallback('plaintext http:// to a public host (use https or a LAN/loopback mirror)');
+  console.warn(`[models] ⚠ model weights will be downloaded from ${u.origin} (CHATPANEL_MODEL_BASE_URL override), not ${DEFAULT_MODEL_HOST}`);
+  return raw.replace(/\/*$/, '/');
+}
+
+// Must end with '/' (transformers appends the model path template to it).
+const MODEL_HOST = resolveModelHost();
 
 let _state = 'off';        // 'off' | 'loading' | 'downloading' | 'ready' | 'error'
 let _model = null;         // active model id, e.g. 'Xenova/bert-base-NER'

package/src/parakeet-engine.js

@@ -0,0 +1,241 @@
+// In-process speech-to-text — NVIDIA Parakeet TDT (transducer) via onnxruntime.
+//
+// Whisper (stt-engine.js) is an encoder-DECODER seq2seq model and loads through the
+// transformers.js `automatic-speech-recognition` pipeline. Parakeet is a *transducer*
+// (Token-and-Duration Transducer / TDT on a FastConformer encoder) — a fundamentally
+// different architecture the transformers.js pipeline can't drive (it errors with
+// `Unsupported model type "nemo-conformer-tdt"`). So we run the ONNX graphs directly
+// on the same onnxruntime the gateway already ships, with a hand-written greedy TDT
+// decode loop.
+//
+// Why bother: Parakeet-TDT-0.6b-v3 is multilingual (25 European languages, auto-
+// detected — no forced-language step) and runs ~35× realtime at int8 on CPU, several
+// times faster than Whisper at comparable accuracy. It's the fast local-dictation path.
+//
+// Model layout (istupakov/onnx-asr export, e.g. `istupakov/parakeet-tdt-0.6b-v3-onnx`):
+//   nemo128.onnx            mel preprocessor  (waveforms → 128-bin log-mel features)
+//   encoder-model[.int8].onnx   FastConformer encoder (features → [B,D,T'] frames)
+//   decoder_joint[.int8].onnx   fused prediction-net (LSTM) + joint network
+//   vocab.txt               "<piece> <id>" per line; the last line is "<blk> <id>"
+//
+// This module owns ONE concern: load those graphs and turn 16 kHz mono Float32 PCM
+// into text. The streaming/session/redaction/diarization layer lives in stt-engine.js
+// and calls us through a tiny adapter, so nothing downstream needs to know the engine.
+
+import { join } from 'node:path';
+import { existsSync, mkdirSync, readFileSync, createWriteStream, renameSync, statSync } from 'node:fs';
+import { Readable } from 'node:stream';
+import { modelRoot } from './ner-engine.js';
+
+// transformers.js reports these `model_type`s for the transducer exports. Any of them
+// means "not a whisper pipeline model — route here instead".
+const TRANSDUCER_MODEL_TYPES = new Set([
+  'nemo-conformer-tdt', 'nemo-conformer-rnnt', 'parakeet_tdt', 'parakeet-tdt', 'parakeet_rnnt',
+]);
+export function isTransducerModelType(mt) {
+  return TRANSDUCER_MODEL_TYPES.has(String(mt || '').trim());
+}
+
+// Parakeet ships its own quantizations (standard QDQ/QOperator int8 — NOT whisper's
+// block-quantized q8, so it loads on BOTH the native and WASM runtimes). Default to
+// int8: ~690 MB total vs ~2.5 GB for fp32, with negligible accuracy loss for ASR.
+export const PARAKEET_DEFAULT_DTYPE = 'int8';
+export function parakeetDtype(d) {
+  return d === 'fp32' ? 'fp32' : PARAKEET_DEFAULT_DTYPE; // only int8 | fp32 are exported
+}
+
+// The repo files this engine needs for a given precision. `encoder-model.onnx` (fp32)
+// carries its weights in a sibling `.onnx.data` external-data file that ORT loads
+// automatically when it sits next to the graph — so we must fetch it too.
+function filesFor(dtype) {
+  const s = parakeetDtype(dtype) === 'fp32' ? '' : '.int8';
+  const files = ['config.json', 'vocab.txt', 'nemo128.onnx', `encoder-model${s}.onnx`, `decoder_joint-model${s}.onnx`];
+  if (!s) files.push('encoder-model.onnx.data'); // fp32 external weights
+  return files;
+}
+
+export function parakeetDir(modelId) {
+  return join(modelRoot(), ...String(modelId).split('/'));
+}
+
+// Present on disk = every required file exists and is non-empty (a truncated download
+// must not read as "installed"). Mirrors stt/ner `modelOnDisk` intent.
+export function parakeetOnDisk(modelId, dtype = PARAKEET_DEFAULT_DTYPE) {
+  const dir = parakeetDir(modelId);
+  if (!existsSync(dir)) return false;
+  try {
+    return filesFor(dtype).every((f) => { const p = join(dir, f); return existsSync(p) && statSync(p).size > 0; });
+  } catch { return false; }
+}
+
+// ── onnxruntime, matching the gateway's runtime (native npm vs WASM binary) ──────────
+// The npm gateway uses native onnxruntime-node (fast). The standalone binary embeds the
+// onnxruntime-web WASM runtime and hands us its paths via __CHATPANEL_WASM_PATHS__ (the
+// same global ner-engine keys off) — configure ORT-web from it. Memoized once.
+let _ortPromise = null;
+function getOrt() {
+  if (_ortPromise) return _ortPromise;
+  _ortPromise = (async () => {
+    const wasmPaths = globalThis.__CHATPANEL_WASM_PATHS__ || null;
+    const mod = await import(wasmPaths ? 'onnxruntime-web' : 'onnxruntime-node');
+    const ort = mod.InferenceSession ? mod : (mod.default || mod);
+    if (wasmPaths) {
+      try { ort.env.wasm.numThreads = 1; ort.env.wasm.proxy = false; ort.env.wasm.wasmPaths = wasmPaths; } catch { /* optional */ }
+    }
+    return ort;
+  })();
+  return _ortPromise;
+}
+
+// ── download (only when a model isn't already on disk) ───────────────────────────────
+// Custom/BYO STT ids aren't on the dl.chatpanel.net mirror, so — like stt-engine's
+// custom path — fetch straight from Hugging Face. Streamed to a .part file then renamed,
+// so an interrupted download never looks complete. `onProgress({ file, pct })` drives
+// the extension's model-manager UI.
+async function downloadFile(modelId, file, dir, { onProgress, log } = {}) {
+  const url = `https://huggingface.co/${modelId}/resolve/main/${encodeURIComponent(file).replace(/%2F/g, '/')}`;
+  const res = await fetch(url, { redirect: 'follow' });
+  if (!res.ok || !res.body) throw new Error(`fetch ${file} → HTTP ${res.status}`);
+  const total = Number(res.headers.get('content-length')) || 0;
+  const tmp = join(dir, `${file}.part`);
+  const out = createWriteStream(tmp);
+  let got = 0, lastPct = -1;
+  const src = Readable.fromWeb(res.body);
+  src.on('data', (chunk) => {
+    got += chunk.length;
+    if (total) { const pct = Math.round((got / total) * 100); if (pct !== lastPct) { lastPct = pct; onProgress?.({ file, pct }); } }
+  });
+  await new Promise((resolve, reject) => {
+    src.pipe(out);
+    out.on('finish', resolve); out.on('error', reject); src.on('error', reject);
+  });
+  renameSync(tmp, join(dir, file));
+  log?.(`[parakeet] fetched ${file}`);
+}
+
+async function ensureFiles(modelId, dtype, { onProgress, log } = {}) {
+  const dir = parakeetDir(modelId);
+  mkdirSync(dir, { recursive: true });
+  for (const file of filesFor(dtype)) {
+    const dest = join(dir, file);
+    if (existsSync(dest) && statSync(dest).size > 0) continue;
+    log?.(`[parakeet] downloading ${file}…`);
+    await downloadFile(modelId, file, dir, { onProgress, log });
+  }
+  return dir;
+}
+
+// ── vocab / detokenize ───────────────────────────────────────────────────────────────
+// vocab.txt: "<piece> <id>" per line. SentencePiece marks a word boundary with ▁
+// (U+2581); replace it with a space. The final line "<blk> <id>" is the blank/SOS id.
+function loadVocab(dir) {
+  const vocab = [];
+  let blank = -1;
+  for (const line of readFileSync(join(dir, 'vocab.txt'), 'utf8').split('\n')) {
+    if (!line) continue;
+    const sp = line.lastIndexOf(' ');
+    if (sp < 0) continue;
+    const id = parseInt(line.slice(sp + 1), 10);
+    const tok = line.slice(0, sp);
+    if (!Number.isFinite(id)) continue;
+    vocab[id] = tok.replace(/▁/g, ' ');
+    if (tok === '<blk>') blank = id;
+  }
+  if (blank < 0) blank = vocab.length - 1; // fall back to the last id (export convention)
+  return { vocab, blank };
+}
+
+function argmax(arr, from, to) {
+  let bi = from, bv = arr[from];
+  for (let i = from + 1; i < to; i++) if (arr[i] > bv) { bv = arr[i]; bi = i; }
+  return bi;
+}
+
+const DURATIONS = 5;        // TDT duration head bins → advance 0..4 encoder frames
+const MAX_SYMBOLS = 10;     // cap non-blank emissions per frame (anti-runaway)
+
+// ── recognizer ───────────────────────────────────────────────────────────────────────
+// Loads the three ONNX sessions once; `transcribe()` is stateless per call (fresh LSTM
+// state), so it's safe to call for every streaming segment. Serialize calls externally
+// (stt-engine already funnels decodes through one chain).
+export async function loadRecognizer({ modelId, dtype = PARAKEET_DEFAULT_DTYPE, allowDownload = true, onProgress, log = () => {} }) {
+  const dt = parakeetDtype(dtype);
+  const onDisk = parakeetOnDisk(modelId, dt);
+  if (!onDisk && !allowDownload) throw new Error('model not on disk and downloads disabled');
+  const dir = onDisk ? parakeetDir(modelId) : await ensureFiles(modelId, dt, { onProgress, log });
+
+  const ort = await getOrt();
+  const s = dt === 'fp32' ? '' : '.int8';
+  const opts = { executionProviders: ['cpu'], graphOptimizationLevel: 'all', logSeverityLevel: 3 };
+  const [prep, encoder, decoder] = await Promise.all([
+    ort.InferenceSession.create(join(dir, 'nemo128.onnx'), opts),
+    ort.InferenceSession.create(join(dir, `encoder-model${s}.onnx`), opts),
+    ort.InferenceSession.create(join(dir, `decoder_joint-model${s}.onnx`), opts),
+  ]);
+  const { vocab, blank } = loadVocab(dir);
+  const VOCAB = blank + 1;   // token logits span [0, VOCAB); duration logits follow
+  const Tensor = ort.Tensor;
+
+  async function transcribe(float32) {
+    if (!(float32 instanceof Float32Array) || float32.length < 400) return '';
+    const n = float32.length;
+
+    // 1) mel features (done in-graph — no manual DSP).
+    const pr = await prep.run({
+      waveforms: new Tensor('float32', float32, [1, n]),
+      waveforms_lens: new Tensor('int64', BigInt64Array.from([BigInt(n)]), [1]),
+    });
+
+    // 2) FastConformer encoder → outputs [1, D, T'] (channels-first, TIME LAST).
+    const er = await encoder.run({ audio_signal: pr.features, length: pr.features_lens });
+    const enc = er.outputs;
+    const [, D, T] = enc.dims;
+    const encLen = Number(er.encoded_lengths.data[0]);
+    const ed = enc.data; // element (0,d,t) at index d*T + t
+
+    // 3) greedy TDT decode. Per encoder frame: run the fused prednet+joint on the
+    // previous token + LSTM state; split the logits into token- and duration-heads.
+    // Only a NON-BLANK emission appends a token and advances the LSTM state; the
+    // duration argmax says how many frames to jump (0..4). duration==0 lets us emit
+    // another symbol at the same frame (up to MAX_SYMBOLS) — this is what makes TDT
+    // faster than plain RNN-T.
+    let h = new Float32Array(2 * 640);
+    let c = new Float32Array(2 * 640);
+    const tokens = [];
+    const frame = new Float32Array(D);
+    let t = 0, emitted = 0;
+    const guard = encLen * (MAX_SYMBOLS + 1) + 8; // hard stop; the loop always advances, but be safe
+    for (let iter = 0; t < encLen && iter < guard; iter++) {
+      for (let d = 0; d < D; d++) frame[d] = ed[d * T + t];
+      const prev = tokens.length ? tokens[tokens.length - 1] : blank;
+      const out = await decoder.run({
+        encoder_outputs: new Tensor('float32', frame, [1, D, 1]),
+        targets: new Tensor('int32', Int32Array.from([prev]), [1, 1]),
+        target_length: new Tensor('int32', Int32Array.from([1]), [1]),
+        input_states_1: new Tensor('float32', h, [2, 1, 640]),
+        input_states_2: new Tensor('float32', c, [2, 1, 640]),
+      });
+      const logits = out.outputs.data;
+      const tok = argmax(logits, 0, VOCAB);
+      const durIdx = argmax(logits, VOCAB, VOCAB + DURATIONS) - VOCAB; // 0..4
+      if (tok !== blank) {
+        h = out.output_states_1.data; c = out.output_states_2.data; // advance state only on emit
+        tokens.push(tok);
+        emitted++;
+      }
+      if (durIdx > 0) { t += durIdx; emitted = 0; }
+      else if (tok === blank || emitted >= MAX_SYMBOLS) { t += 1; emitted = 0; }
+      // else duration==0 & non-blank & under cap → stay on this frame, emit again
+    }
+
+    let text = '';
+    for (const id of tokens) text += vocab[id] ?? '';
+    return text.replace(/^\s+/, '').replace(/\s+/g, ' ').trimEnd();
+  }
+
+  function dispose() {
+    for (const sess of [prep, encoder, decoder]) { try { sess.release?.(); } catch { /* ignore */ } }
+  }
+
+  return { transcribe, dispose, dtype: dt, dir };
+}

package/src/router.js

@@ -10,6 +10,8 @@
 //     baseUrl, protocol,        (api) where to forward + 'openai'|'anthropic'
 //     models: [..],             models this destination serves (for /v1/models)
 //   }
+
+import { assertEndpointUrl } from '@chatpanel/pii';
 //
 // /v1/models aggregates every destination's models so clients can discover them.
 
@@ -87,7 +89,8 @@ export async function aggregateModelsAsync(cfg, { timeoutMs = 4000 } = {}) {
         if (d.protocol === 'anthropic') { headers['x-api-key'] = d.apiKey; headers['anthropic-version'] = '2023-06-01'; }
         else headers.authorization = `Bearer ${d.apiKey}`;
       }
-      const res = await fetch(`${d.baseUrl.replace(/\/$/, '')}/models`, { headers, signal: ctrl.signal });
+      const modelsUrl = assertEndpointUrl(`${d.baseUrl.replace(/\/$/, '')}/models`).toString(); // SSRF guard (skips a blocked dest via the catch)
+      const res = await fetch(modelsUrl, { headers, signal: ctrl.signal });
       if (!res.ok) return;
       const j = await res.json();
       const list = Array.isArray(j?.data) ? j.data : (Array.isArray(j?.models) ? j.models : []);

package/src/server.js

@@ -22,7 +22,7 @@ import { loadConfig } from './config.js';
 import { startEntitlementRefresh, maybeRevalidate } from './entitlement-refresh.js';
 import { redactSegments, segment } from './redact.js';
 import { pipeRestoredStream, pipeRestoredOpenAIStream, makeTokenRestorer } from './stream.js';
-import { restoreText, gatedDictionary, narrowSpecs, makeToolHarness, placeholderToolNote } from '@chatpanel/pii';
+import { restoreText, gatedDictionary, narrowSpecs, makeToolHarness, placeholderToolNote, assertEndpointUrl } from '@chatpanel/pii';
 import { streamBridgeChat, readBridgeToken, openBridgeChat } from './bridge.js';
 import { createRelaySession, getRelaySession, endRelaySession, pumpBridgeStream, deliverToolResult, toolsToSpecs, parseToolCallId } from './toolrelay.js';
 import { shaperFor } from './shape.js';
@@ -43,7 +43,7 @@ import * as openai from './openai.js';
 import * as responses from './responses.js';
 import * as anthropic from './anthropic.js';
 
-export const VERSION = '0.6.28';
+export const VERSION = '0.6.29';
 
 // WARM search tier — SQLite + FTS5 record store (falls back to an encrypted-JSON
 // store if SQLite can't load), fed by the extension's ingest sync + backup-ingest.
@@ -255,7 +255,8 @@ async function probeNerHealth(cfg) {
   const url = nerBaseUrl(cfg);
   if (!url) return { configured: false, ok: false, url: null, model: null };
   try {
-    const r = await fetch(url.replace(/\/ner\/?$/, '') + '/health', { signal: AbortSignal.timeout(2000) });
+    const healthUrl = assertEndpointUrl(url.replace(/\/ner\/?$/, '') + '/health').toString();
+    const r = await fetch(healthUrl, { signal: AbortSignal.timeout(2000) });
     if (!r.ok) return { configured: true, ok: false, url, model: null };
     const j = await r.json().catch(() => ({}));
     return { configured: true, ok: true, url, model: j.model || null };
@@ -425,7 +426,11 @@ async function handleApi(req, res, { adapter, kind, pathname, search, base, dest
       if (destProtocol === 'anthropic') { headers['x-api-key'] = destKey; delete headers.authorization; }
       else { headers.authorization = `Bearer ${destKey}`; }
     }
-    upstream = await fetch(base.replace(/\/$/, '') + pathname + search, {
+    // SSRF guard on the config-supplied upstream: block cloud-metadata + non-http(s)
+    // BEFORE the fetch. Loopback/LAN stay allowed (Ollama/LM Studio/homelab are the
+    // point of a BYO gateway); only the credential-theft pivot is refused.
+    const upstreamUrl = assertEndpointUrl(base.replace(/\/$/, '') + pathname + search).toString();
+    upstream = await fetch(upstreamUrl, {
       method: req.method,
       headers,
       body: ['GET', 'HEAD'].includes(req.method) ? undefined : outBody,
@@ -621,6 +626,7 @@ export function createGateway(cfg = loadConfig()) {
         if (!url) return sendJson(res, 503, { error: { message: 'NER not configured — deterministic-only redaction', type: 'ner_off' } });
         try {
           const body = await readBody(req, cfg.maxBodyBytes);
+          assertEndpointUrl(url); // block metadata/non-http(s) before POSTing raw text to the detector
           const r = await fetch(url, { method: 'POST', headers: { 'content-type': 'application/json' }, body, signal: AbortSignal.timeout(8000) });
           const text = await r.text();
           res.writeHead(r.status, { 'content-type': 'application/json' });

package/src/stt-engine.js

@@ -20,7 +20,8 @@ import { join } from 'node:path';
 import { existsSync, readdirSync } from 'node:fs';
 import { randomUUID } from 'node:crypto';
 import { ensureLib, modelRoot } from './ner-engine.js';
-import { DEFAULT_STT_MODEL, isEnglishOnly, sttModelDtype, isKnownSttModel } from './stt-models.js';
+import { DEFAULT_STT_MODEL, isEnglishOnly, sttModelDtype, isKnownSttModel, sttModelEngine } from './stt-models.js';
+import * as parakeet from './parakeet-engine.js';
 import * as diarize from './diarize-engine.js';
 
 export const SAMPLE_RATE = 16000; // fixed wire contract: 16 kHz mono Float32 PCM
@@ -65,6 +66,8 @@ const DTYPE_SUFFIX = {
 };
 
 export function modelOnDisk(modelId = _model || DEFAULT_STT_MODEL, dtype = sttModelDtype(modelId) || runtimeDtype()) {
+  // Transducer models (parakeet) have a different file layout + engine — delegate.
+  if (sttModelEngine(modelId) === 'parakeet-tdt') return parakeet.parakeetOnDisk(modelId, parakeet.parakeetDtype(dtype));
   const dir = join(modelRoot(), ...modelId.split('/'), 'onnx');
   if (!existsSync(dir)) return false;
   const suffix = DTYPE_SUFFIX[dtype] ?? '';
@@ -87,6 +90,9 @@ export function health() {
 // and a failed SWITCH keeps the previous working pipeline.
 /** @param {string} modelId @param {{ log?: (m: string) => void, allowDownload?: boolean, dtype?: string }} [opts] */
 async function loadModel(modelId, { log = () => {}, allowDownload = true, dtype: dtypeOverride = null } = {}) {
+  // Transducer models aren't whisper pipelines — hand off to the parakeet engine.
+  if (sttModelEngine(modelId) === 'parakeet-tdt') return loadParakeet(modelId, { log, allowDownload, dtype: dtypeOverride });
+
   const prevPipe = _pipe;
   const prevModel = _model;
   let lib;
@@ -160,6 +166,52 @@ async function loadModel(modelId, { log = () => {}, allowDownload = true, dtype:
   }
 }
 
+// Load a Parakeet TDT (transducer) model via parakeet-engine.js (raw onnxruntime), and
+// expose it to the session layer as a whisper-shaped `_pipe(audio) → { text }` adapter,
+// so decodeSession/streaming/redaction/diarization all work unchanged. Fail-open and
+// keep-previous-on-switch-failure, exactly like the whisper path above.
+/** @param {string} modelId @param {{ log?: (m: string) => void, allowDownload?: boolean, dtype?: string|null }} [opts] */
+async function loadParakeet(modelId, { log = () => {}, allowDownload = true, dtype: dtypeOverride = null } = {}) {
+  const prevPipe = _pipe;
+  const prevModel = _model;
+  const dtype = parakeet.parakeetDtype(dtypeOverride && dtypeOverride !== 'auto' ? dtypeOverride : PARAKEET_RUNTIME_DTYPE());
+  const haveLocal = parakeet.parakeetOnDisk(modelId, dtype);
+  if (!haveLocal && !allowDownload) {
+    _state = 'error'; _err = 'model not on disk and downloads disabled';
+    log(`[stt] model ${modelId} not installed and downloads disabled`);
+    return false;
+  }
+  _state = haveLocal ? 'loading' : 'downloading';
+  if (!haveLocal) { _progress = { model: modelId, file: null, pct: 0 }; log(`[stt] downloading model ${modelId} (one-time, from Hugging Face)…`); }
+  try {
+    const rec = await parakeet.loadRecognizer({
+      modelId, dtype, allowDownload, log,
+      onProgress: (p) => { _progress = { model: modelId, file: p.file || null, pct: typeof p.pct === 'number' ? p.pct : (_progress?.pct ?? 0) }; },
+    });
+    // whisper-shaped adapter: ignores the whisper `{ language, task }` opts (parakeet
+    // auto-detects language) and returns { text }. `__parakeet` flags the language-ID
+    // short-circuit; `dispose` frees the ORT sessions on switch.
+    const adapter = async (audio) => ({ text: await rec.transcribe(audio) });
+    adapter.__parakeet = true;
+    adapter.dispose = () => rec.dispose();
+    _pipe = adapter; _model = modelId; _state = 'ready'; _err = null; _progress = null; _dtype = dtype;
+    if (prevPipe && prevPipe !== adapter) { try { await prevPipe.dispose?.(); } catch { /* ignore */ } }
+    log(`[stt] ready — model ${modelId} @ ${dtype} (parakeet-tdt, in-process, offline) — local dictation active`);
+    return true;
+  } catch (e) {
+    _err = e.message; _progress = null;
+    if (prevPipe) { _pipe = prevPipe; _model = prevModel; _state = 'ready'; }
+    else { _state = 'error'; }
+    log(`[stt] model load failed (${e.message})${prevPipe ? ' — keeping previous model' : ''}`);
+    return false;
+  }
+}
+
+// Parakeet only ships int8 + fp32 exports (no whisper-style q8). int8 loads and runs on
+// BOTH runtimes; only force fp32 if a caller explicitly asks. Independent of the whisper
+// runtimeDtype (which returns q8/fp32).
+function PARAKEET_RUNTIME_DTYPE() { return parakeet.PARAKEET_DEFAULT_DTYPE; }
+
 // Load the configured model once, on FIRST USE (never at gateway startup — the
 // download is deferred until someone actually dictates). Single-flight.
 export function init(cfg = {}) {
@@ -174,8 +226,11 @@ export function init(cfg = {}) {
 export async function setModel(modelId, opts = {}) {
   const log = typeof opts.onLog === 'function' ? opts.onLog : () => {};
   if (!modelId) return false;
-  // Re-load if the model OR the requested precision changed.
-  const wantDtype = opts.dtype && opts.dtype !== 'auto' ? opts.dtype : (sttModelDtype(modelId) || runtimeDtype());
+  // Re-load if the model OR the requested precision changed. Parakeet has its own
+  // dtype domain (int8/fp32), independent of whisper's q8/fp32 runtimeDtype.
+  const wantDtype = sttModelEngine(modelId) === 'parakeet-tdt'
+    ? parakeet.parakeetDtype(opts.dtype && opts.dtype !== 'auto' ? opts.dtype : parakeet.PARAKEET_DEFAULT_DTYPE)
+    : (opts.dtype && opts.dtype !== 'auto' ? opts.dtype : (sttModelDtype(modelId) || runtimeDtype()));
   if (modelId === _model && isReady() && _dtype === wantDtype) return true;
   return loadModel(modelId, { log, allowDownload: opts.allowDownload !== false, dtype: opts.dtype });
 }
@@ -348,7 +403,7 @@ async function decodeSession(s, { flush = false } = {}) {
 
   // Auto-detect the spoken language on the session's first voiced audio (≥1s),
   // then pin it. An explicit client `lang` wins; `.en` models skip all of this.
-  if (!s.lang && !s.langTried && !isEnglishOnly(_model) && audio.length >= SAMPLE_RATE) {
+  if (!s.lang && !s.langTried && !isEnglishOnly(_model) && !_pipe?.__parakeet && audio.length >= SAMPLE_RATE) {
     s.langTried = true;
     const detected = await detectLanguage(audio);
     if (detected) { s.lang = detected; emit(s, { type: 'language', lang: detected }); }

package/src/stt-models.js

@@ -53,8 +53,35 @@ export const STT_MODEL_CATALOG = [
     ramMB: 3200,
     note: 'Best accuracy. For powerful machines; use the native (npm) gateway for speed.',
   },
+  {
+    // NOT a whisper/seq2seq model — a NeMo TDT transducer. It doesn't run through the
+    // transformers.js ASR pipeline; the STT engine routes `engine: 'parakeet-tdt'`
+    // models to parakeet-engine.js (raw onnxruntime + a greedy TDT decode). Multilingual
+    // (25 European languages, auto-detected) and ~35× realtime at int8 on the native
+    // (npm) gateway — the fast local-dictation path. WASM runs it but slower.
+    id: 'istupakov/parakeet-tdt-0.6b-v3-onnx',
+    label: 'Parakeet TDT 0.6B v3 (multilingual, fast)',
+    lang: '25 European languages (auto-detected)',
+    tier: 'accurate',
+    engine: 'parakeet-tdt',
+    recommended: true,   // our default recommendation: faster + more accurate than Whisper.
+    approxMB: 690,   // int8: encoder 652 + decoder_joint 18 + preprocessor
+    ramMB: 1600,
+    note: 'Recommended — NVIDIA Parakeet transducer. Several× faster than Whisper at similar or better accuracy, English + 24 EU languages. One-time download; best on the native (npm) gateway.',
+  },
 ];
 
+// The model we steer users to (a bigger, on-demand download — NOT the boot default,
+// which stays a small model so first dictation works instantly). The settings UI
+// surfaces this so users can install it after the gateway is running.
+export const RECOMMENDED_STT_MODEL = 'istupakov/parakeet-tdt-0.6b-v3-onnx';
+
+// STT engine backing a model. Default 'whisper' = the transformers.js ASR pipeline;
+// 'parakeet-tdt' = the raw-onnxruntime transducer engine (parakeet-engine.js).
+export function sttModelEngine(id) {
+  return sttModel(id)?.engine || 'whisper';
+}
+
 export function isKnownSttModel(id) {
   return STT_MODEL_CATALOG.some((m) => m.id === id);
 }