@drakulavich/kesha-voice-kit 1.17.0 → 1.17.1

package/SKILL.md

@@ -26,6 +26,39 @@ Local voice toolkit: transcribe voice messages to text, synthesize speech, detec
 - **Need to send a voice note (Telegram, WhatsApp, Signal, Discord)**: synthesize directly into the messenger-native format with `kesha say "<text>" --format ogg-opus --out reply.ogg`. Default is mono 24 kHz @ 32 kbps — what Telegram `sendVoice` expects. No `ffmpeg` round-trip needed.
 - **Need to detect what language a file is in** before choosing a pipeline: `kesha --json audio.ogg` returns both audio-based and text-based language detection with confidence scores.
 
+## OpenClaw plugin setup
+
+Install the plugin, then explicitly route OpenClaw audio understanding through the CLI model entry. The plugin registration makes Kesha discoverable, but real voice-message transcription uses `tools.media.audio.models` with a `type: "cli"` entry.
+
+```bash
+bun add -g @drakulavich/kesha-voice-kit
+kesha install
+openclaw plugins install @drakulavich/kesha-voice-kit
+openclaw config set tools.media.audio.enabled true
+openclaw config set tools.media.audio.models \
+  '[{"type":"cli","command":"kesha","args":["--format","transcript","{{MediaPath}}"],"timeoutSeconds":15}]'
+```
+
+Use `--format transcript` for OpenClaw's normal voice-message path: stdout is compact text plus language metadata, while progress and errors stay off the transcript payload.
+
+For agents that need timestamped segments, switch the model entry to JSON output and allow a longer timeout:
+
+```bash
+openclaw config set tools.media.audio.models \
+  '[{"type":"cli","command":"kesha","args":["--json","--timestamps","{{MediaPath}}"],"timeoutSeconds":30}]'
+```
+
+Verification checklist:
+
+```bash
+which kesha
+kesha status
+openclaw plugins list
+openclaw config get tools.media.audio.models
+```
+
+Do not rely on `openclaw.plugin.json` to patch `tools.media.audio.models`; OpenClaw ignores non-schema fields such as `configPatch`. Keep the CLI route in user config.
+
 ## STT: transcribe audio
 
 ```bash

package/openclaw-plugin.cjs

@@ -6,7 +6,7 @@
 // 25 languages, no cloud, ~19x faster than Whisper.
 //
 // The same `kesha` CLI also produces messenger-ready voice notes via
-// `kesha say --text "..." --format ogg-opus --out reply.ogg` (Telegram /
+// `kesha say "..." --format ogg-opus --out reply.ogg` (Telegram /
 // Discord ingest OGG/Opus directly — no transcoding needed). Not wired into
 // OpenClaw's media-understanding capability here; invoke it from a hook or
 // agent tool when you want Kesha to speak.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakulavich/kesha-voice-kit",
-  "version": "1.17.0",
+  "version": "1.17.1",
   "description": "Open-source voice toolkit. Speech-to-text (25 langs, ~19x faster than Whisper on Apple Silicon, ONNX fallback on CPU), text-to-speech (Kokoro + Vosk-TTS + ~180 macOS system voices, SSML), voice-activity detection, language detection (107 langs). Rust engine, OpenClaw skill.",
   "type": "module",
   "bin": {

package/src/cli/dispatch.ts

@@ -4,10 +4,11 @@ import { log } from "../log";
 import { suggestCommand } from "../suggest-command";
 import { installCommand } from "./install";
 import { sayCommand } from "./say";
+import { statsCommand } from "./stats";
 import { statusCommand } from "./status";
 import { mainCommand } from "./main";
 
-const SUBCOMMANDS = ["install", "status", "say"];
+const SUBCOMMANDS = ["install", "status", "say", "stats"];
 
 function isPathLike(arg: string): boolean {
   return arg.includes(".") || arg.includes("/") || existsSync(arg);
@@ -31,6 +32,11 @@ export async function runCli(rawArgs = process.argv.slice(2)): Promise<void> {
     return;
   }
 
+  if (firstArg === "stats") {
+    await runMain(statsCommand, { rawArgs: restArgs });
+    return;
+  }
+
   // Check for unknown subcommands (non-flag, non-file-path args).
   // Extensionless existing files remain valid transcription inputs; missing
   // bare tokens are more likely command typos and should not start the engine.

package/src/cli/main.ts

@@ -13,6 +13,7 @@ import {
   formatVerboseOutput,
 } from "../format";
 import { formatToonOutput } from "../toon";
+import { artifactFromFile, createStatsRecorder } from "../stats";
 
 const pkg = await Bun.file(new URL("../../package.json", import.meta.url)).json();
 
@@ -109,8 +110,12 @@ export const mainCommand = defineCommand({
     version: pkg.version,
     description:
       "Kesha Voice Kit — open-source voice toolkit for Apple Silicon.\n" +
-      "  Run 'kesha install [--no-cache]' to download engine and models.\n" +
-      "  Run 'kesha status' to inspect installed backend.",
+      "\n" +
+      "Commands:\n" +
+      "  install    Download engine and models.\n" +
+      "  status     Inspect installed backend.\n" +
+      "  say        Synthesize speech from text.\n" +
+      "  stats      Manage local anonymous performance stats.",
   },
   args: {
     json: {
@@ -197,28 +202,46 @@ export const mainCommand = defineCommand({
     const vadMode = args.vad ? "on" : args["no-vad"] ? "off" : "auto";
 
     if (files.length === 0) {
-      log.info("Usage: kesha <audio_file> [audio_file ...]\n       kesha install [--no-cache]\n       kesha status");
+      log.info(
+        "Usage: kesha <audio_file> [audio_file ...]\n" +
+          "       kesha install [--no-cache]\n" +
+          "       kesha status\n" +
+          "       kesha say <text>\n" +
+          "       kesha stats [enable|disable|status|week|errors]",
+      );
       process.exit(1);
     }
 
     let hasError = false;
     const results: TranscribeResult[] = [];
+    const stats = createStatsRecorder("transcribe");
 
     const wantsLangId = !!(args.lang || args.verbose || wantsJson || wantsToon || wantsTranscript);
+    const reportProgress = process.stdout.isTTY !== true;
 
     for (const file of files) {
       if (!existsSync(file)) {
         hasError = true;
+        stats.recordError("input", new Error("File not found"), "file_not_found");
         log.error(`${file}: File not found`);
         continue;
       }
+      const inputArtifact = artifactFromFile(file, "input_audio");
+      if (inputArtifact) stats.recordArtifact(inputArtifact);
 
       const startedAt = performance.now();
       try {
+        if (reportProgress) {
+          console.error(`Transcribing ${file}...`);
+        }
         // Run audio lang-id and transcription concurrently.
         const [audioResult, transcript] = await Promise.all([
-          wantsLangId ? detectAudioLanguageEngine(file) : Promise.resolve(null),
-          transcribeWithSegments(file, { vad: vadMode, timestamps: args.timestamps, speakers: args.speakers }),
+          wantsLangId
+            ? stats.timeStage("lang_id_audio", () => detectAudioLanguageEngine(file))
+            : Promise.resolve(null),
+          stats.timeStage("transcribe", () =>
+            transcribeWithSegments(file, { vad: vadMode, timestamps: args.timestamps, speakers: args.speakers })
+          ),
         ]);
         const { text, segments } = transcript;
 
@@ -236,7 +259,7 @@ export const mainCommand = defineCommand({
         let textLanguage: LangDetectResult | undefined;
 
         if (wantsLangId) {
-          const engineTextResult = await detectTextLanguageEngine(text);
+          const engineTextResult = await stats.timeStage("lang_id_text", () => detectTextLanguageEngine(text));
           if (engineTextResult && engineTextResult.code) {
             textLanguage = engineTextResult;
           }
@@ -247,20 +270,25 @@ export const mainCommand = defineCommand({
         const mismatchWarning = checkLanguageMismatch(args.lang, lang);
         if (mismatchWarning) log.warn(`${file}: ${mismatchWarning}`);
 
+        const sttTimeMs = Math.round(performance.now() - startedAt);
         const result: TranscribeResult = {
           file,
           text,
           lang,
           audioLanguage,
           textLanguage: textLanguage ?? (tinyldLang ? { code: tinyldLang, confidence: 0 } : undefined),
-          sttTimeMs: Math.round(performance.now() - startedAt),
+          sttTimeMs,
         };
-        if (args.timestamps) {
+        if (args.timestamps || args.speakers) {
           result.segments = segments;
         }
         results.push(result);
+        if (reportProgress) {
+          console.error(`Transcribed ${file} (${sttTimeMs}ms)`);
+        }
       } catch (err: unknown) {
         hasError = true;
+        stats.recordError("transcribe", err);
         const message = err instanceof Error ? err.message : String(err);
         log.error(`${file}: ${message}`);
       }
@@ -278,6 +306,8 @@ export const mainCommand = defineCommand({
       process.stdout.write(formatTextOutput(results));
     }
 
+    stats.finish(hasError ? "failed" : "success", files.length);
+
     if (hasError) process.exit(1);
   },
 });

package/src/cli/say.ts

@@ -2,6 +2,7 @@ import { defineCommand } from "citty";
 import { detectTextLanguageEngine, getEngineBinPath } from "../engine";
 import { log } from "../log";
 import { say, SayError, type SayFormat } from "../synth";
+import { artifactFromBytes, artifactFromFile, createStatsRecorder } from "../stats";
 import { pickVoiceForLang } from "../voice-routing";
 
 /** Run NLLanguageRecognizer (via engine) on the text and pick a default voice. */
@@ -133,19 +134,36 @@ export const sayCommand = defineCommand({
       sampleRate: args["sample-rate"] ? Number(args["sample-rate"]) : undefined,
       noExpandAbbrev: Boolean(args["no-expand-abbrev"]),
     };
+    const stats = createStatsRecorder("say");
 
     try {
       const startedAt = performance.now();
-      const audio = await say(opts);
+      if (opts.out) {
+        const voiceLabel = opts.voice ?? "default voice";
+        console.error(`Synthesizing ${voiceLabel} -> ${opts.out}...`);
+      }
+      const audio = await stats.timeStage("tts", () => say(opts));
       const ttsTimeMs = Math.round(performance.now() - startedAt);
-      if (args.verbose) {
+      if (opts.out) {
+        console.error(`Saved ${opts.out} (${ttsTimeMs}ms)`);
+      }
+      if (args.verbose && !opts.out) {
         // stderr — stdout may carry raw audio bytes when --out is omitted.
         console.error(`TTS time: ${ttsTimeMs}ms`);
       }
+      if (opts.out) {
+        const outputArtifact = artifactFromFile(opts.out, "output_audio");
+        if (outputArtifact) stats.recordArtifact(outputArtifact);
+      } else {
+        stats.recordArtifact(artifactFromBytes(audio.byteLength, "output_audio", opts.format ?? "wav"));
+      }
       if (!opts.out) {
         process.stdout.write(audio);
       }
+      stats.finish("success", 1);
     } catch (err) {
+      stats.recordError("tts", err);
+      stats.finish("failed", 1);
       if (err instanceof SayError) {
         log.error(err.stderr.trim() || err.message);
         process.exit(err.exitCode);

package/src/cli/stats.ts

@@ -0,0 +1,67 @@
+import { defineCommand } from "citty";
+import { log } from "../log";
+import {
+  disableStats,
+  enableStats,
+  getRecentErrors,
+  getStatsStatus,
+  getWeekSummary,
+  renderErrors,
+  renderWeekSummary,
+} from "../stats";
+
+interface StatsCommandArgs {
+  action?: string;
+}
+
+export const statsCommand = defineCommand({
+  meta: {
+    name: "stats",
+    description: "Manage local anonymous Kesha Stats",
+  },
+  args: {
+    action: {
+      type: "positional",
+      required: false,
+      description: "Action: enable | disable | status | week | errors",
+    },
+  },
+  run({ args }: { args: StatsCommandArgs }) {
+    const action = args.action ?? "status";
+    switch (action) {
+      case "enable": {
+        enableStats();
+        const status = getStatsStatus();
+        log.success("Kesha Stats enabled");
+        log.info(`Database: ${status.dbPath}`);
+        return;
+      }
+      case "disable": {
+        disableStats();
+        const status = getStatsStatus();
+        log.info("Kesha Stats disabled");
+        log.info(`Database: ${status.dbPath}`);
+        return;
+      }
+      case "status": {
+        const status = getStatsStatus();
+        log.info(`Kesha Stats: ${status.enabled ? "enabled" : "disabled"}`);
+        log.info(`Database: ${status.dbPath}`);
+        log.info(`Runs: ${status.runCount}`);
+        return;
+      }
+      case "week": {
+        log.info(renderWeekSummary(getWeekSummary()));
+        return;
+      }
+      case "errors": {
+        log.info(renderErrors(getRecentErrors()));
+        return;
+      }
+      default:
+        log.error(`unknown stats action '${action}'`);
+        log.warn("supported: enable, disable, status, week, errors");
+        process.exit(2);
+    }
+  },
+});

package/src/cli.ts

@@ -7,6 +7,7 @@ export { installCommand } from "./cli/install";
 export { sayCommand } from "./cli/say";
 export { pickVoiceForLang } from "./voice-routing";
 export { statusCommand } from "./cli/status";
+export { statsCommand } from "./cli/stats";
 export {
   mainCommand,
   detectLanguage,

package/src/stats.ts

@@ -0,0 +1,580 @@
+import { Database } from "bun:sqlite";
+import { existsSync, mkdirSync, readFileSync, statSync } from "fs";
+import { homedir } from "os";
+import { dirname, extname, join } from "path";
+import { log } from "./log";
+
+const SCHEMA_VERSION = 1;
+const MAX_ERROR_MESSAGE_CHARS = 300;
+const APP_VERSION = readPackageVersion();
+
+export type StatsCommandName = "transcribe" | "say";
+export type StatsStageStatus = "success" | "failed";
+export type StatsRunStatus = "success" | "failed";
+
+export interface StatsArtifactInput {
+  kind: "input_audio" | "output_audio";
+  format?: string | null;
+  sizeBytes?: number | null;
+  durationMs?: number | null;
+  sampleRate?: number | null;
+  channels?: number | null;
+}
+
+export interface StatsRecorder {
+  readonly enabled: boolean;
+  recordArtifact(input: StatsArtifactInput): void;
+  timeStage<T>(stage: string, fn: () => Promise<T>): Promise<T>;
+  recordError(stage: string, err: unknown, errorCode?: string): void;
+  finish(status: StatsRunStatus, itemCount?: number): void;
+}
+
+class NoopStatsRecorder implements StatsRecorder {
+  readonly enabled = false;
+  recordArtifact(): void {}
+  async timeStage<T>(_stage: string, fn: () => Promise<T>): Promise<T> {
+    return fn();
+  }
+  recordError(): void {}
+  finish(): void {}
+}
+
+class SqliteStatsRecorder implements StatsRecorder {
+  readonly enabled = true;
+  private closed = false;
+
+  constructor(
+    private readonly db: Database,
+    private readonly runId: number,
+  ) {}
+
+  recordArtifact(input: StatsArtifactInput): void {
+    this.safeWrite(() => {
+      this.db.query(
+        `insert into artifacts
+          (run_id, kind, format, size_bytes, duration_ms, sample_rate, channels)
+         values (?, ?, ?, ?, ?, ?, ?)`,
+      ).run(
+        this.runId,
+        input.kind,
+        normalizeFormat(input.format),
+        input.sizeBytes ?? null,
+        input.durationMs ?? null,
+        input.sampleRate ?? null,
+        input.channels ?? null,
+      );
+    });
+  }
+
+  async timeStage<T>(stage: string, fn: () => Promise<T>): Promise<T> {
+    const startedAt = new Date().toISOString();
+    const t0 = performance.now();
+    try {
+      const result = await fn();
+      this.recordStage(stage, startedAt, t0, "success");
+      return result;
+    } catch (err) {
+      this.recordStage(stage, startedAt, t0, "failed");
+      throw err;
+    }
+  }
+
+  recordError(stage: string, err: unknown, errorCode?: string): void {
+    const { errorClass, message } = sanitizeStatsError(err);
+    this.safeWrite(() => {
+      this.db.query(
+        `insert into errors
+          (run_id, stage, error_class, error_code, sanitized_message, occurred_at)
+         values (?, ?, ?, ?, ?, ?)`,
+      ).run(
+        this.runId,
+        stage,
+        errorClass,
+        errorCode ?? null,
+        message,
+        new Date().toISOString(),
+      );
+    });
+  }
+
+  finish(status: StatsRunStatus, itemCount = 0): void {
+    if (this.closed) return;
+    this.safeWrite(() => {
+      this.db.query(
+        "update runs set finished_at = ?, status = ?, item_count = ? where id = ?",
+      ).run(new Date().toISOString(), status, itemCount, this.runId);
+    });
+    this.closed = true;
+    this.db.close();
+  }
+
+  private recordStage(
+    stage: string,
+    startedAt: string,
+    startedMs: number,
+    status: StatsStageStatus,
+  ): void {
+    this.safeWrite(() => {
+      this.db.query(
+        `insert into stage_timings
+          (run_id, stage, started_at, duration_ms, status)
+         values (?, ?, ?, ?, ?)`,
+      ).run(
+        this.runId,
+        stage,
+        startedAt,
+        Math.max(0, Math.round(performance.now() - startedMs)),
+        status,
+      );
+    });
+  }
+
+  private safeWrite(fn: () => void): void {
+    try {
+      fn();
+    } catch (err) {
+      warnStatsWriteFailed(err);
+    }
+  }
+}
+
+let warnedStatsWriteFailed = false;
+
+function warnStatsWriteFailed(err: unknown): void {
+  if (!warnedStatsWriteFailed) {
+    log.warn("warning: failed to write Kesha Stats; continuing without stats for this event");
+    warnedStatsWriteFailed = true;
+  }
+  const message = err instanceof Error ? err.message : String(err);
+  log.debug(`stats write failed: ${message}`);
+}
+
+export function createStatsRecorder(command: StatsCommandName): StatsRecorder {
+  const dbPath = resolveStatsDbPath();
+  if (!existsSync(dbPath)) return new NoopStatsRecorder();
+
+  try {
+    const db = openStatsDatabase(dbPath);
+    if (!getStatsEnabled(db)) {
+      db.close();
+      return new NoopStatsRecorder();
+    }
+    const runId = insertRun(db, command);
+    return new SqliteStatsRecorder(db, runId);
+  } catch (err) {
+    warnStatsWriteFailed(err);
+    return new NoopStatsRecorder();
+  }
+}
+
+export function enableStats(): void {
+  const db = openStatsDatabase(resolveStatsDbPath());
+  try {
+    setSetting(db, "enabled", "1");
+  } finally {
+    db.close();
+  }
+}
+
+export function disableStats(): void {
+  const db = openStatsDatabase(resolveStatsDbPath());
+  try {
+    setSetting(db, "enabled", "0");
+  } finally {
+    db.close();
+  }
+}
+
+export interface StatsStatus {
+  enabled: boolean;
+  dbPath: string;
+  runCount: number;
+  exists: boolean;
+}
+
+export function getStatsStatus(): StatsStatus {
+  const dbPath = resolveStatsDbPath();
+  if (!existsSync(dbPath)) {
+    return { enabled: false, dbPath, runCount: 0, exists: false };
+  }
+  const db = openStatsDatabase(dbPath);
+  try {
+    return {
+      enabled: getStatsEnabled(db),
+      dbPath,
+      runCount: Number((db.query("select count(*) as n from runs").get() as { n: number }).n),
+      exists: true,
+    };
+  } finally {
+    db.close();
+  }
+}
+
+export interface StatsWeekSummary {
+  runs: number;
+  successes: number;
+  failures: number;
+  inputFiles: number;
+  inputBytes: number;
+  inputDurationMs: number;
+  sttTimeMs: number;
+  ttsTimeMs: number;
+}
+
+export function getWeekSummary(now = new Date()): StatsWeekSummary {
+  const dbPath = resolveStatsDbPath();
+  if (!existsSync(dbPath)) return emptyWeekSummary();
+  const since = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000).toISOString();
+  const db = openStatsDatabase(dbPath);
+  try {
+    const runs = db.query(
+      `select
+        count(*) as runs,
+        sum(case when status = 'success' then 1 else 0 end) as successes,
+        sum(case when status = 'failed' then 1 else 0 end) as failures
+       from runs
+       where started_at >= ?`,
+    ).get(since) as { runs: number; successes: number | null; failures: number | null };
+
+    const artifacts = db.query(
+      `select
+        count(*) as inputFiles,
+        coalesce(sum(size_bytes), 0) as inputBytes,
+        coalesce(sum(duration_ms), 0) as inputDurationMs
+       from artifacts
+       where kind = 'input_audio'
+         and run_id in (select id from runs where started_at >= ?)`,
+    ).get(since) as { inputFiles: number; inputBytes: number; inputDurationMs: number };
+
+    const stages = db.query(
+      `select
+        coalesce(sum(case when stage = 'transcribe' then duration_ms else 0 end), 0) as sttTimeMs,
+        coalesce(sum(case when stage = 'tts' then duration_ms else 0 end), 0) as ttsTimeMs
+       from stage_timings
+       where run_id in (select id from runs where started_at >= ?)`,
+    ).get(since) as { sttTimeMs: number; ttsTimeMs: number };
+
+    return {
+      runs: Number(runs.runs ?? 0),
+      successes: Number(runs.successes ?? 0),
+      failures: Number(runs.failures ?? 0),
+      inputFiles: Number(artifacts.inputFiles ?? 0),
+      inputBytes: Number(artifacts.inputBytes ?? 0),
+      inputDurationMs: Number(artifacts.inputDurationMs ?? 0),
+      sttTimeMs: Number(stages.sttTimeMs ?? 0),
+      ttsTimeMs: Number(stages.ttsTimeMs ?? 0),
+    };
+  } finally {
+    db.close();
+  }
+}
+
+export interface StatsErrorRow {
+  occurredAt: string;
+  command: string | null;
+  stage: string | null;
+  errorClass: string | null;
+  errorCode: string | null;
+  message: string;
+}
+
+export function getRecentErrors(limit = 20): StatsErrorRow[] {
+  const dbPath = resolveStatsDbPath();
+  if (!existsSync(dbPath)) return [];
+  const db = openStatsDatabase(dbPath);
+  try {
+    const rows = db.query(
+      `select
+        e.occurred_at as occurredAt,
+        r.command as command,
+        e.stage as stage,
+        e.error_class as errorClass,
+        e.error_code as errorCode,
+        e.sanitized_message as message
+       from errors e
+       left join runs r on r.id = e.run_id
+       order by e.occurred_at desc
+       limit ?`,
+    ).all(limit) as StatsErrorRow[];
+    return rows;
+  } finally {
+    db.close();
+  }
+}
+
+export function renderWeekSummary(summary: StatsWeekSummary): string {
+  const realtime = summary.inputDurationMs > 0 && summary.sttTimeMs > 0
+    ? `${(summary.inputDurationMs / summary.sttTimeMs).toFixed(1)}x`
+    : "n/a";
+  return [
+    "Kesha Stats - last 7 days",
+    `Runs: ${summary.runs} (${summary.successes} success, ${summary.failures} failed)`,
+    `Input files: ${summary.inputFiles}`,
+    `Input audio: ${humanDuration(summary.inputDurationMs)}`,
+    `Input size: ${humanBytes(summary.inputBytes)}`,
+    `STT time: ${humanDuration(summary.sttTimeMs)} (${realtime} realtime)`,
+    `TTS time: ${humanDuration(summary.ttsTimeMs)}`,
+  ].join("\n");
+}
+
+export function renderErrors(rows: StatsErrorRow[]): string {
+  if (rows.length === 0) return "Kesha Stats - no recorded errors";
+  const lines = ["Kesha Stats - recent errors"];
+  for (const row of rows) {
+    const parts = [
+      row.occurredAt,
+      row.command ?? "unknown",
+      row.stage ?? "unknown",
+      row.errorCode ?? row.errorClass ?? "error",
+    ];
+    lines.push(`${parts.join(" | ")} | ${row.message}`);
+  }
+  return lines.join("\n");
+}
+
+export function resolveStatsDbPath(): string {
+  if (process.env.KESHA_STATS_DB) return process.env.KESHA_STATS_DB;
+  if (process.platform === "darwin") {
+    return join(homedir(), "Library", "Application Support", "kesha", "stats.sqlite");
+  }
+  if (process.platform === "win32") {
+    const base = process.env.APPDATA || join(homedir(), "AppData", "Roaming");
+    return join(base, "kesha", "stats.sqlite");
+  }
+  const base = process.env.XDG_DATA_HOME || join(homedir(), ".local", "share");
+  return join(base, "kesha", "stats.sqlite");
+}
+
+export function artifactFromFile(
+  path: string,
+  kind: StatsArtifactInput["kind"],
+): StatsArtifactInput | null {
+  try {
+    const st = statSync(path);
+    if (!st.isFile()) return null;
+    return {
+      kind,
+      format: extname(path),
+      sizeBytes: st.size,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function artifactFromBytes(
+  bytes: number,
+  kind: StatsArtifactInput["kind"],
+  format?: string,
+): StatsArtifactInput {
+  return {
+    kind,
+    format,
+    sizeBytes: bytes,
+  };
+}
+
+export function sanitizeStatsError(err: unknown): { errorClass: string; message: string } {
+  const errorClass = err instanceof Error ? err.name : typeof err;
+  const raw = err instanceof Error ? err.message || err.name : String(err);
+  let message = raw
+    .split(/\r?\n/)
+    .filter((line) => !/^\s*at\s+/.test(line))
+    .join(" ")
+    .replace(/\s+/g, " ")
+    .trim();
+
+  const home = homedir();
+  const cwd = process.cwd();
+  for (const path of [home, cwd]) {
+    if (path) {
+      message = message.replace(new RegExp(escapeRegExp(path), "g"), "<path>");
+    }
+  }
+
+  message = message
+    .replace(/(https?:\/\/[^\s?]+)\?[^\s]+/g, "$1?<redacted>")
+    .replace(/("text"\s*:\s*)"[^"]*"/gi, '$1"<redacted>"')
+    .replace(/("transcript"\s*:\s*)"[^"]*"/gi, '$1"<redacted>"')
+    .replace(/("stdout"\s*:\s*)"[^"]*"/gi, '$1"<redacted>"')
+    .replace(/("stderr"\s*:\s*)"[^"]*"/gi, '$1"<redacted>"')
+    .replace(/\/(?:Users|home|tmp|private\/tmp|var\/folders)\/[^\s)"']+/g, "<path>")
+    .replace(/[A-Za-z]:\\[^\s)"']+/g, "<path>");
+
+  if (message.length === 0) message = errorClass || "unknown error";
+  if (message.length > MAX_ERROR_MESSAGE_CHARS) {
+    message = `${message.slice(0, MAX_ERROR_MESSAGE_CHARS - 3)}...`;
+  }
+  return { errorClass, message };
+}
+
+function openStatsDatabase(dbPath: string): Database {
+  mkdirSync(dirname(dbPath), { recursive: true });
+  const db = new Database(dbPath);
+  try {
+    db.exec("pragma journal_mode = WAL");
+    db.exec("pragma busy_timeout = 1000");
+    migrateStatsDatabase(db);
+    return db;
+  } catch (err) {
+    db.close();
+    throw err;
+  }
+}
+
+function migrateStatsDatabase(db: Database): void {
+  db.exec(`
+    create table if not exists schema_migrations (
+      version integer primary key,
+      applied_at text not null
+    );
+  `);
+
+  const currentVersion = currentSchemaVersion(db);
+  if (currentVersion >= SCHEMA_VERSION) return;
+
+  if (currentVersion < 1) {
+    db.exec(`
+      create table if not exists settings (
+        key text primary key,
+        value text not null
+      );
+
+      create table if not exists runs (
+        id integer primary key autoincrement,
+        command text not null,
+        started_at text not null,
+        finished_at text,
+        status text not null,
+        app_version text not null,
+        item_count integer not null default 0
+      );
+
+      create table if not exists artifacts (
+        id integer primary key autoincrement,
+        run_id integer not null references runs(id),
+        kind text not null,
+        format text,
+        size_bytes integer,
+        duration_ms integer,
+        sample_rate integer,
+        channels integer
+      );
+
+      create table if not exists stage_timings (
+        id integer primary key autoincrement,
+        run_id integer not null references runs(id),
+        stage text not null,
+        started_at text not null,
+        duration_ms integer not null,
+        status text not null
+      );
+
+      create table if not exists errors (
+        id integer primary key autoincrement,
+        run_id integer references runs(id),
+        stage text,
+        error_class text,
+        error_code text,
+        sanitized_message text not null,
+        occurred_at text not null
+      );
+
+      create index if not exists runs_started_at_idx on runs(started_at);
+      create index if not exists stage_timings_run_id_idx on stage_timings(run_id);
+      create index if not exists artifacts_run_id_idx on artifacts(run_id);
+      create index if not exists errors_occurred_at_idx on errors(occurred_at);
+    `);
+
+    recordSchemaVersion(db, 1);
+  }
+}
+
+function currentSchemaVersion(db: Database): number {
+  const row = db.query("select coalesce(max(version), 0) as version from schema_migrations").get() as {
+    version: number;
+  };
+  return Number(row.version ?? 0);
+}
+
+function recordSchemaVersion(db: Database, version: number): void {
+  db.query(
+    "insert or ignore into schema_migrations (version, applied_at) values (?, ?)",
+  ).run(version, new Date().toISOString());
+}
+
+function getStatsEnabled(db: Database): boolean {
+  const row = db.query("select value from settings where key = 'enabled'").get() as
+    | { value: string }
+    | null;
+  return row?.value === "1";
+}
+
+function setSetting(db: Database, key: string, value: string): void {
+  db.query(
+    "insert into settings (key, value) values (?, ?) on conflict(key) do update set value = excluded.value",
+  ).run(key, value);
+}
+
+function insertRun(db: Database, command: StatsCommandName): number {
+  const result = db.query(
+    "insert into runs (command, started_at, status, app_version) values (?, ?, 'failed', ?) returning id",
+  ).get(command, new Date().toISOString(), APP_VERSION) as { id: number };
+  return Number(result.id);
+}
+
+function normalizeFormat(format?: string | null): string | null {
+  if (!format) return null;
+  return format.replace(/^\./, "").toLowerCase();
+}
+
+function emptyWeekSummary(): StatsWeekSummary {
+  return {
+    runs: 0,
+    successes: 0,
+    failures: 0,
+    inputFiles: 0,
+    inputBytes: 0,
+    inputDurationMs: 0,
+    sttTimeMs: 0,
+    ttsTimeMs: 0,
+  };
+}
+
+function humanBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  const units = ["KB", "MB", "GB", "TB"];
+  let n = bytes / 1024;
+  let i = 0;
+  while (n >= 1024 && i < units.length - 1) {
+    n /= 1024;
+    i++;
+  }
+  return `${n.toFixed(n >= 100 ? 0 : 1)} ${units[i]}`;
+}
+
+function humanDuration(ms: number): string {
+  const seconds = Math.round(ms / 1000);
+  if (seconds < 1) return `${ms}ms`;
+  const h = Math.floor(seconds / 3600);
+  const m = Math.floor((seconds % 3600) / 60);
+  const s = seconds % 60;
+  if (h > 0) return `${h}h ${m}m ${s}s`;
+  if (m > 0) return `${m}m ${s}s`;
+  return `${s}s`;
+}
+
+function escapeRegExp(input: string): string {
+  return input.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function readPackageVersion(): string {
+  try {
+    const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as {
+      version?: unknown;
+    };
+    return typeof pkg.version === "string" ? pkg.version : "unknown";
+  } catch {
+    return "unknown";
+  }
+}