@bojackduy/opencode-voice 0.1.0

package/lib/llm-client.js

@@ -0,0 +1,304 @@
+// OpenAI-compatible LLM client for text normalization.
+//
+// Works with any OpenAI-compatible endpoint:
+//   - Anthropic's OpenAI compatibility layer
+//   - OpenAI directly
+//   - Ollama, vLLM, LM Studio, etc.
+//
+// Configuration is passed from plugin options (tui.json):
+//   ["@bojackduy/opencode-voice", {
+//     "endpoint": "https://api.anthropic.com/v1",
+//     "model": "claude-haiku-4-5",
+//     "apiKeyEnv": "ANTHROPIC_API_KEY",
+//     "maxTokens": 2048,
+//     "reasoningEffort": "low",
+//     "chatTemplateKwargs": {"enable_thinking": false},
+//     "retries": 2
+//   }]
+
+const DEFAULTS = {
+  maxTokens: 2048,
+  reasoningEffort: null,
+  chatTemplateKwargs: null,
+  retries: 2,
+  temperature: null,
+};
+
+function isResponsesEndpoint(endpoint, explicitFlag) {
+  if (explicitFlag === true) return true;
+  if (explicitFlag === false) return false;
+  const trimmed = (endpoint || "").replace(/\/+$/, "");
+  return trimmed.endsWith("/responses");
+}
+
+function isChatCompletionsEndpoint(endpoint) {
+  const trimmed = (endpoint || "").replace(/\/+$/, "");
+  return trimmed.endsWith("/chat/completions");
+}
+
+function resolveEndpoint(raw, useResponses) {
+  const trimmed = (raw || "").replace(/\/+$/, "");
+  if (!trimmed) return trimmed;
+  if (
+    isChatCompletionsEndpoint(trimmed) ||
+    (isResponsesEndpoint(trimmed, useResponses === true ? true : null) &&
+      trimmed.endsWith("/responses"))
+  ) {
+    // already a full path — use as-is
+    if (trimmed.endsWith("/chat/completions") || trimmed.endsWith("/responses")) return trimmed;
+  }
+  if (isResponsesEndpoint(raw, useResponses)) return `${trimmed}/responses`;
+  return `${trimmed}/chat/completions`;
+}
+
+function extractResponsesText(data) {
+  if (!data) return null;
+  if (typeof data.output_text === "string" && data.output_text.trim()) return data.output_text;
+  // output: [{ type:"message", content:[{type:"output_text", text:"..."}] }]
+  const out = data.output;
+  if (Array.isArray(out)) {
+    for (const item of out) {
+      const content = item?.content;
+      if (Array.isArray(content)) {
+        for (const c of content) {
+          if (typeof c?.text === "string" && c.text.trim()) return c.text;
+          if (typeof c?.output_text === "string" && c.output_text.trim()) return c.output_text;
+        }
+      } else if (typeof content?.text === "string" && content.text.trim()) {
+        return content.text;
+      }
+    }
+  }
+  // some gateways return choices like chat
+  return data?.choices?.[0]?.message?.content || null;
+}
+
+function normalizeRetries(value) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed < 0) return DEFAULTS.retries;
+  return Math.floor(parsed);
+}
+
+/**
+ * Resolve an OpenCode provider + model (as picked via /voice-model) into
+ * OpenAI-compatible call config. Explicit plugin options always win; this is
+ * only the fallback when endpoint/model are not configured.
+ *
+ * Auth caveat: only env-key providers work (key read live from provider.env).
+ * OAuth/Console-managed credentials are not visible to plugins.
+ */
+export function resolveProviderConfig(provider, model) {
+  if (!provider || !model) return null;
+  const options = provider.options || {};
+  const endpoint =
+    (typeof options.baseURL === "string" && options.baseURL) ||
+    (typeof options.endpoint === "string" && options.endpoint) ||
+    model?.api?.url ||
+    null;
+  const envVars = Array.isArray(provider.env) ? provider.env : [];
+  // Usability is ANY exported key, but requests must use the key that is
+  // actually exported — envVars[0] alone yields unauthenticated requests
+  // when the user exported the second alt name instead.
+  const exported = envVars.find((name) => name && process.env[name]);
+  return {
+    endpoint,
+    model: model.id,
+    apiKeyEnv: exported || envVars[0] || null,
+  };
+}
+
+function normalizeChatTemplateKwargs(value) {
+  if (!value) return null;
+  if (typeof value === "object") return value;
+  try {
+    const parsed = JSON.parse(value);
+    return typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function shouldRetry(status) {
+  return status === 408 || status === 429 || status >= 500;
+}
+
+function wait(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Create an LLM completion function.
+ *
+ * @param {object} [pluginOptions] - Static config from tui.json plugin options
+ * @param {{ log?: (scope: string, message: string, level?: string) => void }} [logger]
+ * @param {() => string | undefined} [getSessionID] - Resolver for the live opencode
+ *   session ID. Sent as `x-opencode-session` so session-scoped gateways
+ *   (e.g. opencode.ai/zen/go) can route the request. Omit when the endpoint
+ *   needs no session binding.
+ * @param {() => ({ provider: object, model: object } | null)} [getProviderModel] -
+ *   Resolver for the voice-selected OpenCode provider + model (see
+ *   /voice-model). Used only when endpoint/model are not set explicitly.
+ * @returns {{ complete: (opts: { system?: string, prompt: string, config?: object }) => Promise<{ text: string | null, error?: string }> }}
+ */
+export function createClient(pluginOptions, logger, getSessionID, getProviderModel) {
+  function getConfig() {
+    const rawUseResponses =
+      pluginOptions?.useResponsesApi ??
+      pluginOptions?.responsesApi ??
+      pluginOptions?.useResponses ??
+      null;
+    // allow explicit apiMode: "responses" | "chat"
+    const modeFlag =
+      pluginOptions?.apiMode === "responses"
+        ? true
+        : pluginOptions?.apiMode === "chat"
+          ? false
+          : rawUseResponses;
+    // Voice-selected OpenCode provider (via /voice-model) fills whatever the
+    // explicit options leave out. Explicit endpoint/model/apiKeyEnv win.
+    let providerResolved = null;
+    try {
+      const selection = typeof getProviderModel === "function" ? getProviderModel() : null;
+      providerResolved = resolveProviderConfig(selection?.provider, selection?.model);
+    } catch {
+      providerResolved = null;
+    }
+    return {
+      endpoint: pluginOptions?.endpoint ?? providerResolved?.endpoint,
+      model: pluginOptions?.model ?? providerResolved?.model,
+      apiKeyEnv: pluginOptions?.apiKeyEnv ?? providerResolved?.apiKeyEnv,
+      maxTokens: pluginOptions?.maxTokens ?? DEFAULTS.maxTokens,
+      reasoningEffort: pluginOptions?.reasoningEffort ?? DEFAULTS.reasoningEffort,
+      chatTemplateKwargs: normalizeChatTemplateKwargs(
+        pluginOptions?.chatTemplateKwargs ?? DEFAULTS.chatTemplateKwargs,
+      ),
+      retries: normalizeRetries(pluginOptions?.retries ?? DEFAULTS.retries),
+      temperature:
+        pluginOptions?.temperature != null
+          ? Number(pluginOptions.temperature)
+          : DEFAULTS.temperature,
+      useResponsesApi: modeFlag,
+    };
+  }
+
+  /**
+   * Send a chat completion request to an OpenAI-compatible endpoint.
+   *
+   * @param {object} opts
+   * @param {string} [opts.system]  - System prompt
+   * @param {string} opts.prompt    - User message
+   * @param {object} [opts.config]  - Per-call overrides (e.g. { maxTokens: 4096 })
+   * @returns {Promise<{ text: string | null, error?: string }>}
+   */
+  async function complete({ system, prompt, config: overrides }) {
+    const cfg = { ...getConfig(), ...overrides };
+    if (!cfg.endpoint) {
+      logger?.log?.("LLM", "completion skipped: endpoint not configured", "warn");
+      return { text: null, error: "LLM endpoint not configured" };
+    }
+    if (!cfg.model) {
+      logger?.log?.("LLM", "completion skipped: model not configured", "warn");
+      return { text: null, error: "LLM model not configured" };
+    }
+    const apiKey = cfg.apiKeyEnv ? process.env[cfg.apiKeyEnv] : null;
+    // Per-call override wins, otherwise ask the live session resolver.
+    // The zen/go gateway rejects requests without x-opencode-session (401/400).
+    const sessionID =
+      cfg.sessionID ?? (typeof getSessionID === "function" ? getSessionID() : null) ?? null;
+
+    const endpoint = resolveEndpoint(cfg.endpoint, cfg.useResponsesApi);
+    const useResponses = endpoint.endsWith("/responses");
+
+    let body;
+    if (useResponses) {
+      body = {
+        model: cfg.model,
+        input: prompt,
+        instructions: system || undefined,
+        max_output_tokens: cfg.maxTokens,
+      };
+      if (cfg.temperature != null && Number.isFinite(cfg.temperature))
+        body.temperature = cfg.temperature;
+      if (cfg.reasoningEffort) body.reasoning = { effort: cfg.reasoningEffort };
+      // chat_template_kwargs not standard for responses, but pass through if needed
+      if (cfg.chatTemplateKwargs) body.chat_template_kwargs = cfg.chatTemplateKwargs;
+    } else {
+      const messages = [];
+      if (system) messages.push({ role: "system", content: system });
+      messages.push({ role: "user", content: prompt });
+      body = {
+        model: cfg.model,
+        max_tokens: cfg.maxTokens,
+        messages,
+      };
+      if (cfg.temperature != null && Number.isFinite(cfg.temperature))
+        body.temperature = cfg.temperature;
+      if (cfg.reasoningEffort) body.reasoning_effort = cfg.reasoningEffort;
+      if (cfg.chatTemplateKwargs) body.chat_template_kwargs = cfg.chatTemplateKwargs;
+    }
+
+    for (let attempt = 0; attempt <= cfg.retries; attempt++) {
+      try {
+        logger?.log?.(
+          "LLM",
+          `Completion request attempt=${attempt + 1} model=${cfg.model} maxTokens=${cfg.maxTokens} promptChars=${prompt.length}`,
+          "debug",
+        );
+        const response = await fetch(endpoint, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            ...(apiKey ? { Authorization: "Bearer " + apiKey } : {}),
+            ...(sessionID ? { "x-opencode-session": sessionID } : {}),
+          },
+          body: JSON.stringify(body),
+        });
+
+        if (!response.ok) {
+          logger?.log?.(
+            "LLM",
+            `Completion response status=${response.status}`,
+            shouldRetry(response.status) ? "warn" : "error",
+          );
+          if (attempt < cfg.retries && shouldRetry(response.status)) {
+            await wait(250 * 2 ** attempt);
+            continue;
+          }
+          return { text: null, error: `LLM request failed (${response.status})` };
+        }
+
+        const data = await response.json();
+        const text = useResponses
+          ? extractResponsesText(data)
+          : data?.choices?.[0]?.message?.content || null;
+        if (text) {
+          logger?.log?.(
+            "LLM",
+            `Completion succeeded chars=${text.length} mode=${useResponses ? "responses" : "chat"}`,
+            "debug",
+          );
+          return { text };
+        }
+
+        logger?.log?.("LLM", "Completion returned empty content", "warn");
+
+        if (attempt < cfg.retries) {
+          await wait(250 * 2 ** attempt);
+          continue;
+        }
+        return { text: null, error: "Empty LLM response" };
+      } catch (err) {
+        logger?.log?.("LLM", `Completion error attempt=${attempt + 1}: ${err.message}`, "warn");
+        if (attempt < cfg.retries) {
+          await wait(250 * 2 ** attempt);
+          continue;
+        }
+        return { text: null, error: `LLM error: ${err.message}` };
+      }
+    }
+
+    return { text: null, error: "LLM request failed after retries" };
+  }
+
+  return { complete };
+}

package/lib/logger.js

@@ -0,0 +1,18 @@
+export function createLogger(client) {
+  async function log(scope, message, level = "debug") {
+    try {
+      await client?.app?.log?.({
+        body: {
+          service: "opencode-voice",
+          level,
+          message,
+          extra: { scope },
+        },
+      });
+    } catch {
+      // Logging should never interrupt voice features.
+    }
+  }
+
+  return { log };
+}

package/lib/notes-writer.js

@@ -0,0 +1,224 @@
+// Live-notes output: ordered Markdown transcript + lossless JSONL sidecar.
+//
+// Chunks are transcribed and normalized independently and may resolve out of
+// order (a slow LLM normalize call on chunk N can finish after a fast one on
+// chunk N+1). The writer buffers by sequence number and only appends once
+// every earlier chunk has been written, so the files are always in
+// recording order regardless of processing order.
+
+import fs from "node:fs";
+import path from "node:path";
+
+export function formatClockTime(ms) {
+  const totalSec = Math.max(0, Math.floor(ms / 1000));
+  const h = String(Math.floor(totalSec / 3600)).padStart(2, "0");
+  const m = String(Math.floor((totalSec % 3600) / 60)).padStart(2, "0");
+  const s = String(totalSec % 60).padStart(2, "0");
+  return `${h}:${m}:${s}`;
+}
+
+function normalizeWord(w) {
+  return w.toLowerCase().replace(/[^\p{L}\p{N}]/gu, "");
+}
+
+/**
+ * Forced chunk splits carry ~overlapMs of duplicate audio into the next
+ * chunk, so the transcribed text of consecutive chunks can share a few
+ * words at the boundary. Drop the longest run (up to maxWords) of leading
+ * words in `nextText` that exactly matches the trailing words of
+ * `prevText`, so the merged transcript reads once, not twice.
+ */
+export function mergeOverlapText(prevText, nextText, options = {}) {
+  const maxWords = options.maxWords ?? 8;
+  const prevWords = (prevText || "").trim().split(/\s+/).filter(Boolean);
+  const nextWords = (nextText || "").trim().split(/\s+/).filter(Boolean);
+  if (prevWords.length === 0 || nextWords.length === 0) return nextText || "";
+
+  const limit = Math.min(maxWords, prevWords.length, nextWords.length);
+  let bestK = 0;
+  for (let k = limit; k >= 1; k--) {
+    const prevTail = prevWords.slice(-k).map(normalizeWord).join(" ");
+    const nextHead = nextWords.slice(0, k).map(normalizeWord).join(" ");
+    if (prevTail && prevTail === nextHead) {
+      bestK = k;
+      break;
+    }
+  }
+  if (bestK === 0) return nextText || "";
+  return nextWords.slice(bestK).join(" ");
+}
+
+export function buildMarkdownHeader({ startedAt, language, model }) {
+  const lines = [
+    "# Live notes",
+    "",
+    `Started: ${startedAt}`,
+    `Language: ${language || "auto"}`,
+    `Model: ${model || "unknown"}`,
+    "",
+    "## Transcript",
+    "",
+  ];
+  return lines.join("\n");
+}
+
+export function buildMarkdownEntry({ startMs, text }) {
+  if (!text) return "";
+  return `[${formatClockTime(startMs)}] ${text}\n\n`;
+}
+
+export function buildJsonlLine(record) {
+  return JSON.stringify(record) + "\n";
+}
+
+function slugifyBaseName(name) {
+  return String(name || "notes")
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 60);
+}
+
+/**
+ * Default session file base name: 2026-09-24-143005-notes (title optional).
+ * Second resolution plus a per-process disambiguator so two sessions started
+ * in the same minute (or the same second across restarts) never share one
+ * append-only pair and mix their streams.
+ */
+export function buildSessionBaseName(startedAt, title) {
+  const d = startedAt instanceof Date ? startedAt : new Date(startedAt);
+  const pad = (n) => String(n).padStart(2, "0");
+  const stamp = `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}-${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}`;
+  const suffix = title ? slugifyBaseName(title) : "notes";
+  return `${stamp}-${suffix}`;
+}
+
+/**
+ * Resolve a collision-free basename: when a previous session already owns
+ * `base` (same second, restarted process, or clock skew), append -2, -3, …
+ * Keeps the documented one-pair-per-session invariant.
+ */
+export function resolveUniqueBaseName(dir, baseName) {
+  let candidate = baseName;
+  let n = 1;
+  while (
+    fs.existsSync(path.join(dir, `${candidate}.md`)) ||
+    fs.existsSync(path.join(dir, `${candidate}.raw.jsonl`))
+  ) {
+    n += 1;
+    candidate = `${baseName}-${n}`;
+  }
+  return candidate;
+}
+
+/**
+ * Create a live-notes writer bound to one recording session. `dir` is
+ * created if missing. Returns paths after `close()`.
+ */
+export function createNotesWriter({ dir, baseName, startedAt, language, model }) {
+  fs.mkdirSync(dir, { recursive: true });
+  // Atomically claim a collision-free basename: exclusive-create both files
+  // synchronously, so two sessions racing in the same tick cannot both pass
+  // an existsSync check and interleave appends into one pair.
+  let uniqueBase = baseName;
+  let mdPath;
+  let jsonlPath;
+  for (let n = 1; ; n += 1) {
+    uniqueBase = n === 1 ? baseName : `${baseName}-${n}`;
+    mdPath = path.join(dir, `${uniqueBase}.md`);
+    jsonlPath = path.join(dir, `${uniqueBase}.raw.jsonl`);
+    try {
+      fs.writeFileSync(mdPath, "", { flag: "wx" });
+      fs.writeFileSync(jsonlPath, "", { flag: "wx" });
+      break;
+    } catch (err) {
+      if (err?.code !== "EEXIST") throw err;
+      // We may have created mdPath just now while the jsonl name is taken
+      // (stale file from an older version): remove our half-claim so no
+      // orphan accumulates, then try the next suffix.
+      try {
+        if (err?.path === jsonlPath) fs.unlinkSync(mdPath);
+      } catch {}
+    }
+  }
+
+  const mdStream = fs.createWriteStream(mdPath, { flags: "a" });
+  const jsonlStream = fs.createWriteStream(jsonlPath, { flags: "a" });
+  mdStream.write(buildMarkdownHeader({ startedAt, language, model }));
+
+  let nextSeq = 0;
+  const pending = new Map();
+  let lastWrittenText = "";
+  let lastWrittenEndMs = 0;
+  let entriesWritten = 0;
+
+  function writeOne(record) {
+    jsonlStream.write(buildJsonlLine(record));
+    lastWrittenEndMs = record.endMs ?? lastWrittenEndMs;
+    // Skipped chunks (silence / hallucination / repeats) still advance the
+    // sequence in the JSONL sidecar, but must never reach the readable
+    // transcript - their `raw` is noise by definition.
+    if (record.skipped) return;
+    const text = record.normalized || record.raw || "";
+    if (!text) return;
+    const merged = record.forced ? mergeOverlapText(lastWrittenText, text) : text;
+    if (!merged.trim()) return;
+    mdStream.write(buildMarkdownEntry({ startMs: record.startMs, text: merged }));
+    lastWrittenText = merged;
+    entriesWritten += 1;
+  }
+
+  /**
+   * Append a processed chunk. Written immediately if it is the next chunk in
+   * sequence; otherwise held until earlier chunks arrive.
+   */
+  function appendChunk(record) {
+    pending.set(record.seq, record);
+    while (pending.has(nextSeq)) {
+      writeOne(pending.get(nextSeq));
+      pending.delete(nextSeq);
+      nextSeq += 1;
+    }
+  }
+
+  function pendingCount() {
+    return pending.size;
+  }
+
+  function entryCount() {
+    return entriesWritten;
+  }
+
+  function lastText() {
+    return lastWrittenText;
+  }
+
+  function lastWrittenEndMsGetter() {
+    return lastWrittenEndMs;
+  }
+
+  async function close() {
+    // Flush anything still buffered (out-of-order arrivals that never got
+    // their missing predecessor - e.g. a chunk whose transcription errored
+    // silently) in sequence-number order, so nothing is silently dropped.
+    for (const seq of [...pending.keys()].sort((a, b) => a - b)) {
+      writeOne(pending.get(seq));
+      pending.delete(seq);
+    }
+    await new Promise((resolve) => mdStream.end(resolve));
+    await new Promise((resolve) => jsonlStream.end(resolve));
+    return { mdPath, jsonlPath };
+  }
+
+  return {
+    appendChunk,
+    pendingCount,
+    entryCount,
+    lastText,
+    lastWrittenEndMs: lastWrittenEndMsGetter,
+    close,
+    mdPath,
+    jsonlPath,
+  };
+}

package/lib/session.js

@@ -0,0 +1,102 @@
+// Shared session helpers for OpenCode TUI plugin.
+
+/**
+ * Get the title of a specific session by ID. Returns "" if unknown or on error.
+ */
+export async function getSessionTitle(client, sessionID) {
+  if (!sessionID) return "";
+  try {
+    const result = await client.session.list();
+    const session = result.data?.find((s) => s.id === sessionID);
+    return session?.title || "";
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Get the title of the most recently updated session. Returns "" on error or
+ * when there are no sessions.
+ */
+export async function getActiveSessionTitle(client) {
+  try {
+    const result = await client.session.list();
+    if (!result.data || result.data.length === 0) return "";
+    const active = result.data.sort((a, b) => b.time.updated - a.time.updated)[0];
+    return active?.title || "";
+  } catch {
+    return "";
+  }
+}
+
+async function resolveSessionID(client, api) {
+  const route = api?.route?.current;
+  if (route?.name === "session" && route?.params?.sessionID) {
+    return route.params.sessionID;
+  }
+  try {
+    const result = await client.session.list();
+    if (!result.data || result.data.length === 0) return null;
+    const active = result.data.sort((a, b) => b.time.updated - a.time.updated)[0];
+    return active?.id || null;
+  } catch {
+    return null;
+  }
+}
+
+function messageText(api, msg) {
+  try {
+    const parts = api?.state?.part?.(msg.id) || [];
+    const text = parts
+      .filter((p) => p?.type === "text" && p?.text)
+      .map((p) => p.text.trim())
+      .filter(Boolean)
+      .join("\n");
+    if (text) return text;
+  } catch {}
+  // Compact sessions may only carry summaries on the message itself.
+  const summary = msg?.summary
+    ? [msg.summary.title, msg.summary.body].filter(Boolean).join(" — ")
+    : "";
+  return summary || "";
+}
+
+/**
+ * Get a compact, bounded slice of recent conversation turns for LLM context
+ * (e.g. STT normalization that must resolve names/pronouns like Cristina).
+ *
+ * Returns "user: ...\nassistant: ..." lines, newest last, capped at
+ * maxMessages turns and maxChars total (tail kept on overflow). Returns ""
+ * whenever context is unavailable - callers must treat that as "no context"
+ * and proceed without it.
+ */
+export async function getRecentConversationContext(client, api, options = {}) {
+  const maxMessages = Number(options.maxMessages) > 0 ? Math.floor(Number(options.maxMessages)) : 8;
+  const maxChars = Number(options.maxChars) > 0 ? Math.floor(Number(options.maxChars)) : 3000;
+  const PER_MESSAGE_CHARS = 800;
+  try {
+    const sessionID = await resolveSessionID(client, api);
+    if (!sessionID) return "";
+    const messages = api?.state?.session?.messages?.(sessionID) || [];
+    if (!Array.isArray(messages) || messages.length === 0) return "";
+    const lines = [];
+    for (const msg of messages.slice(-maxMessages)) {
+      const role = msg?.role === "assistant" ? "assistant" : "user";
+      let text = messageText(api, msg).trim().replace(/\s+/g, " ");
+      if (!text) continue;
+      if (text.length > PER_MESSAGE_CHARS) text = text.slice(0, PER_MESSAGE_CHARS) + "…";
+      lines.push(`${role}: ${text}`);
+    }
+    if (lines.length === 0) return "";
+    let joined = lines.join("\n");
+    if (joined.length > maxChars) {
+      let cut = joined.slice(joined.length - maxChars);
+      const newline = cut.indexOf("\n");
+      if (newline !== -1) cut = cut.slice(newline + 1);
+      joined = cut;
+    }
+    return joined;
+  } catch {
+    return "";
+  }
+}