@tychenjiajun/pi-voice 0.0.0-stage → 0.2.0

package/src/log.ts

@@ -0,0 +1,171 @@
+import { appendFileSync, mkdirSync, renameSync, statSync } from "node:fs";
+import { dirname } from "node:path";
+
+/**
+ * Pi Voice's diagnostic log (~/.pi/agent/pi-voice.log).
+ * On by default at info, debug level with PI_VOICE_DEBUG=1
+ * Does not log transcripts or audio.
+ */
+
+export type LogLevel = "error" | "warn" | "info" | "debug";
+/** Who wrote the line: Pi Voice, or a native library through its log hook. */
+export type LogSource = "voice" | "recorder" | "transcribe";
+
+const RANK: Record<LogLevel, number> = { error: 0, warn: 1, info: 2, debug: 3 };
+/** Past this the file moves to `.1`, replacing the previous one. */
+const MAX_BYTES = 1024 * 1024;
+
+type Sink = { path: string; level: LogLevel; opened: boolean; failed: boolean };
+let sink: Sink | undefined;
+
+export function initLog(options: { path: string; level: LogLevel }): void {
+  if (sink?.path === options.path) {
+    sink.level = options.level;
+    return;
+  }
+  sink = { path: options.path, level: options.level, opened: false, failed: false };
+}
+
+/** Stops logging and the event-loop watch. */
+export function closeLog(): void {
+  sink = undefined;
+  stopWatch();
+  watchers = 0;
+  step = "idle";
+  keyPressedAt = undefined;
+}
+
+/** The level being written, or undefined when the log is off. */
+export function logLevel(): LogLevel | undefined {
+  return sink?.level;
+}
+
+function logEnabled(level: LogLevel): boolean {
+  return sink !== undefined && RANK[level] <= RANK[sink.level];
+}
+
+function append(sink: Sink, line: string): void {
+  if (!sink.opened) {
+    mkdirSync(dirname(sink.path), { recursive: true });
+    sink.opened = true;
+    const runtime = process.versions.bun ? `bun ${process.versions.bun}` : `node ${process.versions.node}`;
+    line = `${format("info", "voice", `pi-voice log opened (${runtime}, ${process.platform}-${process.arch}, level ${sink.level})`)}${line}`;
+  }
+  // Sized on every write: other Pi processes append to and rotate this file too.
+  try {
+    const size = statSync(sink.path).size;
+    if (size > 0 && size + Buffer.byteLength(line) > MAX_BYTES) renameSync(sink.path, `${sink.path}.1`);
+  } catch (error) {
+    // No file yet, or another process rotated it first.
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+  }
+  appendFileSync(sink.path, line);
+}
+
+function format(level: LogLevel, source: LogSource, message: string, timeMs = Date.now()): string {
+  const time = new Date(timeMs).toISOString();
+  return `${time} ${process.pid} ${level.padEnd(5)} ${source.padEnd(10)} ${message}\n`;
+}
+
+/** Writes one line. `timeMs` is when it happened, for native records that arrive late. */
+export function writeLog(level: LogLevel, source: LogSource, message: string, timeMs?: number): void {
+  if (!sink || sink.failed || !logEnabled(level)) return;
+  try {
+    append(sink, format(level, source, message.trimEnd().replaceAll("\n", " ⏎ "), timeMs));
+  } catch {
+    sink.failed = true; // A read-only or full disk must not break dictation.
+  }
+}
+
+export const log = {
+  error: (message: string) => writeLog("error", "voice", message),
+  warn: (message: string) => writeLog("warn", "voice", message),
+  info: (message: string) => writeLog("info", "voice", message),
+  debug: (message: string) => writeLog("debug", "voice", message),
+};
+
+/** An error's message, with a `RecorderError`'s code when it has one. */
+export function describeError(error: unknown): string {
+  if (!(error instanceof Error)) return String(error);
+  const { code } = error as Error & { code?: unknown };
+  // Node's own errors already lead with their code.
+  return typeof code === "string" && !error.message.startsWith(code) ? `${code}: ${error.message}` : error.message;
+}
+
+// Steps: what Pi Voice is doing, so a blocked event loop can say where.
+
+let step = "idle";
+
+/** Marks what Pi Voice is doing now; logged at debug. */
+export function logStep(name: string, detail?: string): void {
+  step = name;
+  if (timer) stepsSinceTick.push(name);
+  log.debug(detail ? `${name}: ${detail}` : name);
+}
+
+let keyPressedAt: number | undefined;
+
+/** The dictation shortcut was pressed; the next `sinceKeyPress` measures from here. */
+export function markKeyPress(): void {
+  keyPressedAt = performance.now();
+}
+
+/** Milliseconds since the last key press, once; undefined if none is pending. */
+export function sinceKeyPress(): number | undefined {
+  if (keyPressedAt === undefined) return undefined;
+  const elapsed = performance.now() - keyPressedAt;
+  keyPressedAt = undefined;
+  return elapsed;
+}
+
+// The event-loop watch: a timer that notices when it ran late, while Pi Voice
+// has work in flight. It can only report a block once the loop resumes, so it
+// names every step entered since the last tick: the block is among them.
+
+const TICK_MS = 50;
+/** A frozen TUI starts to show at about this. */
+const BLOCK_MS = 250;
+
+let watchers = 0;
+let timer: ReturnType<typeof setInterval> | undefined;
+let lastTick = 0;
+let stepsSinceTick = [step];
+
+function tick(): void {
+  const now = performance.now();
+  const blocked = now - lastTick - TICK_MS;
+  if (blocked >= BLOCK_MS) {
+    const where = stepsSinceTick.length === 1
+      ? `during "${step}"`
+      : `across "${stepsSinceTick.join('" → "')}"`;
+    const sleep = blocked >= 30_000 ? " (or the system slept)" : "";
+    log.warn(`event loop blocked for ${(blocked / 1000).toFixed(1)} s ${where}${sleep}`);
+  }
+  lastTick = now;
+  stepsSinceTick = [step];
+}
+
+function stopWatch(): void {
+  if (timer) clearInterval(timer);
+  timer = undefined;
+}
+
+/** Watches the event loop until the returned release is called. Nested watches share one timer. */
+export function watchEventLoop(): () => void {
+  if (!sink) return () => {};
+  if (watchers++ === 0) {
+    lastTick = performance.now();
+    stepsSinceTick = [step];
+    timer = setInterval(tick, TICK_MS);
+    timer.unref?.();
+  }
+  let released = false;
+  return () => {
+    if (released || watchers === 0) return;
+    released = true;
+    if (--watchers === 0) {
+      tick(); // A block that ended just now, before the timer could run.
+      stopWatch();
+    }
+  };
+}

package/src/microphone-picker.ts

@@ -0,0 +1,95 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { getAvailableMicrophones, type InputDevice, type Permission } from "./audio.js";
+import type { MicrophoneSetting } from "./settings.js";
+import { SingleSelectPicker, type SingleSelectChoice } from "./ui-components.js";
+
+export function microphoneSummary(microphone: MicrophoneSetting): string {
+  if (microphone.type === "system-default") return "System default";
+  const duplicate = microphone.occurrence > 0 ? ` · device ${microphone.occurrence + 1}` : "";
+  return `${microphone.name}${duplicate}`;
+}
+
+export function microphonesEqual(left: MicrophoneSetting, right: MicrophoneSetting): boolean {
+  return (
+    left.type === right.type &&
+    (left.type === "system-default" ||
+      (right.type === "device" &&
+        left.name === right.name &&
+        left.occurrence === right.occurrence))
+  );
+}
+
+function microphoneChoices(
+  devices: readonly InputDevice[],
+  current: MicrophoneSetting,
+): {
+  choices: SingleSelectChoice<string>[];
+  currentValue: string;
+  byValue: Map<string, MicrophoneSetting>;
+} {
+  const totals = new Map<string, number>();
+  for (const { name } of devices) totals.set(name, (totals.get(name) ?? 0) + 1);
+  const byValue = new Map<string, MicrophoneSetting>();
+  byValue.set("system-default", { type: "system-default" });
+  const choices: SingleSelectChoice<string>[] = [
+    {
+      value: "system-default",
+      label: "System default",
+      description: "Follow the input device selected by the operating system",
+    },
+  ];
+  let currentValue = "system-default";
+  for (const [index, { name, occurrence }] of devices.entries()) {
+    const microphone: MicrophoneSetting = { type: "device", name, occurrence };
+    const value = `device-${index}`;
+    const label = (totals.get(name) ?? 0) > 1 ? `${name} · device ${occurrence + 1}` : name;
+    choices.push({ value, label });
+    byValue.set(value, microphone);
+    if (microphonesEqual(current, microphone)) currentValue = value;
+  }
+  return { choices, currentValue, byValue };
+}
+
+/** Nothing where the platform has no permission to report (Linux). */
+export function microphonePermissionSummary(permission: Permission): string | undefined {
+  if (permission === "granted") return "Microphone: ✓ Access granted";
+  if (permission === "denied") return "Microphone: ✗ Access denied";
+  if (permission === "not-determined") {
+    return "Microphone: ⚠ Not yet requested — first recording will prompt for access";
+  }
+  return undefined;
+}
+
+export async function chooseMicrophone(
+  ctx: ExtensionContext,
+  current: MicrophoneSetting,
+  permission: Permission,
+): Promise<MicrophoneSetting | undefined> {
+  let devices: InputDevice[] = [];
+  try {
+    devices = await getAvailableMicrophones();
+  } catch (error) {
+    ctx.ui.notify(
+      `Could not list microphones: ${error instanceof Error ? error.message : String(error)}`,
+      "error",
+    );
+  }
+  const { choices, currentValue, byValue } = microphoneChoices(devices, current);
+  const selected = await ctx.ui.custom<string | undefined>((tui, theme, keybindings, done) =>
+    new SingleSelectPicker(
+      tui,
+      theme,
+      keybindings,
+      choices,
+      currentValue,
+      {
+        title: "Choose microphone input",
+        subtitle: microphonePermissionSummary(permission),
+        searchable: choices.length > 8,
+        cancelLabel: "back",
+      },
+      done,
+    ),
+  );
+  return selected ? byValue.get(selected) : undefined;
+}

package/src/model-activation.ts

@@ -0,0 +1,74 @@
+import type { CatalogModel } from "./catalog.js";
+import { downloadCatalogModel, findCachedCatalogModel, type CachedCatalogModel } from "./models.js";
+import { writeSettings, type TranscribeSettings } from "./settings.js";
+
+export type CatalogModelActivation = (
+  model: CatalogModel,
+  options: {
+    cached: CachedCatalogModel | undefined;
+    signal: AbortSignal;
+    onProgress: (progress: { downloaded: number; total: number }) => void;
+  },
+) => Promise<{ path: string }>;
+
+/**
+ * The download-then-save pipeline behind the model picker, shared by
+ * onboarding and the settings menu. Back-to-back selections can outrun their
+ * settings writes; commits run in selection order, so the file always ends on
+ * the user's last choice.
+ */
+export function createModelActivation(options: {
+  buildSettings: (model: CatalogModel, path: string) => TranscribeSettings;
+  onCommitted: (settings: TranscribeSettings) => void;
+}): {
+  activate: CatalogModelActivation;
+  /** Resolves once every commit enqueued so far has landed (or failed). */
+  waitForCommits: () => Promise<void>;
+} {
+  let commitQueue: Promise<void> = Promise.resolve();
+
+  const activate: CatalogModelActivation = async (
+    model,
+    { cached, signal, onProgress },
+  ) => {
+    let path: string;
+    if (cached) {
+      // The picker listed the cache when it opened; re-check so settings
+      // never point at a file that has since been evicted. Integrity is
+      // covered by the download-time hash and the size check here.
+      const stillCached = findCachedCatalogModel(model);
+      if (!stillCached) {
+        throw new Error(
+          "the downloaded file is missing; select the model again to re-download it",
+        );
+      }
+      path = stillCached.path;
+    } else {
+      path = await downloadCatalogModel(model, { signal, onProgress });
+    }
+
+    const commit = commitQueue.then(async () => {
+      // Skip the write when this selection was superseded or its download
+      // was cancelled while the commit sat in the queue.
+      signal.throwIfAborted();
+      let settings: TranscribeSettings;
+      try {
+        settings = options.buildSettings(model, path);
+        await writeSettings(settings);
+      } catch (error) {
+        throw new Error(
+          `Could not save settings: ${error instanceof Error ? error.message : String(error)}`,
+        );
+      }
+      options.onCommitted(settings);
+    });
+    commitQueue = commit.then(
+      () => undefined,
+      () => undefined,
+    );
+    await commit;
+    return { path };
+  };
+
+  return { activate, waitForCommits: () => commitQueue };
+}

package/src/model-cells.ts

@@ -0,0 +1,218 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import {
+  canonicalLanguage,
+  catalogModelSearchText,
+  displayLanguage,
+  formatBinarySize,
+  modelMatchesLanguage,
+  type CatalogModel,
+} from "./catalog.js";
+import {
+  languageAccuracyGrade,
+  modelWaitSeconds,
+  SPEED_METER_STEPS,
+  speedMeterLevel,
+  type AccuracyLetter,
+  type RecommendationRole,
+} from "./recommendations.js";
+import { LIST_PADDING, padToWidth, selectionMarker } from "./ui-components.js";
+
+type UiTheme = ExtensionContext["ui"]["theme"];
+
+// "A-" is the widest grade; language codes ("yue") can widen a column.
+const MIN_GRADE_CELL_WIDTH = 2;
+const MIN_MODEL_NAME_WIDTH = 12;
+export const ROLE_LABELS: Record<RecommendationRole, string> = {
+  best: "Best",
+  fast: "Fast",
+  accurate: "Accurate",
+};
+export const MANUAL_LANGUAGE_TAG = "manual lang";
+/** Replaces the size column for a model already in the cache. */
+export const ON_DISK_LABEL = "on disk";
+// "Best · Fast" is the widest role pairing that occurs.
+export const TAG_WIDTH = 11;
+
+/** Width of one grade cell for these language columns. */
+export function gradeCellWidth(languages: readonly string[]): number {
+  return Math.max(MIN_GRADE_CELL_WIDTH, ...languages.map((language) => visibleWidth(language)));
+}
+
+/** Width of the whole grade block: the cells and the spaces between them. */
+export function gradeColumnsWidth(languages: readonly string[]): number {
+  return languages.length * gradeCellWidth(languages) + Math.max(0, languages.length - 1);
+}
+
+// Colour reinforces the letter rather than replacing it, one hue per grade so
+// no single grade dominates: green A, blue B, gold C, red D and F. The blue
+// and gold borrow the markdown link and heading tokens; the theme has no
+// dedicated ones, and both shipped themes give them sensible values.
+export function gradeStyle(theme: UiTheme, letter: AccuracyLetter, text: string): string {
+  switch (letter) {
+    case "A": return theme.fg("success", text);
+    case "B": return theme.fg("mdLink", text);
+    case "C": return theme.fg("mdHeading", text);
+    case "D":
+    case "F": return theme.fg("error", text);
+  }
+}
+
+// One cell per preferred language, in preference order, carrying the model's
+// benchmark grade for it. A model that lacks the language shows a dash; one
+// that claims it without a benchmark shows a question mark, since a claim on
+// a model card is not a measurement.
+export function gradeCells(
+  theme: UiTheme,
+  model: CatalogModel,
+  languages: readonly string[],
+): string {
+  const cellWidth = gradeCellWidth(languages);
+  return languages
+    .map((language) => {
+      const grade = languageAccuracyGrade(model, language);
+      if (!grade) {
+        const mark = modelMatchesLanguage(model, language) ? "?" : "—";
+        return theme.fg("dim", padToWidth(mark, cellWidth));
+      }
+      return gradeStyle(theme, grade.letter, padToWidth(grade.label, cellWidth));
+    })
+    .join(" ");
+}
+
+/** The language codes over the grade cells, in the same widths. */
+export function gradeHeader(languages: readonly string[]): string {
+  const cellWidth = gradeCellWidth(languages);
+  return languages.map((language) => padToWidth(language, cellWidth)).join(" ");
+}
+
+// Benchmark processing speed, fuller the quicker (not end-of-speech latency).
+// Unbenchmarked models leave the column empty rather than claim a speed.
+export function speedCell(model: CatalogModel): string {
+  const wait = modelWaitSeconds(model);
+  if (wait === undefined) return " ".repeat(SPEED_METER_STEPS);
+  const level = speedMeterLevel(wait);
+  return "▰".repeat(level) + "▱".repeat(SPEED_METER_STEPS - level);
+}
+
+export type ModelTableLayout = {
+  nameWidth: number;
+  /**
+   * A section heading that doubles as the column header row: the label sits
+   * over the name column, the column names over theirs.
+   */
+  header: (label: string) => string;
+  sizeWidth?: number;
+};
+
+/** Shared column geometry for catalog and downloaded-model tables. */
+export function modelTableLayout(
+  theme: UiTheme,
+  width: number,
+  maximumNameWidth: number,
+  languages: readonly string[],
+  sizeWidth?: number,
+): ModelTableLayout {
+  const languagesWidth = gradeColumnsWidth(languages);
+  const sizeOverhead = sizeWidth === undefined ? 0 : 2 + sizeWidth;
+  const overhead =
+    LIST_PADDING * 2 +
+    4 +
+    2 +
+    SPEED_METER_STEPS +
+    2 +
+    languagesWidth +
+    sizeOverhead +
+    2 +
+    TAG_WIDTH;
+  const nameWidth = Math.min(
+    maximumNameWidth,
+    Math.max(MIN_MODEL_NAME_WIDTH, width - overhead),
+  );
+  // Labels outdent two columns from the names, like a heading; the rest of
+  // the name column is theirs, and a long one truncates on narrow terminals.
+  const labelWidth = 2 + nameWidth;
+  const size = sizeWidth === undefined
+    ? ""
+    : `  ${theme.fg("dim", "Size".padStart(sizeWidth))}`;
+  return {
+    nameWidth,
+    sizeWidth,
+    header: (label) =>
+      `  ${theme.fg("muted", padToWidth(label, labelWidth))}  ` +
+      `${theme.fg("dim", padToWidth("Speed", SPEED_METER_STEPS))}  ` +
+      theme.fg("dim", gradeHeader(languages)) +
+      size,
+  };
+}
+
+/** Shared model row; callers provide only the pane-specific final tag. */
+export function modelTableRow(
+  theme: UiTheme,
+  model: CatalogModel,
+  languages: readonly string[],
+  layout: ModelTableLayout,
+  options: {
+    active: boolean;
+    current: boolean;
+    tag?: string;
+    /** Already in the cache: the size column says so instead of the size. */
+    downloaded?: boolean;
+  },
+): string {
+  const prefix = options.active ? theme.fg("accent", "→ ") : "  ";
+  const current = selectionMarker(theme, options.current);
+  const nameText = padToWidth(model.name, layout.nameWidth);
+  const name = options.active ? theme.fg("accent", nameText) : nameText;
+  const sizeText = options.downloaded ? ON_DISK_LABEL : formatBinarySize(model.size);
+  const size = layout.sizeWidth === undefined
+    ? ""
+    : `  ${theme.fg("dim", sizeText.padStart(layout.sizeWidth))}`;
+  return (
+    `${prefix}${current} ${name}  ${speedCell(model)}  ` +
+    `${gradeCells(theme, model, languages)}${size}  ${options.tag ?? ""}`
+  );
+}
+
+/** Shared description and capability lines below a model table. */
+export function modelDetailText(
+  theme: UiTheme,
+  model: CatalogModel,
+  width: number,
+  padding: number,
+  feedback?: { type: "success" | "error" | "muted"; text: string },
+  showManualSelection = false,
+): string {
+  const canonicalLanguages = [...new Set(model.languages.map(canonicalLanguage))];
+  const features = [
+    canonicalLanguages.length === 1
+      ? `${displayLanguage(canonicalLanguages[0]!)} only`
+      : `${canonicalLanguages.length} languages`,
+    model.capabilities.languageDetection
+      ? "auto language detection"
+      : showManualSelection
+        ? "manual language selection"
+        : undefined,
+  ].filter((value): value is string => Boolean(value));
+  const description = truncateToWidth(
+    model.description,
+    Math.max(24, width - padding * 2),
+    "…",
+  );
+  const feedbackText = feedback
+    ? `\n${theme.fg(feedback.type, feedback.text)}`
+    : "";
+  return `${description}\n${theme.fg("dim", features.join(" · "))}${feedbackText}`;
+}
+
+/**
+ * The catalog's search matching, shared by every page that lists models.
+ * Each word of the query must appear literally in the model's id, name,
+ * family or size, so typing a model name finds that model and little else.
+ */
+export function matchesCatalogSearch(model: CatalogModel, query: string): boolean {
+  const tokens = query.toLowerCase().split(/\s+/).filter(Boolean);
+  if (!tokens.length) return true;
+  const text = catalogModelSearchText(model);
+  return tokens.every((token) => text.includes(token));
+}