kimaki 0.4.76 → 0.4.78

package/dist/system-message.js

@@ -65,7 +65,7 @@ this feature by restarting kimaki with the \`--no-critique\` flag.
 
 ### reviewing diffs with AI
 
-\`critique review --web\` generates an AI-powered review of a diff and uploads it as a shareable URL.
+\`bunx critique review --web\` generates an AI-powered review of a diff and uploads it as a shareable URL.
 It spawns a separate opencode session that analyzes the diff, groups related changes, and produces
 a structured review with explanations, diagrams, and suggestions. This is useful when the user
 asks you to explain or review a diff — the output is much richer than a plain diff URL.
@@ -106,7 +106,7 @@ The command prints a preview URL when done — share that URL with the user.
 const KIMAKI_TUNNEL_INSTRUCTIONS = `
 ## running dev servers with tunnel access
 
-ALWAYS use \`kimaki tunnel\` when starting any dev server. NEVER run \`pnpm dev\`, \`npm run dev\`, or any dev server command without wrapping it in \`kimaki tunnel\`. The user is on Discord, not at the terminal — localhost URLs are useless to them. They need a tunnel URL to access the site.
+ALWAYS use \`kimaki tunnel\` when starting any dev server. NEVER run \`pnpm dev\`, \`npm run dev\`, or any dev server command without wrapping it in \`kimaki tunnel\`. Always invoke Kimaki directly as \`kimaki\`, never via \`npx\` or \`bunx\`. The user is on Discord, not at the terminal — localhost URLs are useless to them. They need a tunnel URL to access the site.
 
 Use \`tmux\` to run the tunnel + dev server combo in the background so it persists across commands.
 
@@ -131,7 +131,7 @@ Use random tunnel IDs by default. Only pass \`-t\` when exposing a service that
 tmux new-session -d -s myapp-dev
 
 # Run the dev server with kimaki tunnel inside the session
-tmux send-keys -t myapp-dev "npx kimaki tunnel -p 3000 -- pnpm dev" Enter
+tmux send-keys -t myapp-dev "kimaki tunnel -p 3000 -- pnpm dev" Enter
 \`\`\`
 
 ### getting the tunnel URL
@@ -146,15 +146,15 @@ tmux capture-pane -t myapp-dev -p | grep -i "tunnel"
 \`\`\`bash
 # Next.js project
 tmux new-session -d -s projectname-nextjs-dev-3000
-tmux send-keys -t nextjs-dev "npx kimaki tunnel -p 3000 -- pnpm dev" Enter
+tmux send-keys -t nextjs-dev "kimaki tunnel -p 3000 -- pnpm dev" Enter
 
 # Vite project on port 5173
 tmux new-session -d -s vite-dev-5173
-tmux send-keys -t vite-dev "npx kimaki tunnel -p 5173 -- pnpm dev" Enter
+tmux send-keys -t vite-dev "kimaki tunnel -p 5173 -- pnpm dev" Enter
 
 # Custom tunnel ID (only for intentionally public-safe services)
 tmux new-session -d -s holocron-dev
-tmux send-keys -t holocron-dev "npx kimaki tunnel -p 3000 -t holocron -- pnpm dev" Enter
+tmux send-keys -t holocron-dev "kimaki tunnel -p 3000 -t holocron -- pnpm dev" Enter
 \`\`\`
 
 ### stopping the dev server
@@ -217,7 +217,7 @@ If there are internal kimaki issues (sessions not responding, bot errors, unexpe
 
 To upload files to the Discord thread (images, screenshots, long files that would clutter the chat), run:
 
-npx -y kimaki upload-to-discord --session ${sessionId} <file1> [file2] ...
+kimaki upload-to-discord --session ${sessionId} <file1> [file2] ...
 
 ## requesting files from the user
 
@@ -227,7 +227,7 @@ To ask the user to upload files from their device, use the \`kimaki_file_upload\
 
 To archive the current Discord thread (hide it from sidebar) and stop the session, run:
 
-npx -y kimaki session archive --session ${sessionId}
+kimaki session archive --session ${sessionId}
 
 Only do this when the user explicitly asks to close or archive the thread, and only after your final message.
 
@@ -235,7 +235,7 @@ Only do this when the user explicitly asks to close or archive the thread, and o
 
 To search for Discord users in a guild (needed for mentions like <@userId>), run:
 
-npx -y kimaki user list --guild ${guildId || '<guildId>'} --query "username"
+kimaki user list --guild ${guildId || '<guildId>'} --query "username"
 
 This returns user IDs you can use for Discord mentions.
 ${channelId
@@ -244,7 +244,7 @@ ${channelId
 
 To start a new thread/session in this channel pro-grammatically, run:
 
-npx -y kimaki send --channel ${channelId} --prompt "your prompt here"${agentFlag}${username ? ` --user "${username}"` : ''}
+kimaki send --channel ${channelId} --prompt "your prompt here"${agentFlag}${username ? ` --user "${username}"` : ''}
 
 You can use this to "spawn" parallel helper sessions like teammates: start new threads with focused prompts, then come back and collect the results.
 
@@ -252,23 +252,23 @@ IMPORTANT: NEVER use \`--worktree\` unless the user explicitly asks for a worktr
 
 To send a prompt to an existing thread instead of creating a new one:
 
-npx -y kimaki send --thread <thread_id> --prompt "follow-up prompt"
+kimaki send --thread <thread_id> --prompt "follow-up prompt"
 
 Use this when you already have the Discord thread ID.
 
 To send to the thread associated with a known session:
 
-npx -y kimaki send --session <session_id> --prompt "follow-up prompt"
+kimaki send --session <session_id> --prompt "follow-up prompt"
 
 Use this when you have the OpenCode session ID.
 
 Use --notify-only to create a notification thread without starting an AI session:
 
-npx -y kimaki send --channel ${channelId} --prompt "User cancelled subscription" --notify-only
+kimaki send --channel ${channelId} --prompt "User cancelled subscription" --notify-only
 
 Use --worktree to create a git worktree for the session (ONLY when the user explicitly asks for a worktree):
 
-npx -y kimaki send --channel ${channelId} --prompt "Add dark mode support" --worktree dark-mode${agentFlag}${username ? ` --user "${username}"` : ''}
+kimaki send --channel ${channelId} --prompt "Add dark mode support" --worktree dark-mode${agentFlag}${username ? ` --user "${username}"` : ''}
 
 Important:
 - NEVER use \`--worktree\` unless the user explicitly requests a worktree. Most tasks should use normal threads without worktrees.
@@ -278,18 +278,21 @@ Important:
 
 Use --agent to specify which agent to use for the session:
 
-npx -y kimaki send --channel ${channelId} --prompt "Plan the refactor of the auth module" --agent plan${username ? ` --user "${username}"` : ''}
+kimaki send --channel ${channelId} --prompt "Plan the refactor of the auth module" --agent plan${username ? ` --user "${username}"` : ''}
 ${agents && agents.length > 0 ? `
 Available agents:
 ${agents.map((a) => { return `- \`${a.name}\`${a.name === currentAgent ? ' (current)' : ''}${a.description ? `: ${a.description}` : ''}`; }).join('\n')}
 ` : ''}
+## switching agents in the current session
+
+The user can switch the active agent mid-session using the Discord slash command \`/<agentname>-agent\`. For example if you are in plan mode and the user asks you to edit files, tell them to run \`/build-agent\` to switch to the build agent first.
 
 ## scheduled sends and task management
 
 Use \`--send-at\` to schedule a one-time or recurring task:
 
-npx -y kimaki send --channel ${channelId} --prompt "Reminder: review open PRs" --send-at "2026-03-01T09:00:00Z"
-npx -y kimaki send --channel ${channelId} --prompt "Run weekly test suite and summarize failures" --send-at "0 9 * * 1"
+kimaki send --channel ${channelId} --prompt "Reminder: review open PRs" --send-at "2026-03-01T09:00:00Z"
+kimaki send --channel ${channelId} --prompt "Run weekly test suite and summarize failures" --send-at "0 9 * * 1"
 
 When using a date for \`--send-at\`, it must be UTC in ISO format ending with \`Z\`.
 
@@ -321,13 +324,13 @@ kimaki task delete <id>
 
 Use case patterns:
 - Reminder flows: create deadline reminders in this channel with one-time \`--send-at\`; mention only if action is required.
-- Proactive reminders: when you encounter time-sensitive information during your work (e.g. creating an API key that expires in 90 days, a certificate with an expiration date, a trial period ending, a deadline mentioned in code comments), proactively schedule a \`--notify-only\` reminder before the expiration so the user gets notified in time. For example, if you generate an API key expiring on 2026-06-01, schedule a reminder a few days before: \`npx -y kimaki send --channel ${channelId} --prompt "Reminder: <@${userId || 'USER_ID'}> the API key created on 2026-03-01 expires on 2026-06-01. Renew it before it breaks production." --send-at "2026-05-28T09:00:00Z" --notify-only\`. Always tell the user you scheduled the reminder so they know.
+- Proactive reminders: when you encounter time-sensitive information during your work (e.g. creating an API key that expires in 90 days, a certificate with an expiration date, a trial period ending, a deadline mentioned in code comments), proactively schedule a \`--notify-only\` reminder before the expiration so the user gets notified in time. For example, if you generate an API key expiring on 2026-06-01, schedule a reminder a few days before: \`kimaki send --channel ${channelId} --prompt "Reminder: <@${userId || 'USER_ID'}> the API key created on 2026-03-01 expires on 2026-06-01. Renew it before it breaks production." --send-at "2026-05-28T09:00:00Z" --notify-only\`. Always tell the user you scheduled the reminder so they know.
 - Weekly QA: schedule "run full test suite, inspect failures, post summary, and mention ${username ? `@${username}` : '@username'} only when failures require review".
 - Weekly benchmark automation: schedule a benchmark prompt that runs model evals, writes JSON outputs in the repo, commits results, and mentions only for regressions.
 - Recurring maintenance: use cron \`--send-at\` for repetitive tasks like rotating secrets, checking dependency updates, running security audits, or cleaning up stale branches. Example: \`--send-at "0 9 1 * *"\` to run on the 1st of every month.
 - Thread reminders: when the user says "remind me about this in 2 hours" (or any duration), use \`--send-at\` with \`--thread\` to resurface the current thread. Compute the future UTC time and send a mention so Discord shows a notification:
 
-npx -y kimaki send --session ${sessionId} --prompt "Reminder: <@${userId || 'USER_ID'}> you asked to be reminded about this thread." --send-at "<future_UTC_time>" --notify-only
+kimaki send --session ${sessionId} --prompt "Reminder: <@${userId || 'USER_ID'}> you asked to be reminded about this thread." --send-at "<future_UTC_time>" --notify-only
 
 Replace \`<future_UTC_time>\` with the computed UTC ISO timestamp. The \`--notify-only\` flag creates just a notification message without starting a new AI session. The \`<@userId>\` mention ensures the user gets a Discord notification.
 
@@ -342,7 +345,7 @@ ONLY create worktrees when the user explicitly asks for one. Never proactively u
 When the user asks to "create a worktree" or "make a worktree", they mean you should use the kimaki CLI to create it. Do NOT use raw \`git worktree add\` commands. Instead use:
 
 \`\`\`bash
-npx -y kimaki send --channel ${channelId} --prompt "your task description" --worktree worktree-name${agentFlag}${username ? ` --user "${username}"` : ''}
+kimaki send --channel ${channelId} --prompt "your task description" --worktree worktree-name${agentFlag}${username ? ` --user "${username}"` : ''}
 \`\`\`
 
 This creates a new Discord thread with an isolated git worktree and starts a session in it. The worktree name should be kebab-case and descriptive of the task.
@@ -360,7 +363,7 @@ This is useful for automation (cron jobs, GitHub webhooks, n8n, etc.)
 When you are approaching the **context window limit** or the user explicitly asks to **handoff to a new thread**, use the \`kimaki send\` command to start a fresh session with context:
 
 \`\`\`bash
-npx -y kimaki send --channel ${channelId} --prompt "Continuing from previous session: <summary of current task and state>"${agentFlag}${username ? ` --user "${username}"` : ''}
+kimaki send --channel ${channelId} --prompt "Continuing from previous session: <summary of current task and state>"${agentFlag}${username ? ` --user "${username}"` : ''}
 \`\`\`
 
 The command automatically handles long prompts (over 2000 chars) by sending them as file attachments.
@@ -444,10 +447,10 @@ If your Bash tool timeout triggers anyway, fall back to reading the session outp
 
 \`\`\`bash
 # Start a session and wait for it to finish
-npx -y kimaki send --channel <channel_id> --prompt "Fix the auth bug" --wait
+kimaki send --channel <channel_id> --prompt "Fix the auth bug" --wait
 
 # Send to an existing thread and wait
-npx -y kimaki send --thread <thread_id> --prompt "Run the tests" --wait
+kimaki send --thread <thread_id> --prompt "Run the tests" --wait
 \`\`\`
 
 The command exits with the session markdown on stdout once the model finishes responding.

package/dist/test-utils.js

@@ -6,6 +6,22 @@
 // Prefers using the existing opencode client (already running server) to avoid
 // spawning a new server process during teardown. Falls back to initializing
 // a new server only if no existing client is available.
+/**
+ * Deterministic port from a string key (channel ID, test file name, etc.).
+ * Uses a hash to pick a stable port in range 53000-54999, avoiding overlap
+ * with queue-advanced tests (51000-52999) and getLockPort (30000-39999).
+ * Replaces the old TOCTOU-prone pattern of binding port 0, reading the
+ * assigned port, closing, then rebinding — which races under parallel vitest.
+ */
+export function chooseLockPort({ key }) {
+    let hash = 0;
+    for (let i = 0; i < key.length; i++) {
+        const char = key.charCodeAt(i);
+        hash = (hash << 5) - hash + char;
+        hash |= 0;
+    }
+    return 53_000 + (Math.abs(hash) % 2_000);
+}
 import { getOpencodeClient, initializeOpencodeForDirectory, } from './opencode.js';
 import { getThreadState, } from './session-handler/thread-runtime-state.js';
 /**

package/dist/thread-message-queue.e2e.test.js

@@ -9,7 +9,6 @@
 // If total duration of a file exceeds ~10s, split into a new test file
 // so vitest can parallelize across files.
 import fs from 'node:fs';
-import net from 'node:net';
 import path from 'node:path';
 import url from 'node:url';
 import { describe, beforeAll, afterAll, test, expect } from 'vitest';
@@ -22,7 +21,7 @@ import { startDiscordBot } from './discord-bot.js';
 import { setBotToken, initDatabase, closeDatabase, setChannelDirectory, setChannelVerbosity, getChannelVerbosity, } from './database.js';
 import { startHranaServer, stopHranaServer } from './hrana-server.js';
 import { initializeOpencodeForDirectory, stopOpencodeServer } from './opencode.js';
-import { cleanupTestSessions, waitForFooterMessage, waitForBotMessageContaining, waitForMessageById, waitForBotMessageCount, waitForBotReplyAfterUserMessage, waitForThreadState, } from './test-utils.js';
+import { chooseLockPort, cleanupTestSessions, waitForFooterMessage, waitForBotMessageContaining, waitForMessageById, waitForBotMessageCount, waitForBotReplyAfterUserMessage, waitForThreadState, } from './test-utils.js';
 const e2eTest = describe;
 function createRunDirectories() {
     const root = path.resolve(process.cwd(), 'tmp', 'thread-queue-e2e');
@@ -32,23 +31,6 @@ function createRunDirectories() {
     fs.mkdirSync(projectDirectory, { recursive: true });
     return { root, dataDir, projectDirectory };
 }
-function chooseLockPort() {
-    return new Promise((resolve, reject) => {
-        const server = net.createServer();
-        server.listen(0, () => {
-            const address = server.address();
-            if (!address || typeof address === 'string') {
-                server.close();
-                reject(new Error('Failed to resolve lock port'));
-                return;
-            }
-            const port = address.port;
-            server.close(() => {
-                resolve(port);
-            });
-        });
-    });
-}
 function createDiscordJsClient({ restUrl }) {
     return new Client({
         intents: [
@@ -233,7 +215,7 @@ e2eTest('thread message queue ordering', () => {
     beforeAll(async () => {
         testStartTime = Date.now();
         directories = createRunDirectories();
-        const lockPort = await chooseLockPort();
+        const lockPort = chooseLockPort({ key: TEXT_CHANNEL_ID });
         process.env['KIMAKI_LOCK_PORT'] = String(lockPort);
         setDataDir(directories.dataDir);
         previousDefaultVerbosity = store.getState().defaultVerbosity;

package/dist/utils.js

@@ -58,11 +58,13 @@ export function generateDiscordInstallUrlForBot({ appId, mode, clientId, clientS
     // This initiates the better-auth OAuth flow with clientId/clientSecret
     // as additionalData, which better-auth stores in its verification table
     // and recovers after Discord redirects back to the callback.
+    // Use a kimaki-specific callback field name to avoid ambiguity with
+    // better-auth's own callbackURL state field.
     const url = new URL(`${KIMAKI_WEBSITE_URL}/discord-install`);
     url.searchParams.set('clientId', clientId);
     url.searchParams.set('clientSecret', clientSecret);
     if (gatewayCallbackUrl) {
-        url.searchParams.set('callbackUrl', gatewayCallbackUrl);
+        url.searchParams.set('kimakiCallbackUrl', gatewayCallbackUrl);
     }
     return url.toString();
 }

package/dist/voice-message.e2e.test.js

@@ -8,7 +8,6 @@
 // Tests assert on both Discord messages (via digital twin) and session state
 // transitions (via getThreadState from the zustand store).
 import fs from 'node:fs';
-import net from 'node:net';
 import path from 'node:path';
 import url from 'node:url';
 import { describe, beforeAll, afterAll, beforeEach, test, expect } from 'vitest';
@@ -21,7 +20,7 @@ import { startDiscordBot } from './discord-bot.js';
 import { setBotToken, initDatabase, closeDatabase, setChannelDirectory, setChannelVerbosity, } from './database.js';
 import { startHranaServer, stopHranaServer } from './hrana-server.js';
 import { initializeOpencodeForDirectory, getOpencodeClient, stopOpencodeServer } from './opencode.js';
-import { cleanupTestSessions, waitForFooterMessage, waitForBotMessageContaining, waitForThreadState, } from './test-utils.js';
+import { chooseLockPort, cleanupTestSessions, waitForFooterMessage, waitForBotMessageContaining, waitForThreadState, } from './test-utils.js';
 import { getThreadState } from './session-handler/thread-runtime-state.js';
 const e2eTest = describe;
 // ── Helpers ──────────────────────────────────────────────────────
@@ -33,23 +32,6 @@ function createRunDirectories() {
     fs.mkdirSync(projectDirectory, { recursive: true });
     return { root, dataDir, projectDirectory };
 }
-function chooseLockPort() {
-    return new Promise((resolve, reject) => {
-        const server = net.createServer();
-        server.listen(0, () => {
-            const address = server.address();
-            if (!address || typeof address === 'string') {
-                server.close();
-                reject(new Error('Failed to resolve lock port'));
-                return;
-            }
-            const port = address.port;
-            server.close(() => {
-                resolve(port);
-            });
-        });
-    });
-}
 function createDiscordJsClient({ restUrl }) {
     return new Client({
         intents: [
@@ -245,7 +227,7 @@ e2eTest('voice message handling', () => {
     beforeAll(async () => {
         testStartTime = Date.now();
         directories = createRunDirectories();
-        const lockPort = await chooseLockPort();
+        const lockPort = chooseLockPort({ key: TEXT_CHANNEL_ID });
         process.env['KIMAKI_LOCK_PORT'] = String(lockPort);
         setDataDir(directories.dataDir);
         previousDefaultVerbosity = store.getState().defaultVerbosity;

package/dist/voice.js

@@ -21,7 +21,36 @@ const OPENAI_SUPPORTED_AUDIO_TYPES = new Set([
     'audio/mpeg',
     'audio/mp3',
     'audio/wav',
+    'audio/x-wav',
 ]);
+const OGG_AUDIO_TYPES = new Set([
+    'audio/ogg',
+    'audio/opus',
+]);
+const M4A_AUDIO_TYPES = new Set([
+    'audio/mp4',
+    'audio/m4a',
+    'audio/x-m4a',
+]);
+export function normalizeAudioMediaType(mediaType) {
+    const normalized = mediaType.trim().toLowerCase();
+    if (normalized === 'audio/x-m4a' || normalized === 'audio/m4a') {
+        return 'audio/mp4';
+    }
+    return normalized;
+}
+export function getOpenAIAudioConversionStrategy(mediaType) {
+    if (OPENAI_SUPPORTED_AUDIO_TYPES.has(mediaType)) {
+        return 'none';
+    }
+    if (OGG_AUDIO_TYPES.has(mediaType)) {
+        return 'convert-ogg-to-wav';
+    }
+    if (M4A_AUDIO_TYPES.has(mediaType)) {
+        return 'convert-m4a-to-wav';
+    }
+    return 'unsupported';
+}
 /**
  * Convert OGG Opus audio to WAV using prism-media (already installed for Discord voice).
  * Pipeline: OGG buffer → OggDemuxer → Opus Decoder → PCM → WAV (with header).
@@ -64,6 +93,74 @@ export function convertOggToWav(input) {
         Readable.from(input).pipe(demuxer).pipe(decoder);
     });
 }
+/**
+ * Convert M4A/MP4 audio to WAV using prism-media FFmpeg wrapper.
+ * This depends on an ffmpeg binary available in PATH.
+ */
+export function convertM4aToWav(input) {
+    return new Promise((resolve) => {
+        const pcmChunks = [];
+        const transcoder = new prism.FFmpeg({
+            args: [
+                '-analyzeduration',
+                '0',
+                '-loglevel',
+                '0',
+                '-f',
+                'mp4',
+                '-i',
+                'pipe:0',
+                '-f',
+                's16le',
+                '-acodec',
+                'pcm_s16le',
+                '-ac',
+                '1',
+                '-ar',
+                '48000',
+                'pipe:1',
+            ],
+        });
+        transcoder.on('data', (chunk) => {
+            pcmChunks.push(chunk);
+        });
+        transcoder.on('end', () => {
+            const pcmData = Buffer.concat(pcmChunks);
+            if (pcmData.length === 0) {
+                resolve(new TranscriptionError({
+                    reason: 'FFmpeg conversion produced empty audio output',
+                }));
+                return;
+            }
+            const wavHeader = createWavHeader({
+                dataLength: pcmData.length,
+                sampleRate: 48000,
+                numChannels: 1,
+                bitsPerSample: 16,
+            });
+            resolve(Buffer.concat([wavHeader, pcmData]));
+        });
+        transcoder.on('error', (err) => {
+            const lower = err.message.toLowerCase();
+            const isMissingFfmpeg = lower.includes('ffmpeg') &&
+                (lower.includes('not found') ||
+                    lower.includes('enoent') ||
+                    lower.includes('spawn'));
+            if (isMissingFfmpeg) {
+                resolve(new TranscriptionError({
+                    reason: 'M4A transcription with OpenAI requires ffmpeg to be installed and available in PATH',
+                    cause: err,
+                }));
+                return;
+            }
+            resolve(new TranscriptionError({
+                reason: `M4A decode failed: ${err.message}`,
+                cause: err,
+            }));
+        });
+        Readable.from(input).pipe(transcoder);
+    });
+}
 function createWavHeader({ dataLength, sampleRate, numChannels, bitsPerSample, }) {
     const byteRate = (sampleRate * numChannels * bitsPerSample) / 8;
     const blockAlign = (numChannels * bitsPerSample) / 8;
@@ -225,17 +322,33 @@ export async function transcribeAudio({ audio, prompt, language, temperature, ap
     if (audioBuffer.length === 0) {
         return new InvalidAudioFormatError();
     }
-    let mediaType = mediaTypeParam || 'audio/mpeg';
+    let mediaType = normalizeAudioMediaType(mediaTypeParam || 'audio/mpeg');
     let finalAudioBase64 = audioBuffer.toString('base64');
-    // OpenAI input_audio only supports mp3/wav. Convert OGG Opus (Discord voice) to WAV.
-    if (resolvedProvider === 'openai' && !OPENAI_SUPPORTED_AUDIO_TYPES.has(mediaType)) {
-        voiceLogger.log(`Converting ${mediaType} to WAV for OpenAI compatibility`);
-        const converted = await convertOggToWav(audioBuffer);
-        if (converted instanceof Error) {
-            return converted;
+    // OpenAI input_audio supports only a subset of audio formats.
+    // Convert based on MIME so OGG conversion runs only for real OGG/Opus inputs.
+    if (resolvedProvider === 'openai') {
+        const conversionStrategy = getOpenAIAudioConversionStrategy(mediaType);
+        if (conversionStrategy === 'convert-ogg-to-wav') {
+            voiceLogger.log(`Converting ${mediaType} to WAV for OpenAI compatibility`);
+            const converted = await convertOggToWav(audioBuffer);
+            if (converted instanceof Error) {
+                return converted;
+            }
+            finalAudioBase64 = converted.toString('base64');
+            mediaType = 'audio/wav';
+        }
+        else if (conversionStrategy === 'convert-m4a-to-wav') {
+            voiceLogger.log(`Converting ${mediaType} to WAV for OpenAI compatibility`);
+            const converted = await convertM4aToWav(audioBuffer);
+            if (converted instanceof Error) {
+                return converted;
+            }
+            finalAudioBase64 = converted.toString('base64');
+            mediaType = 'audio/wav';
+        }
+        else if (conversionStrategy === 'unsupported') {
+            return new InvalidAudioFormatError();
         }
-        finalAudioBase64 = converted.toString('base64');
-        mediaType = 'audio/wav';
     }
     const languageHint = language ? `The audio is in ${language}.\n\n` : '';
     // build session context section

package/dist/voice.test.js

@@ -3,8 +3,23 @@
 import { describe, test, expect } from 'vitest';
 import fs from 'node:fs';
 import path from 'node:path';
-import { transcribeAudio, convertOggToWav } from './voice.js';
-import { extractTranscription } from './voice.js';
+import { transcribeAudio, convertOggToWav, extractTranscription, normalizeAudioMediaType, getOpenAIAudioConversionStrategy, } from './voice.js';
+describe('audio media type routing', () => {
+    test('normalizes m4a aliases to audio/mp4', () => {
+        expect(normalizeAudioMediaType('audio/x-m4a')).toMatchInlineSnapshot('"audio/mp4"');
+        expect(normalizeAudioMediaType('audio/m4a')).toMatchInlineSnapshot('"audio/mp4"');
+    });
+    test('keeps non-m4a media types unchanged', () => {
+        expect(normalizeAudioMediaType('audio/ogg')).toMatchInlineSnapshot('"audio/ogg"');
+        expect(normalizeAudioMediaType('audio/wav')).toMatchInlineSnapshot('"audio/wav"');
+    });
+    test('converts ogg only when mime is actual ogg/opus', () => {
+        expect(getOpenAIAudioConversionStrategy('audio/ogg')).toMatchInlineSnapshot('"convert-ogg-to-wav"');
+        expect(getOpenAIAudioConversionStrategy('audio/opus')).toMatchInlineSnapshot('"convert-ogg-to-wav"');
+        expect(getOpenAIAudioConversionStrategy('audio/mp4')).toMatchInlineSnapshot('"convert-m4a-to-wav"');
+        expect(getOpenAIAudioConversionStrategy('audio/mpeg')).toMatchInlineSnapshot('"none"');
+    });
+});
 describe('extractTranscription', () => {
     test('extracts transcription from tool call', () => {
         const result = extractTranscription([

package/dist/websockify.js

@@ -0,0 +1,69 @@
+// In-process WebSocket-to-TCP bridge (websockify replacement).
+// Accepts WebSocket connections and pipes raw bytes to/from a TCP target.
+// Used by /screenshare to bridge noVNC (WebSocket) to a VNC server (TCP).
+// Supports the 'binary' subprotocol required by noVNC.
+import { WebSocketServer, WebSocket } from 'ws';
+import net from 'node:net';
+import { createLogger } from './logger.js';
+const logger = createLogger('SCREEN');
+export function startWebsockify({ wsPort, tcpHost, tcpPort, }) {
+    return new Promise((resolve, reject) => {
+        const wss = new WebSocketServer({
+            port: wsPort,
+            // noVNC negotiates the 'binary' subprotocol
+            handleProtocols: (protocols) => {
+                if (protocols.has('binary')) {
+                    return 'binary';
+                }
+                return false;
+            },
+        });
+        wss.on('listening', () => {
+            const addr = wss.address();
+            const port = typeof addr === 'object' && addr ? addr.port : wsPort;
+            logger.log(`Websockify listening on port ${port} → ${tcpHost}:${tcpPort}`);
+            resolve({
+                wss,
+                port,
+                close: () => {
+                    for (const client of wss.clients) {
+                        client.close();
+                    }
+                    wss.close();
+                },
+            });
+        });
+        wss.on('error', (err) => {
+            reject(new Error('Websockify failed to start', { cause: err }));
+        });
+        wss.on('connection', (ws) => {
+            const tcp = net.createConnection(tcpPort, tcpHost, () => {
+                logger.log(`TCP connection established to ${tcpHost}:${tcpPort}`);
+            });
+            tcp.on('data', (data) => {
+                if (ws.readyState === WebSocket.OPEN) {
+                    ws.send(data);
+                }
+            });
+            ws.on('message', (data) => {
+                if (!tcp.destroyed) {
+                    tcp.write(data);
+                }
+            });
+            ws.on('close', () => {
+                tcp.destroy();
+            });
+            ws.on('error', (err) => {
+                logger.error('WebSocket error:', err);
+                tcp.destroy();
+            });
+            tcp.on('close', () => {
+                ws.close();
+            });
+            tcp.on('error', (err) => {
+                logger.error('TCP connection error:', err);
+                ws.close();
+            });
+        });
+    });
+}