@polderlabs/bizar 4.9.0 → 5.0.1

package/bizar-dash/src/server/routes/workspaces.mjs

@@ -0,0 +1,204 @@
+/**
+ * src/server/routes/workspaces.mjs
+ *
+ * v5.0.0 — Workspace management REST API.
+ *
+ * Endpoints:
+ *   GET    /api/workspaces                    — list user's workspaces
+ *   POST   /api/workspaces                    — create workspace
+ *   GET    /api/workspaces/:id                — get workspace details
+ *   DELETE /api/workspaces/:id                 — delete workspace (admin only)
+ *   POST   /api/workspaces/:id/invites        — create invite
+ *   GET    /api/workspaces/:id/invites        — list pending invites
+ *   DELETE /api/workspaces/:id/invites/:token — revoke invite
+ *   POST   /api/workspaces/:id/members/:userId — update member role
+ *   DELETE /api/workspaces/:id/members/:userId — remove member
+ *   POST   /api/invites/:token/accept         — accept invite
+ */
+import { Router } from 'express';
+import {
+  createWorkspace,
+  getWorkspace,
+  listWorkspacesWithRoles,
+  deleteWorkspace,
+  createInvite,
+  listInvites,
+  revokeInvite,
+  addMember,
+  removeMember,
+  updateMemberRole,
+  acceptInvite,
+  checkPermission,
+  listMembers,
+  ROLES,
+} from '../workspaces.mjs';
+import { getCurrentUserId, getCurrentWorkspaceId } from '../auth.mjs';
+import { wrap } from './_shared.mjs';
+
+/**
+ * @returns {import('express').Router}
+ */
+export function createWorkspacesRouter() {
+  const router = Router();
+
+  // GET /api/workspaces — list user's workspaces
+  router.get('/workspaces', wrap(async (req, res) => {
+    const userId = getCurrentUserId(req);
+    if (!userId) {
+      return res.status(401).json({ error: 'unauthorized', message: 'Not authenticated' });
+    }
+    const workspaces = await listWorkspacesWithRoles(userId);
+    res.json({ workspaces });
+  }));
+
+  // POST /api/workspaces — create workspace
+  router.post('/workspaces', wrap(async (req, res) => {
+    const userId = getCurrentUserId(req);
+    if (!userId) {
+      return res.status(401).json({ error: 'unauthorized', message: 'Not authenticated' });
+    }
+    const { name } = req.body || {};
+    if (!name || typeof name !== 'string' || !name.trim()) {
+      return res.status(400).json({ error: 'bad_request', message: 'Workspace name is required' });
+    }
+    const workspace = await createWorkspace({ name: name.trim(), ownerId: userId });
+    res.status(201).json({ workspace });
+  }));
+
+  // GET /api/workspaces/:id — get workspace details
+  router.get('/workspaces/:id', wrap(async (req, res) => {
+    const userId = getCurrentUserId(req);
+    if (!userId) {
+      return res.status(401).json({ error: 'unauthorized', message: 'Not authenticated' });
+    }
+    const { id } = req.params;
+    const workspace = await getWorkspace(id);
+    if (!workspace) {
+      return res.status(404).json({ error: 'not_found', message: 'Workspace not found' });
+    }
+    const hasAccess = await checkPermission(id, userId, ROLES.VIEWER);
+    if (!hasAccess) {
+      return res.status(403).json({ error: 'forbidden', message: 'Not a member of this workspace' });
+    }
+    const members = await listMembers(id);
+    res.json({ workspace, members });
+  }));
+
+  // DELETE /api/workspaces/:id — delete workspace (admin only)
+  router.delete('/workspaces/:id', wrap(async (req, res) => {
+    const userId = getCurrentUserId(req);
+    if (!userId) {
+      return res.status(401).json({ error: 'unauthorized', message: 'Not authenticated' });
+    }
+    const { id } = req.params;
+    const canDelete = await checkPermission(id, userId, ROLES.ADMIN);
+    if (!canDelete) {
+      return res.status(403).json({ error: 'forbidden', message: 'Admin role required' });
+    }
+    await deleteWorkspace(id);
+    res.json({ ok: true });
+  }));
+
+  // POST /api/workspaces/:id/invites — create invite
+  router.post('/workspaces/:id/invites', wrap(async (req, res) => {
+    const userId = getCurrentUserId(req);
+    if (!userId) {
+      return res.status(401).json({ error: 'unauthorized', message: 'Not authenticated' });
+    }
+    const { id } = req.params;
+    const { email, role } = req.body || {};
+    if (!email || typeof email !== 'string') {
+      return res.status(400).json({ error: 'bad_request', message: 'Email is required' });
+    }
+    if (!role || !Object.values(ROLES).includes(role)) {
+      return res.status(400).json({ error: 'bad_request', message: 'Valid role is required' });
+    }
+    const canInvite = await checkPermission(id, userId, ROLES.ADMIN);
+    if (!canInvite) {
+      return res.status(403).json({ error: 'forbidden', message: 'Admin role required to invite' });
+    }
+    const result = await createInvite(id, email, role, userId);
+    res.status(201).json(result);
+  }));
+
+  // GET /api/workspaces/:id/invites — list pending invites
+  router.get('/workspaces/:id/invites', wrap(async (req, res) => {
+    const userId = getCurrentUserId(req);
+    if (!userId) {
+      return res.status(401).json({ error: 'unauthorized', message: 'Not authenticated' });
+    }
+    const { id } = req.params;
+    const canView = await checkPermission(id, userId, ROLES.ADMIN);
+    if (!canView) {
+      return res.status(403).json({ error: 'forbidden', message: 'Admin role required' });
+    }
+    const invites = await listInvites(id);
+    res.json({ invites });
+  }));
+
+  // DELETE /api/workspaces/:id/invites/:token — revoke invite
+  router.delete('/workspaces/:id/invites/:token', wrap(async (req, res) => {
+    const userId = getCurrentUserId(req);
+    if (!userId) {
+      return res.status(401).json({ error: 'unauthorized', message: 'Not authenticated' });
+    }
+    const { id, token } = req.params;
+    const canRevoke = await checkPermission(id, userId, ROLES.ADMIN);
+    if (!canRevoke) {
+      return res.status(403).json({ error: 'forbidden', message: 'Admin role required' });
+    }
+    await revokeInvite(id, token);
+    res.json({ ok: true });
+  }));
+
+  // POST /api/workspaces/:id/members/:userId — update member role
+  router.post('/workspaces/:id/members/:userId', wrap(async (req, res) => {
+    const userId = getCurrentUserId(req);
+    if (!userId) {
+      return res.status(401).json({ error: 'unauthorized', message: 'Not authenticated' });
+    }
+    const { id, userId: targetUserId } = req.params;
+    const { role } = req.body || {};
+    if (!role || !Object.values(ROLES).includes(role)) {
+      return res.status(400).json({ error: 'bad_request', message: 'Valid role is required' });
+    }
+    const canUpdate = await checkPermission(id, userId, ROLES.ADMIN);
+    if (!canUpdate) {
+      return res.status(403).json({ error: 'forbidden', message: 'Admin role required' });
+    }
+    await updateMemberRole(id, targetUserId, role);
+    res.json({ ok: true, role });
+  }));
+
+  // DELETE /api/workspaces/:id/members/:userId — remove member
+  router.delete('/workspaces/:id/members/:userId', wrap(async (req, res) => {
+    const userId = getCurrentUserId(req);
+    if (!userId) {
+      return res.status(401).json({ error: 'unauthorized', message: 'Not authenticated' });
+    }
+    const { id, userId: targetUserId } = req.params;
+    const canRemove = await checkPermission(id, userId, ROLES.ADMIN);
+    if (!canRemove) {
+      return res.status(403).json({ error: 'forbidden', message: 'Admin role required' });
+    }
+    await removeMember(id, targetUserId);
+    res.json({ ok: true });
+  }));
+
+  // POST /api/invites/:token/accept — accept invite
+  router.post('/invites/:token/accept', wrap(async (req, res) => {
+    const userId = getCurrentUserId(req);
+    if (!userId) {
+      return res.status(401).json({ error: 'unauthorized', message: 'Not authenticated' });
+    }
+    const { token } = req.params;
+    const { email, name } = req.body || {};
+    if (!email || !name) {
+      return res.status(400).json({ error: 'bad_request', message: 'Email and name are required' });
+    }
+    const result = await acceptInvite(token, userId, email, name);
+    res.json({ ok: true, workspace: result.workspace, role: result.role });
+  }));
+
+  return router;
+}

package/bizar-dash/src/server/serve-info.mjs

@@ -56,6 +56,7 @@ import { readFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
 import { createConnection, isIP } from 'node:net';
+import { warn as loggerWarn, error as loggerError } from './logger.mjs';
 
 const HOME = homedir();
 
@@ -321,6 +322,147 @@ export async function listOpencodeSessions(info, timeoutMs = 5000) {
 
 export const SERVE_INFO_FILE_PATHS = DEFAULT_SERVE_INFO_FILES;
 
+// ── v5.0.0 — bug #4 — directory resolver (shared between route modules) ──
+//
+// Both `routes/opencode-sessions.mjs` and `routes/opencode-session-detail.mjs`
+// need the same logic: given a sessionId and the plugin's serve-info, figure
+// out which `directory` (worktree) to pass as a `?directory=…` query param
+// to opencode's HTTP API. We previously had two copies of this resolver
+// inline in each route; now there's one in serve-info.mjs so a fix here
+// reaches both routes.
+//
+// Strategy (per issue #4 brief):
+//   1. If serve.json has a `worktree` AND a fast probe (`GET
+//      /api/session/{id}?directory=<worktree>`) succeeds (HTTP 200), use
+//      the worktree — no need to list every opencode session.
+//   2. Otherwise, list every session via `GET /api/session` and find the
+//      one whose id matches. Use its `location.directory` (or the legacy
+//      `worktree` field, if present) as the directory.
+//   3. If neither yields a directory, return null — callers should 503
+//      so the UI can show "directory unknown" rather than sending the
+//      request with a blank `?directory=` (opencode 400s on that).
+//
+// `worktreeHasSession` is a small `GET /api/session/{id}?directory=...`
+// probe used as a fast-path so we don't pay the cost of listing every
+// session on every listMessages call. The endpoint returns 200 when the
+// session exists in that worktree, 404 when it doesn't. We treat 2xx
+// other than 200 as success (opencode has shipped both `200` and `204`
+// on this endpoint across versions).
+
+/**
+ * Lightweight probe — does `sessionId` exist in `worktree`?
+ *
+ * Implemented as `GET /api/session/{id}?directory={worktree}`. Returns
+ * `true` on 2xx, `false` on 404, `null` on network / auth / other
+ * errors (the caller should fall back to the slower list path and
+ * trust THAT result).
+ *
+ * Never throws.
+ *
+ * @param {ServeInfo} info
+ * @param {string} sessionId
+ * @param {string} worktree
+ * @param {number} [timeoutMs]
+ * @returns {Promise<boolean|null>}
+ */
+async function worktreeHasSession(info, sessionId, worktree, timeoutMs = 2_500) {
+  if (!info || !sessionId || !worktree) return null;
+  const url = `${info.baseUrl}/api/session/${encodeURIComponent(sessionId)}?directory=${encodeURIComponent(worktree)}`;
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, {
+      method: 'GET',
+      headers: {
+        Authorization: buildAuthHeader(info),
+        Accept: 'application/json',
+      },
+      signal: ac.signal,
+    });
+    if (res.status >= 200 && res.status < 300) return true;
+    if (res.status === 404) return false;
+    // 401/403/5xx → don't trust the result, let the fallback path decide.
+    return null;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Resolve the opencode `directory` (worktree) for a session.
+ *
+ * Per the brief:
+ *   1. If we have a worktree AND a fast probe confirms the session
+ *      lives there, return it.
+ *   2. Otherwise, list every session and find the matching one; use
+ *      its `location.directory` (or legacy `worktree`).
+ *   3. Return null if neither yields a directory.
+ *
+ * Signature is `(sessionId, serveInfo)` (positional, sessionId first)
+ * to match the brief. Callers that only have `serveInfo` can pass
+ * `null` for `sessionId` and the function will fall through to the
+ * list path.
+ *
+ * Never throws.
+ *
+ * @param {string|null|undefined} sessionId
+ * @param {ServeInfo|null|undefined} serveInfo
+ * @returns {Promise<string|null>}
+ */
+export async function resolveSessionDirectory(sessionId, serveInfo) {
+  if (!serveInfo) return null;
+
+  // Fast path: probe the recorded worktree first. If the session lives
+  // there, we save the round-trip to /api/session.
+  if (typeof serveInfo.worktree === 'string' && serveInfo.worktree.length > 0) {
+    const probe = await worktreeHasSession(serveInfo, sessionId || '', serveInfo.worktree);
+    if (probe === true) return serveInfo.worktree;
+  }
+
+  // Slower fallback: list every session and find the match.
+  try {
+    const sessions = await listOpencodeSessions(serveInfo, 5_000);
+    if (Array.isArray(sessions)) {
+      const entry = sessionId
+        ? sessions.find(
+            (s) =>
+              s && (s.id === sessionId || (typeof s.sessionId === 'string' && s.sessionId === sessionId)),
+          )
+        : null;
+      if (entry) {
+        const dir = entry?.location?.directory;
+        if (typeof dir === 'string' && dir.length > 0) return dir;
+        // Defensive: some opencode builds store the worktree on the
+        // session at the top level instead of under `location`.
+        const legacy = entry?.worktree;
+        if (typeof legacy === 'string' && legacy.length > 0) return legacy;
+      }
+      // No matching session, but we have a worktree from serve.json —
+      // last-chance fallback. This mirrors the pre-v5.0.0 inline
+      // resolver behaviour so an unmatched session still routes to
+      // the plugin's recorded cwd rather than 503'ing.
+      if (!entry && typeof serveInfo.worktree === 'string' && serveInfo.worktree.length > 0) {
+        return serveInfo.worktree;
+      }
+    } else if (typeof serveInfo.worktree === 'string' && serveInfo.worktree.length > 0) {
+      // listOpencodeSessions returned null (serve offline / auth fail).
+      // Fall back to the worktree so we at least try the same
+      // directory the plugin recorded — the upstream 404/502 will
+      // surface a clearer error than a 503 directory_unknown.
+      return serveInfo.worktree;
+    }
+  } catch (err) {
+    loggerWarn('resolveSessionDirectory: listOpencodeSessions failed', {
+      sessionId: sessionId || null,
+      err: err instanceof Error ? err.message : String(err),
+    });
+  }
+
+  return null;
+}
+
 // ── v3.5.4 (bug: dispatch stuck) — spawn helpers ─────────────────────────
 //
 // The dashboard's task delegator used to shell out to
@@ -473,8 +615,21 @@ export async function sendOpencodePrompt(info, opts, directory, timeoutMs = DEFA
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     const isAbort = err instanceof Error && err.name === 'AbortError';
+    let cause = 'unknown';
+    if (isAbort) cause = 'timeout';
+    else if (err && typeof err === 'object') {
+      const code = /** @type {any} */ (err).code;
+      if (typeof code === 'string' && code.length > 0) {
+        cause = code.startsWith('ECONN') || code.startsWith('UND_ERR') || code === 'ENOTFOUND'
+          ? 'network'
+          : code;
+      } else {
+        cause = 'network';
+      }
+    }
     return {
       ok: false,
+      cause,
       error: isAbort ? `sendPrompt timed out after ${timeoutMs}ms` : `sendPrompt network error: ${msg}`,
     };
   } finally {
@@ -543,8 +698,25 @@ export async function listOpencodeMessages(info, sessionId, directory, timeoutMs
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     const isAbort = err instanceof Error && err.name === 'AbortError';
+    // v5.0.0 — bug #4: surface a structured `cause` to the route so it
+    // can render a useful suggestion without substring-sniffing the
+    // error message. Prefers the underlying network error code
+    // (ECONNREFUSED, UND_ERR_SOCKET, …) when present.
+    let cause = 'unknown';
+    if (isAbort) cause = 'timeout';
+    else if (err && typeof err === 'object') {
+      const code = /** @type {any} */ (err).code;
+      if (typeof code === 'string' && code.length > 0) {
+        cause = code.startsWith('ECONN') || code.startsWith('UND_ERR') || code === 'ENOTFOUND'
+          ? 'network'
+          : code;
+      } else {
+        cause = 'network';
+      }
+    }
     return {
       ok: false,
+      cause,
       error: isAbort ? `listMessages timed out after ${timeoutMs}ms` : `listMessages network error: ${msg}`,
     };
   } finally {

package/bizar-dash/src/server/voice-store.mjs

@@ -0,0 +1,202 @@
+/**
+ * src/server/voice-store.mjs
+ *
+ * v5.0.0 — Voice note persistence layer.
+ *
+ * Audio files are stored at:
+ *   ~/.local/share/bizar/voice-notes/<id>.webm
+ *
+ * Markdown transcripts are written to the user's vault at:
+ *   <vaultPath>/.obsidian/voice-notes/<id>.md
+ * or (if no vaultPath is set) to the default vault:
+ *   ~/.local/share/bizar/voice-notes/transcripts/<id>.md
+ *
+ * Metadata index is at:
+ *   ~/.local/share/bizar/voice-notes/index.json
+ */
+
+import {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  renameSync,
+  mkdirSync,
+  readdirSync,
+  unlinkSync,
+} from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { randomBytes } from 'node:crypto';
+import { info, warn, child } from './logger.mjs';
+
+const log = child({ module: 'voice-store' });
+
+const HOME = homedir();
+const VOICE_DIR = join(HOME, '.local', 'share', 'bizar', 'voice-notes');
+const INDEX_FILE = join(VOICE_DIR, 'index.json');
+const TRANSCRIPT_DIR = join(VOICE_DIR, 'transcripts');
+
+// ── Paths ───────────────────────────────────────────────────────────────────
+
+function audioPath(id) {
+  return join(VOICE_DIR, `${id}.webm`);
+}
+
+function transcriptPath(id, vaultPath) {
+  if (vaultPath) {
+    const dir = join(vaultPath, '.obsidian', 'voice-notes');
+    return join(dir, `${id}.md`);
+  }
+  return join(TRANSCRIPT_DIR, `${id}.md`);
+}
+
+// ── Atomic helpers ──────────────────────────────────────────────────────────
+
+function atomicWriteJson(filePath, data) {
+  const tmp = `${filePath}.tmp.${process.pid}`;
+  writeFileSync(tmp, JSON.stringify(data, null, 2) + '\n', 'utf8');
+  renameSync(tmp, filePath);
+}
+
+// ── Index ───────────────────────────────────────────────────────────────────
+
+/**
+ * @typedef {Object} VoiceNote
+ * @property {string} id
+ * @property {string} audioPath
+ * @property {string|null} notePath  - markdown transcript path (may not exist yet)
+ * @property {string|null} transcript
+ * @property {number|null} durationSec
+ * @property {string|null} vaultPath
+ * @property {number} createdAtMs
+ * @property {number} updatedAtMs
+ */
+
+/** @returns {VoiceNote[]} */
+function loadIndex() {
+  try {
+    if (!existsSync(INDEX_FILE)) return [];
+    const text = readFileSync(INDEX_FILE, 'utf8');
+    if (!text.trim()) return [];
+    return JSON.parse(text);
+  } catch {
+    return [];
+  }
+}
+
+function saveIndex(notes) {
+  mkdirSync(dirname(INDEX_FILE), { recursive: true });
+  atomicWriteJson(INDEX_FILE, notes);
+}
+
+// ── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Save a voice note: write audio file + markdown transcript + update index.
+ *
+ * @param {{ audioBuffer: Buffer|Uint8Array, transcript: string|null, durationSec: number|null, vaultPath: string|null }} opts
+ * @returns {Promise<{ notePath: string, audioPath: string, id: string }>}
+ */
+export async function saveVoiceNote({ audioBuffer, transcript, durationSec, vaultPath }) {
+  const id = randomBytes(8).toString('hex');
+  const ap = audioPath(id);
+
+  // 1. Write audio (binary, no atomic needed for raw bytes — just ensure dir)
+  mkdirSync(dirname(ap), { recursive: true });
+  writeFileSync(ap, Buffer.from(audioBuffer));
+
+  // 2. Write markdown transcript if we have one
+  let notePath = null;
+  if (transcript) {
+    const tp = transcriptPath(id, vaultPath);
+    const tpDir = dirname(tp);
+    mkdirSync(tpDir, { recursive: true });
+    const md = [
+      '---',
+      `title: Voice Note ${new Date().toISOString().slice(0, 16).replace('T', ' ')}`,
+      `date: ${new Date().toISOString()}`,
+      `type: voice-note`,
+      `audio: ${id}.webm`,
+      `duration: ${durationSec ?? '?'}`,
+      '---',
+      '',
+      `# ${new Date().toLocaleDateString('en-US', { weekday: 'long', year: 'numeric', month: 'long', day: 'numeric' })}`,
+      '',
+      transcript,
+    ].join('\n');
+    writeFileSync(tp, md, 'utf8');
+    notePath = tp;
+  }
+
+  // 3. Update index
+  const notes = loadIndex();
+  /** @type {VoiceNote} */
+  const entry = {
+    id,
+    audioPath: ap,
+    notePath,
+    transcript: transcript || null,
+    durationSec: durationSec || null,
+    vaultPath: vaultPath || null,
+    createdAtMs: Date.now(),
+    updatedAtMs: Date.now(),
+  };
+  notes.unshift(entry); // newest first
+  saveIndex(notes);
+
+  log.info('voice note saved', { id, notePath, audioPath: ap });
+  return { notePath, audioPath: ap, id };
+}
+
+/**
+ * @param {{ vaultPath?: string|null, limit?: number }} opts
+ * @returns {VoiceNote[]}
+ */
+export function listVoiceNotes({ vaultPath = null, limit = 50 } = {}) {
+  const notes = loadIndex();
+  const filtered = vaultPath
+    ? notes.filter((n) => n.vaultPath === vaultPath)
+    : notes;
+  return filtered.slice(0, limit);
+}
+
+/**
+ * @param {string} id
+ * @returns {VoiceNote|undefined}
+ */
+export function getVoiceNote(id) {
+  return loadIndex().find((n) => n.id === id);
+}
+
+/**
+ * @param {string} id
+ * @returns {boolean}
+ */
+export function deleteVoiceNote(id) {
+  const notes = loadIndex();
+  const idx = notes.findIndex((n) => n.id === id);
+  if (idx === -1) return false;
+
+  const { audioPath: ap, notePath: tp } = notes[idx];
+
+  // Remove audio file
+  try {
+    if (existsSync(ap)) unlinkSync(ap);
+  } catch (err) {
+    warn('failed to remove audio file', { id, ap, err: err.message });
+  }
+
+  // Remove transcript file
+  if (tp) {
+    try {
+      if (existsSync(tp)) unlinkSync(tp);
+    } catch (err) {
+      warn('failed to remove transcript file', { id, tp, err: err.message });
+    }
+  }
+
+  notes.splice(idx, 1);
+  saveIndex(notes);
+  log.info('voice note deleted', { id });
+  return true;
+}

package/bizar-dash/src/server/voice-transcribe.mjs

@@ -0,0 +1,72 @@
+/**
+ * src/server/voice-transcribe.mjs
+ *
+ * v5.0.0 — Whisper transcription for voice notes.
+ *
+ * Uses OpenAI Whisper API (or a compatible BIZAR_WHISPER_ENDPOINT).
+ * Returns null on failure so callers can degrade gracefully.
+ */
+
+import { info, warn, child } from './logger.mjs';
+
+const log = child({ module: 'voice-transcribe' });
+
+/**
+ * Transcribe an audio buffer via Whisper.
+ *
+ * @param {Buffer|Uint8Array} audioBuffer - raw audio bytes
+ * @param {{ mimeType?: string }} opts
+ * @returns {Promise<string|null>} transcript text or null
+ */
+export async function transcribe(audioBuffer, { mimeType = 'audio/webm' } = {}) {
+  if (!process.env.OPENAI_API_KEY && !process.env.BIZAR_WHISPER_ENDPOINT) {
+    log.debug('no whisper credentials configured, skipping transcription');
+    return null;
+  }
+
+  const endpoint =
+    process.env.BIZAR_WHISPER_ENDPOINT || 'https://api.openai.com/v1/audio/transcriptions';
+
+  const body = new FormData();
+  body.append(
+    'file',
+    new Blob([audioBuffer], { type: mimeType }),
+    'audio.webm',
+  );
+  body.append('model', 'whisper-1');
+
+  const headers = {};
+  if (process.env.OPENAI_API_KEY) {
+    headers['Authorization'] = `Bearer ${process.env.OPENAI_API_KEY}`;
+  }
+  // BIZAR_WHISPER_ENDPOINT may be a local proxy that doesn't need auth
+  // but may also support Authorization header — only set if key exists
+
+  log.info('submitting audio to whisper', { endpoint, sizeBytes: audioBuffer.byteLength });
+
+  let resp;
+  try {
+    resp = await fetch(endpoint, { method: 'POST', body, headers });
+  } catch (err) {
+    warn('whisper fetch failed', { err: err.message });
+    return null;
+  }
+
+  if (!resp.ok) {
+    const text = await resp.text().catch(() => '');
+    warn('whisper returned error', { status: resp.status, body: text });
+    return null;
+  }
+
+  let data;
+  try {
+    data = await resp.json();
+  } catch {
+    warn('whisper returned non-JSON');
+    return null;
+  }
+
+  const text = typeof data.text === 'string' ? data.text.trim() : null;
+  log.info('transcription complete', { textLength: text?.length ?? 0 });
+  return text;
+}