kimaki 1.4.0 → 1.6.0

package/src/voice-call.e2e.test.ts

@@ -136,12 +136,12 @@ test('a user joins and speaks, the backend runs kimaki commands and the model sa
   // Thread IDs are snowflakes: replace them for a stable snapshot.
   expect((await twin.discord.channel(voiceChannelId).text()).replace(/<#\d+>/g, '<#thread>')).toMatchInlineSnapshot(`
     "--- from: assistant (TestBot)
-    -# ⬦ voice call started ⋅ gpt-live ⋅ cove
+    -# voice call started ⋅ gpt-live ⋅ cove
     Hello tommy.
-    » **tommy:** Which projects do I have?
+    -# » **tommy:** Which projects do I have?
     -# ┣ shell _seq 1 2000; kimaki project list_
     -# ┣ shell _kimaki send --channel 200000000000000100 --prompt 'Voice call note' --notify-on…_
-    -# ⬦ session started in <#thread>
+    -# session started in <#thread>
     -#  ⨯  post\\_message _text must not be empty_
     You have one project."
   `)
@@ -205,12 +205,12 @@ test('chat messages reach the backend, and end_call leaves after the goodbye whi
   expect(botPackets() - packetsBefore).toBeGreaterThanOrEqual(30)
   expect(live.backendInputs.at(-1)).toBe(`<chat-message from="tommy" user-id="${TEST_USER_ID}">\nplease hang up\n</chat-message>`)
   expect(await chatSince(before)).toMatchInlineSnapshot(`
-    "TestBot: -# ⬦ voice call started ⋅ gpt-live ⋅ cove
+    "TestBot: -# voice call started ⋅ gpt-live ⋅ cove
     TestBot: Hi again.
     tommy: please hang up
     TestBot: -# ┣ end\\_call
     TestBot: Bye.
-    TestBot: -# ⬦ voice call ended: the assistant hung up"
+    TestBot: -# voice call ended: the assistant hung up"
   `)
   await twin.discord.channel(voiceChannelId).user(TEST_USER_ID).leaveVoice()
 })
@@ -244,15 +244,15 @@ test('finished threads of any project are announced in the call; the model answe
   live.replies.length = 0
 
   expect(await chatSince(before)).toMatchInlineSnapshot(`
-    "TestBot: -# ⬦ voice call started ⋅ gpt-live ⋅ cove
+    "TestBot: -# voice call started ⋅ gpt-live ⋅ cove
     TestBot: Hi.
     tommy: start a thread
     TestBot: -# ┣ shell _kimaki send --channel <id> --prompt 'call-thread-marker' --user '…_
-    TestBot: -# ⬦ session started in <#<id>>
+    TestBot: -# session started in <#<id>>
     TestBot: Started.
-    TestBot: -# ⬦ thread finished: call-thread-marker ⋅ https://discord.com/channels/<id>/<id> ⋅ <ses>
+    TestBot: -# thread finished: call-thread-marker ⋅ https://discord.com/channels/<id>/<id> ⋅ <ses>
     TestBot: Your thread finished.
-    TestBot: -# ⬦ thread finished: other-thread-marker ⋅ https://discord.com/channels/<id>/<id> ⋅ <ses>"
+    TestBot: -# thread finished: other-thread-marker ⋅ https://discord.com/channels/<id>/<id> ⋅ <ses>"
   `)
   const notices = live.appends.filter((append) => append.text.startsWith('<system>Thread finished'))
   expect(notices.map((notice) => ({ ...notice, text: notice.text.replace(/\d{17,20}/g, '<id>').replace(/ses_\w+/g, '<ses>') }))).toMatchInlineSnapshot(`

package/src/voice-call.ts

@@ -330,7 +330,7 @@ export function createVoiceCalls({ opencodeConfigDir }: { opencodeConfigDir: str
 
   // Bot lines in the text chat of the voice channel, through the same FIFO as session output.
   function post(bot: Bot, { channelId, text, markdown = false }: { channelId: string; text: string; markdown?: boolean }) {
-    bot.effects.run(channelId, [markdown ? { type: 'markdown', text, blankLineBefore: false } : { type: 'send', text }])
+    bot.effects.run(channelId, [markdown ? { type: 'markdown', text, blankLineBefore: false, replyTo: null } : { type: 'send', text }])
   }
 
   // Errors during a call go to the log and to the text chat of the voice channel.
@@ -505,7 +505,7 @@ export function createVoiceCalls({ opencodeConfigDir }: { opencodeConfigDir: str
                 sent.push(threadId)
                 current.started.add(threadId)
                 if (waits) current.waiting.add(threadId)
-                post(bot, { channelId: current.channelId, text: asSubtext(`⬦ ${started} <#${threadId}>`) })
+                post(bot, { channelId: current.channelId, text: asSubtext(`${started} <#${threadId}>`) })
               }
             : undefined
           const run = runShell(bot, { call: current, command: input.command, timeoutMs, onLine }).then((result) => {
@@ -668,8 +668,8 @@ export function createVoiceCalls({ opencodeConfigDir }: { opencodeConfigDir: str
     }
     listen(bot, call)
     logger.info(`voice call started in ${channelId}, voice ${settings.voice}`)
-    post(bot, { channelId, text: `-# ⬦ voice call started ⋅ gpt-live ⋅ ${settings.voice}` })
-    if (settings.voiceNotice) post(bot, { channelId, text: asSubtext(`⬦ ${settings.voiceNotice}`) })
+    post(bot, { channelId, text: `-# voice call started ⋅ gpt-live ⋅ ${settings.voice}` })
+    if (settings.voiceNotice) post(bot, { channelId, text: asSubtext(settings.voiceNotice) })
     live.append({ text: 'The call started. Greet the users by name in one short sentence.', channel: 'speakable' })
   }
 
@@ -684,7 +684,7 @@ export function createVoiceCalls({ opencodeConfigDir }: { opencodeConfigDir: str
     call.speaker.stop()
     if (call.connection.state.status !== VoiceConnectionStatus.Destroyed) call.connection.destroy()
     logger.info(`voice call ended in ${call.channelId}${reason ? `: ${reason}` : ''}`)
-    post(bot, { channelId: call.channelId, text: `-# ⬦ voice call ended${reason ? `: ${reason}` : ''}` })
+    post(bot, { channelId: call.channelId, text: `-# voice call ended${reason ? `: ${reason}` : ''}` })
   }
 
   async function onVoiceState(bot: Bot, { before, after }: { before: VoiceState; after: VoiceState }) {
@@ -727,7 +727,7 @@ export function createVoiceCalls({ opencodeConfigDir }: { opencodeConfigDir: str
     if (!call || call.ending) return
     const url = `https://discord.com/channels/${thread.guildId}/${threadId}`
     const state = error === null ? 'finished' : 'failed'
-    post(bot, { channelId: call.channelId, text: asSubtext(`⬦ thread ${state}: ${thread.name} ⋅ ${url} ⋅ ${sessionId}`) })
+    post(bot, { channelId: call.channelId, text: asSubtext(`thread ${state}: ${thread.name} ⋅ ${url} ⋅ ${sessionId}`) })
     const failure = error === null ? '' : ` Error: ${error}`
     const notice = `<system>Thread ${state}: "${thread.name}". Thread ID ${threadId}, session ID ${sessionId}, URL ${url}.${failure}</system>`
     // Answer only for threads started in this call. A pending kimaki send --wait brings the transcript next.

package/src/voice-openai.e2e.test.ts

@@ -2,13 +2,14 @@
 // decoded to WAV (OpenAI accepts only wav and mp3) and sent to a local
 // OpenAI-compatible server that answers with the transcription tool call.
 // A ChatGPT credential stored by OpenCode is the fallback when the key fails, and gets the raw audio.
+// KIMAKI_WHISPER_URL replaces them all with a local Whisper server.
 
 import { execFile } from 'node:child_process'
 import fs from 'node:fs'
 import path from 'node:path'
 import { promisify } from 'node:util'
 import type { DeterministicMatcher } from 'opencode-deterministic-provider'
-import { afterAll, beforeAll, expect, test } from 'vitest'
+import { afterAll, beforeAll, expect, onTestFinished, test } from 'vitest'
 
 import type { BotHandle } from './main.ts'
 import {
@@ -39,6 +40,7 @@ let twin: TestTwin
 let bot: BotHandle
 let openai: FakeOpenAI
 let chatgpt: FakeChatGPT
+let whisper: FakeChatGPT
 let dataDir: string
 // Created by the ChatGPT test: the tests before it run with no credential.
 let opencodeDbFile: string
@@ -46,11 +48,12 @@ let opencodeDbFile: string
 beforeAll(async () => {
   dataDir = tempDataDir()
   opencodeDbFile = path.join(dataDir, 'opencode.db')
-  ;[server, twin, openai, chatgpt] = await Promise.all([
+  ;[server, twin, openai, chatgpt, whisper] = await Promise.all([
     startOpencodeTestServer({ matchers }),
     startTwin(),
     startFakeOpenAI({ result: { transcription: 'Hello from the phone voice-openai', route: 'steer' } }),
     startFakeChatGPT({ text: 'Hello from ChatGPT voice-openai' }),
+    startFakeChatGPT({ text: 'Hello from Whisper voice-openai' }),
   ])
   await seedProjectChannel({ dataDir, channelId: twin.channelId, guildId: twin.discord.guildId, directory: server.projectDirectory })
   await warmUp({ server })
@@ -66,25 +69,33 @@ afterAll(async () => {
   await server?.stop()
   await openai?.stop()
   await chatgpt?.stop()
+  await whisper?.stop()
   fs.rmSync(dataDir, { recursive: true, force: true })
 })
 
-test('an Ogg Opus voice message is converted to WAV and transcribed by OpenAI', async () => {
-  const ogg = fs.readFileSync(path.join(import.meta.dirname, 'fixtures', 'voice.ogg'))
+const ogg = fs.readFileSync(path.join(import.meta.dirname, 'fixtures', 'voice.ogg'))
+
+async function sendVoice() {
+  const before = new Set((await twin.discord.channel(twin.channelId).getThreads()).map((thread) => thread.id))
   await twin.discord
     .channel(twin.channelId)
     .user(TEST_USER_ID)
     .sendVoiceMessage({ url: `data:audio/ogg;base64,${ogg.toString('base64')}` })
-  const thread = await twin.discord.channel(twin.channelId).waitForThread({ timeout: 8_000 })
+  const thread = await twin.discord.channel(twin.channelId).waitForThread({ timeout: 8_000, predicate: (thread) => !before.has(thread.id) })
   await waitForFooter({ discord: twin.discord, threadId: thread.id })
-  expect(await twin.discord.thread(thread.id).text()).toMatchInlineSnapshot(`
+  return thread.id
+}
+
+test('an Ogg Opus voice message is converted to WAV and transcribed by OpenAI', async () => {
+  const thread = await sendVoice()
+  expect(await twin.discord.thread(thread).text()).toMatchInlineSnapshot(`
     "--- from: user (tommy)
     [attachment: voice-message.ogg]
     --- from: assistant (TestBot)
-    » **tommy:** Hello from the phone voice-openai
+    -# » **tommy:** Hello from the phone voice-openai
     -# *using deterministic-provider/deterministic-v2 ⋅ build*
     openai voice ok
-    -# *project ⋅ main ⋅ Ns ⋅ N% ⋅ deterministic-v2*"
+    -# *main ⋅ Ns ⋅ N% ⋅ deterministic-v2*"
   `)
   const [request] = openai.requests
   expect({
@@ -129,29 +140,17 @@ test('an MP3 upload labeled audio/mpeg3 goes to OpenAI as mp3', async () => {
 test('the OpenAI key wins over the ChatGPT credential from OpenCode, which takes over when the key fails', async () => {
   const claims = Buffer.from(JSON.stringify({ 'https://api.openai.com/auth': { chatgpt_account_id: 'acct-test' } })).toString('base64url')
   await writeOpencodeCredential({ file: opencodeDbFile, access: `header.${claims}.signature`, expires: Date.now() + 3_600_000 })
-  const ogg = fs.readFileSync(path.join(import.meta.dirname, 'fixtures', 'voice.ogg'))
   const openaiRequests = openai.requests.length
 
-  async function sendVoice() {
-    const before = new Set((await twin.discord.channel(twin.channelId).getThreads()).map((thread) => thread.id))
-    await twin.discord
-      .channel(twin.channelId)
-      .user(TEST_USER_ID)
-      .sendVoiceMessage({ url: `data:audio/ogg;base64,${ogg.toString('base64')}` })
-    const thread = await twin.discord.channel(twin.channelId).waitForThread({ timeout: 8_000, predicate: (thread) => !before.has(thread.id) })
-    await waitForFooter({ discord: twin.discord, threadId: thread.id })
-    return thread.id
-  }
-
   const viaKey = await sendVoice()
   expect(await twin.discord.thread(viaKey).text()).toMatchInlineSnapshot(`
     "--- from: user (tommy)
     [attachment: voice-message.ogg]
     --- from: assistant (TestBot)
-    » **tommy:** Hello from the phone voice-openai
+    -# » **tommy:** Hello from the phone voice-openai
     -# *using deterministic-provider/deterministic-v2 ⋅ build*
     openai voice ok
-    -# *project ⋅ main ⋅ Ns ⋅ N% ⋅ deterministic-v2*"
+    -# *main ⋅ Ns ⋅ N% ⋅ deterministic-v2*"
   `)
   expect({ chatgptRequests: chatgpt.requests.length, openaiRequests: openai.requests.length - openaiRequests }).toMatchInlineSnapshot(`
     {
@@ -167,10 +166,10 @@ test('the OpenAI key wins over the ChatGPT credential from OpenCode, which takes
     "--- from: user (tommy)
     [attachment: voice-message.ogg]
     --- from: assistant (TestBot)
-    » **tommy:** Hello from ChatGPT voice-openai
+    -# » **tommy:** Hello from ChatGPT voice-openai
     -# *using deterministic-provider/deterministic-v2 ⋅ build*
     openai voice ok
-    -# *project ⋅ main ⋅ Ns ⋅ N% ⋅ deterministic-v2*"
+    -# *main ⋅ Ns ⋅ N% ⋅ deterministic-v2*"
   `)
   const [request] = chatgpt.requests
   expect({
@@ -189,3 +188,44 @@ test('the OpenAI key wins over the ChatGPT credential from OpenCode, which takes
     }
   `)
 })
+
+test('KIMAKI_WHISPER_URL is the only transcriber: no cloud request, and its failure is shown', async () => {
+  process.env['KIMAKI_WHISPER_URL'] = `${whisper.baseUrl}/v1/`
+  process.env['KIMAKI_WHISPER_MODEL'] = 'Systran/faster-whisper-large-v3'
+  onTestFinished(() => {
+    delete process.env['KIMAKI_WHISPER_URL']
+    delete process.env['KIMAKI_WHISPER_MODEL']
+  })
+  const cloudRequests = openai.requests.length + chatgpt.requests.length
+
+  const thread = await sendVoice()
+  expect(await twin.discord.thread(thread).text()).toMatchInlineSnapshot(`
+    "--- from: user (tommy)
+    [attachment: voice-message.ogg]
+    --- from: assistant (TestBot)
+    -# » **tommy:** Hello from Whisper voice-openai
+    -# *using deterministic-provider/deterministic-v2 ⋅ build*
+    openai voice ok
+    -# *main ⋅ Ns ⋅ N% ⋅ deterministic-v2*"
+  `)
+  const request = whisper.requests.at(-1)
+  expect({ ...request, audio: request?.audio.equals(ogg) }).toMatchInlineSnapshot(`
+    {
+      "accountId": null,
+      "audio": true,
+      "authorization": null,
+      "filename": "voice.ogg",
+      "model": "Systran/faster-whisper-large-v3",
+      "path": "/v1/audio/transcriptions",
+      "type": "audio/ogg",
+    }
+  `)
+
+  // 400 is not retried; a 5xx would be retried twice first.
+  whisper.status = 400
+  await twin.discord.channel(twin.channelId).user(TEST_USER_ID).sendVoiceMessage({ url: `data:audio/ogg;base64,${ogg.toString('base64')}` })
+  const reply = await twin.discord.channel(twin.channelId).waitForMessage({ timeout: 8_000, predicate: (message) => message.content.includes('Transcription API returned 400') })
+  whisper.status = 200
+  expect(reply.content).toMatchInlineSnapshot(`"✗ Transcription API returned 400: {"detail":"unauthorized"}"`)
+  expect(openai.requests.length + chatgpt.requests.length).toBe(cloudRequests)
+})

package/src/voice.ts

@@ -7,7 +7,8 @@
 // Order: OpenAI (bot_api_keys, then OPENAI_API_KEY), the ChatGPT subscription credential
 // stored by OpenCode (billed to the plan), Gemini (bot_api_keys, then GEMINI_API_KEY), then the
 // free kimaki.dev Whisper endpoint on gateway installs. A failing provider falls through to the
-// next one. ChatGPT and Whisper have no tool call: the route is always steer.
+// next one. KIMAKI_WHISPER_URL replaces the whole list with a local Whisper server, so audio
+// never reaches a cloud provider. ChatGPT and Whisper have no tool call: the route is always steer.
 // Plain fetch, no AI SDK: we parse provider bodies ourselves so transient
 // bad responses keep their details and can be retried.
 
@@ -47,6 +48,15 @@ const GEMINI_MODEL = 'gemini-flash-latest'
 const TOOL_NAME = 'transcriptionResult'
 const MAX_ATTEMPTS = 3
 const RETRY_DELAY_MS = 500
+// Later messages of the conversation wait for the transcription (ingress.ts): cap all providers and retries.
+const TRANSCRIPTION_TIMEOUT_MS = 2 * 60_000
+
+// KIMAKI_WHISPER_TIMEOUT (seconds) raises the cap for a slow local Whisper server (CPU only).
+function transcriptionTimeoutMs(entries: Transcriber[]) {
+  const seconds = Number(process.env['KIMAKI_WHISPER_TIMEOUT'])
+  if (!entries.some((entry) => entry.kind === 'local-whisper') || !(seconds > 0)) return TRANSCRIPTION_TIMEOUT_MS
+  return seconds * 1000
+}
 
 export class TranscriptionError extends errore.createTaggedError({
   name: 'TranscriptionError',
@@ -376,11 +386,12 @@ async function openAIAudio({ audio, mediaType }: { audio: Buffer; mediaType: str
 
 // --- requests
 
-async function postJson({ url, headers, body }: { url: string; headers: Record<string, string>; body: unknown }) {
+async function postJson({ url, headers, body, signal }: { url: string; headers: Record<string, string>; body: unknown; signal: AbortSignal }) {
   const response = await fetch(url, {
     method: 'POST',
     headers: { 'content-type': 'application/json', ...headers },
     body: JSON.stringify(body),
+    signal,
   }).catch((cause) => new TranscriptionError({ reason: `request to ${url} failed`, cause }))
   if (response instanceof Error) return response
   const text = await response.text().catch((cause) => new TranscriptionError({ reason: 'reading the response failed', cause }))
@@ -391,8 +402,9 @@ async function postJson({ url, headers, body }: { url: string; headers: Record<s
 
 type Tool = ReturnType<typeof buildTranscriptionTool>
 
-async function requestGemini({ apiKey, baseUrl, prompt, audio, mediaType, tool }: ProviderRequest) {
+async function requestGemini({ apiKey, baseUrl, prompt, audio, mediaType, tool, signal }: ProviderRequest) {
   const raw = await postJson({
+    signal,
     url: `${baseUrl}/models/${GEMINI_MODEL}:generateContent`,
     headers: { 'x-goog-api-key': apiKey },
     body: {
@@ -408,10 +420,11 @@ async function requestGemini({ apiKey, baseUrl, prompt, audio, mediaType, tool }
 
 // TODO: use the ChatGPT subscription token here once OpenAI allows it. Today chat/completions
 // rejects it (missing model.request scope), so the subscription only gets dictation without routing.
-async function requestOpenAI({ apiKey, baseUrl, prompt, audio, mediaType, tool }: ProviderRequest) {
+async function requestOpenAI({ apiKey, baseUrl, prompt, audio, mediaType, tool, signal }: ProviderRequest) {
   const input = await openAIAudio({ audio, mediaType })
   if (input instanceof Error) return input
   const raw = await postJson({
+    signal,
     url: `${baseUrl}/chat/completions`,
     headers: { authorization: `Bearer ${apiKey}` },
     body: {
@@ -435,7 +448,7 @@ async function requestOpenAI({ apiKey, baseUrl, prompt, audio, mediaType, tool }
   return parseOpenAIResponse(raw)
 }
 
-type ProviderRequest = { apiKey: string; baseUrl: string; prompt: string; audio: Buffer; mediaType: string; tool: Tool }
+type ProviderRequest = { apiKey: string; baseUrl: string; prompt: string; audio: Buffer; mediaType: string; tool: Tool; signal: AbortSignal }
 
 // Retries transient failures: network, 408/409/429/5xx, bad bodies. Never
 // bad keys, refusals or an empty transcription.
@@ -446,11 +459,11 @@ function isRetryable(error: TranscriptionFailure): boolean {
   return status === 408 || status === 409 || status === 429 || status >= 500
 }
 
-async function withRetries(attempt: () => Promise<TranscriptionFailure | TranscriptionResult>) {
+async function withRetries({ signal, attempt }: { signal: AbortSignal; attempt: () => Promise<TranscriptionFailure | TranscriptionResult> }) {
   for (let number = 1; ; number++) {
     const result = await attempt()
     if (!(result instanceof Error)) return result
-    const retry = number < MAX_ATTEMPTS && isRetryable(result)
+    const retry = number < MAX_ATTEMPTS && !signal.aborted && isRetryable(result)
     logger.warn(`transcription attempt ${number}/${MAX_ATTEMPTS} failed${retry ? ', retrying' : ''}`, result)
     if (!retry) return result
     await new Promise((resolve) => setTimeout(resolve, RETRY_DELAY_MS * number))
@@ -459,16 +472,18 @@ async function withRetries(attempt: () => Promise<TranscriptionFailure | Transcr
 
 // Free Whisper through kimaki.dev, authenticated with the gateway client
 // credentials (website POST /api/transcribe). No routing: always steer.
-async function transcribeViaGateway({ audio, mediaType, clientId, clientSecret }: {
+async function transcribeViaGateway({ audio, mediaType, clientId, clientSecret, signal }: {
   audio: Buffer
   mediaType: string
   clientId: string
   clientSecret: string
+  signal: AbortSignal
 }): Promise<TranscriptionFailure | TranscriptionResult> {
   const response = await fetch(new URL('/api/transcribe', gatewayUrlsFromEnv().website), {
     method: 'POST',
     headers: { authorization: `Bearer ${clientId}:${clientSecret}`, 'content-type': mediaType },
     body: new Uint8Array(audio),
+    signal,
   }).catch((cause) => new TranscriptionError({ reason: 'kimaki.dev transcription not reachable', cause }))
   if (response instanceof Error) return response
   const body = await response.text().catch(() => '')
@@ -489,7 +504,7 @@ async function transcribeViaGateway({ audio, mediaType, clientId, clientSecret }
 
 type ChatGPTCredential = { accessToken: string; accountId: string | null }
 
-const CHATGPT_EXTENSIONS: Record<string, string> = { 'audio/ogg': 'ogg', 'audio/mp4': 'm4a', 'audio/mpeg': 'mp3', 'audio/wav': 'wav' }
+const AUDIO_EXTENSIONS: Record<string, string> = { 'audio/ogg': 'ogg', 'audio/mp4': 'm4a', 'audio/mpeg': 'mp3', 'audio/wav': 'wav' }
 
 // Same claim the Codex CLI sends as chatgpt-account-id.
 function chatGPTAccountId(accessToken: string): string | null {
@@ -524,22 +539,22 @@ export async function chatGPTCredential({ dbFile, now = Date.now() }: { dbFile:
   return null
 }
 
-async function transcribeViaChatGPT({ credential, baseUrl, audio, mediaType }: {
-  credential: ChatGPTCredential
-  baseUrl: string
+// Multipart `file` (plus `fields`) in, `{ text }` out: ChatGPT dictation and Whisper servers.
+async function transcribeFile({ name, url, headers, fields = {}, audio, mediaType, signal }: {
+  // For the error when the server is not reachable.
+  name: string
+  url: string
+  headers: Record<string, string>
+  fields?: Record<string, string>
   audio: Buffer
   mediaType: string
+  signal: AbortSignal
 }): Promise<TranscriptionFailure | TranscriptionResult> {
   const form = new FormData()
-  form.append('file', new File([new Uint8Array(audio)], `voice.${CHATGPT_EXTENSIONS[mediaType] ?? 'ogg'}`, { type: mediaType }))
-  const response = await fetch(`${baseUrl}/transcribe`, {
-    method: 'POST',
-    headers: {
-      authorization: `Bearer ${credential.accessToken}`,
-      ...(credential.accountId && { 'chatgpt-account-id': credential.accountId }),
-    },
-    body: form,
-  }).catch((cause) => new TranscriptionError({ reason: 'ChatGPT transcription not reachable', cause }))
+  form.append('file', new File([new Uint8Array(audio)], `voice.${AUDIO_EXTENSIONS[mediaType] ?? 'ogg'}`, { type: mediaType }))
+  for (const [key, value] of Object.entries(fields)) form.append(key, value)
+  const response = await fetch(url, { method: 'POST', headers, body: form, signal })
+    .catch((cause) => new TranscriptionError({ reason: `${name} not reachable`, cause }))
   if (response instanceof Error) return response
   const body = await response.text().catch(() => '')
   if (!response.ok) return new TranscriptionApiError({ status: String(response.status), body: body.slice(0, 300) })
@@ -548,6 +563,56 @@ async function transcribeViaChatGPT({ credential, baseUrl, audio, mediaType }: {
   return toTranscriptionResult({ transcription: parsed['text'] })
 }
 
+function transcribeViaChatGPT({ credential, baseUrl, audio, mediaType, signal }: {
+  credential: ChatGPTCredential
+  baseUrl: string
+  audio: Buffer
+  mediaType: string
+  signal: AbortSignal
+}) {
+  return transcribeFile({
+    name: 'ChatGPT transcription',
+    url: `${baseUrl}/transcribe`,
+    headers: {
+      authorization: `Bearer ${credential.accessToken}`,
+      ...(credential.accountId && { 'chatgpt-account-id': credential.accountId }),
+    },
+    audio,
+    mediaType,
+    signal,
+  })
+}
+
+// --- Local Whisper (KIMAKI_WHISPER_URL)
+//
+// Any server with the standard OpenAI speech-to-text API: speaches, faster-whisper-server,
+// whisper.cpp server, LocalAI. POST <url>/audio/transcriptions with multipart `file` + `model`.
+// https://platform.openai.com/docs/api-reference/audio/createTranscription
+
+type LocalWhisper = { url: string; model: string; apiKey: string | null }
+
+function localWhisperFromEnv(): LocalWhisper | null {
+  const url = process.env['KIMAKI_WHISPER_URL']?.trim().replace(/\/+$/, '')
+  if (!url) return null
+  return {
+    url,
+    model: process.env['KIMAKI_WHISPER_MODEL']?.trim() || 'whisper-1',
+    apiKey: process.env['KIMAKI_WHISPER_API_KEY']?.trim() || null,
+  }
+}
+
+function transcribeViaLocalWhisper({ whisper, audio, mediaType, signal }: { whisper: LocalWhisper; audio: Buffer; mediaType: string; signal: AbortSignal }) {
+  return transcribeFile({
+    name: `Whisper server at ${whisper.url}`,
+    url: `${whisper.url}/audio/transcriptions`,
+    headers: whisper.apiKey ? { authorization: `Bearer ${whisper.apiKey}` } : {},
+    fields: { model: whisper.model },
+    audio,
+    mediaType,
+    signal,
+  })
+}
+
 // --- routing
 
 export function parseVoiceMessage(result: TranscriptionResult): Route {
@@ -580,10 +645,14 @@ type Transcriber =
   | { kind: 'openai' | 'gemini'; apiKey: string }
   | { kind: 'chatgpt'; credential: ChatGPTCredential }
   | { kind: 'gateway'; clientId: string; clientSecret: string }
+  | { kind: 'local-whisper'; whisper: LocalWhisper }
 
 // Best first: OpenAI key (routing tool call), ChatGPT subscription and Gemini key, then hosted Whisper.
 // ChatGPT and Whisper only transcribe, so the route is always steer.
+// A local Whisper server is the only one: its failure must not send the audio to the cloud.
 async function transcribers({ db, token, opencodeDbFile }: { db: KimakiDb; token: string; opencodeDbFile: string }): Promise<DbError | Transcriber[]> {
+  const whisper = localWhisperFromEnv()
+  if (whisper) return [{ kind: 'local-whisper', whisper }]
   const [row, credential] = await Promise.all([
     db.query.bot_tokens
       .findFirst({ where: { token }, with: { api_keys: true } })
@@ -637,15 +706,21 @@ export async function transcribe({
   const prompt = list.some((entry) => entry.kind === 'openai' || entry.kind === 'gemini')
     ? transcriptionPrompt({ fileTree: await projectFileTree(directory), agents })
     : ''
+  const timeoutMs = transcriptionTimeoutMs(list)
+  const signal = AbortSignal.timeout(timeoutMs)
   const run = (entry: Transcriber) => {
-    if (entry.kind === 'gateway') return transcribeViaGateway({ audio, mediaType, ...entry })
-    if (entry.kind === 'chatgpt') return withRetries(() => transcribeViaChatGPT({ credential: entry.credential, baseUrl: baseUrls.chatgpt ?? CHATGPT_BASE_URL, audio, mediaType }))
-    const request = { apiKey: entry.apiKey, prompt, audio, mediaType, tool }
-    if (entry.kind === 'openai') return withRetries(() => requestOpenAI({ ...request, baseUrl: baseUrls.openai ?? OPENAI_BASE_URL }))
-    return withRetries(() => requestGemini({ ...request, baseUrl: baseUrls.gemini ?? GEMINI_BASE_URL }))
+    if (entry.kind === 'gateway') return transcribeViaGateway({ audio, mediaType, ...entry, signal })
+    if (entry.kind === 'local-whisper') return withRetries({ signal, attempt: () => transcribeViaLocalWhisper({ whisper: entry.whisper, audio, mediaType, signal }) })
+    if (entry.kind === 'chatgpt') {
+      return withRetries({ signal, attempt: () => transcribeViaChatGPT({ credential: entry.credential, baseUrl: baseUrls.chatgpt ?? CHATGPT_BASE_URL, audio, mediaType, signal }) })
+    }
+    const request = { apiKey: entry.apiKey, prompt, audio, mediaType, tool, signal }
+    if (entry.kind === 'openai') return withRetries({ signal, attempt: () => requestOpenAI({ ...request, baseUrl: baseUrls.openai ?? OPENAI_BASE_URL }) })
+    return withRetries({ signal, attempt: () => requestGemini({ ...request, baseUrl: baseUrls.gemini ?? GEMINI_BASE_URL }) })
   }
   let last: TranscriptionFailure | NoTranscriptionKeyError = new NoTranscriptionKeyError()
   for (const entry of list) {
+    if (signal.aborted) return new TranscriptionError({ reason: `no answer within ${timeoutMs / 60_000} minutes` })
     const result = await run(entry)
     if (!(result instanceof Error) || result instanceof EmptyTranscriptionError) return result
     logger.warn(`${entry.kind} transcription failed${entry === list.at(-1) ? '' : ', trying the next provider'}`, result)

package/src/working-directory.e2e.test.ts

@@ -61,10 +61,10 @@ test('session cwd changes preserve the session and use the new location after re
   await waitForFooter({ discord: twin.discord, threadId: sent.threadId, count: 2 })
   expect(hide(await twin.discord.thread(sent.threadId).text())).toMatchInlineSnapshot(`
     "--- from: assistant (TestBot)
-    » **CLI:** Start cwd session
+    -# » **CLI:** Start cwd session
     -# *using deterministic-provider/deterministic-v2 ⋅ build*
     ok
-    -# *project ⋅ main ⋅ Ns ⋅ deterministic-v2*
+    -# *Ns ⋅ deterministic-v2*
     -# Working directory changed to PROJECT/sub
     --- from: user (tommy)
     write-cwd-marker
@@ -72,14 +72,14 @@ test('session cwd changes preserve the session and use the new location after re
     -# ┣ shell _Write to the current directory_
 
     Wrote cwd.txt.
-    -# *sub ⋅ main ⋅ Ns ⋅ N% ⋅ deterministic-v2*"
+    -# *sub ⋅ Ns ⋅ N% ⋅ deterministic-v2*"
   `)
   expect((await client.session.get({ sessionID: sent.sessionId })).location.directory).toBe(path.join(server.projectDirectory, 'sub'))
   expect(fs.readFileSync(path.join(server.projectDirectory, 'sub', 'cwd.txt'), 'utf8')).toBe('isolated')
   expect(fs.existsSync(path.join(server.projectDirectory, 'cwd.txt'))).toBe(false)
   const source = await bot.discord.channels.fetch(sent.threadId)
   if (!source?.isThread()) throw new Error('No thread')
-  const fork = await forkBtw(bot, { sourceThread: source, text: 'Side question', author: { id: TEST_USER_ID, username: 'tommy' }, messageId: 'cwd-btw' })
+  const fork = await forkBtw(bot, { source, text: 'Side question', author: { id: TEST_USER_ID, username: 'tommy' }, messageId: 'cwd-btw' })
   if (fork instanceof Error) throw fork
   await waitForFooter({ discord: twin.discord, threadId: fork.threadId })
   expect(hide(await twin.discord.thread(fork.threadId).text())).toMatchInlineSnapshot(`
@@ -87,7 +87,7 @@ test('session cwd changes preserve the session and use the new location after re
     Reusing context from <#THREAD> to answer prompt...
     Side question
     ok
-    -# *sub ⋅ main ⋅ Ns ⋅ deterministic-v2*"
+    -# *sub ⋅ Ns ⋅ deterministic-v2*"
   `)
   expect((await client.session.get({ sessionID: fork.sessionId })).location.directory).toBe(path.join(server.projectDirectory, 'sub'))
 })
@@ -105,11 +105,11 @@ test('native moves of a busy session update the live footer without aborting its
   await waitForFooter({ discord: twin.discord, threadId: sent.threadId })
   expect(hide(await twin.discord.thread(sent.threadId).text())).toMatchInlineSnapshot(`
     "--- from: assistant (TestBot)
-    » **CLI:** busy-move-marker
+    -# » **CLI:** busy-move-marker
     -# *using deterministic-provider/deterministic-v2 ⋅ build*
     Finished without interruption.
     -# Working directory changed to PROJECT/sub
-    -# *sub ⋅ main ⋅ Ns ⋅ N% ⋅ deterministic-v2*
+    -# *sub ⋅ Ns ⋅ N% ⋅ deterministic-v2*
     Working directory: \`PROJECT/sub\`"
   `)
   expect((await client.session.get({ sessionID: sent.sessionId })).location.directory).toBe(path.join(server.projectDirectory, 'sub'))
@@ -143,7 +143,7 @@ test('new-worktree forks context, and CLI creation and worktree toggle use the s
   await waitForFooter({ discord: twin.discord, threadId: created.threadId })
   expect(hide(await twin.discord.thread(created.threadId).text())).toMatchInlineSnapshot(`
     "--- from: assistant (TestBot)
-    » **CLI:** CLI isolation
+    -# » **CLI:** CLI isolation
     -# *using deterministic-provider/deterministic-v2 ⋅ build*
     ok
     -# *cli-checkout ⋅ opencode/kimaki-cli-checkout ⋅ Ns ⋅ deterministic-v2*"
@@ -156,7 +156,7 @@ test('new-worktree forks context, and CLI creation and worktree toggle use the s
   await waitForFooter({ discord: twin.discord, threadId: automatic.threadId })
   expect(hide(await twin.discord.thread(automatic.threadId).text()).replace(/automatic-isolation-[a-f0-9]{8}/g, 'automatic-isolation-ID')).toMatchInlineSnapshot(`
     "--- from: assistant (TestBot)
-    » **CLI:** Automatic isolation
+    -# » **CLI:** Automatic isolation
     -# *using deterministic-provider/deterministic-v2 ⋅ build*
     ok
     -# *automatic-isolation-ID ⋅ opencode/kimaki-automatic-isolation-ID ⋅ Ns ⋅ deterministic-v2*"
@@ -172,7 +172,7 @@ test('send worktree creates an isolated named checkout, while explicit cwd reuse
   await waitForFooter({ discord: twin.discord, threadId: sent.threadId })
   expect(hide(await twin.discord.thread(sent.threadId).text())).toMatchInlineSnapshot(`
     "--- from: assistant (TestBot)
-    » **CLI:** write-cwd-marker
+    -# » **CLI:** write-cwd-marker
     -# *using deterministic-provider/deterministic-v2 ⋅ build*
     -# ┣ shell _Write to the current directory_
 
@@ -189,7 +189,7 @@ test('send worktree creates an isolated named checkout, while explicit cwd reuse
   await waitForFooter({ discord: twin.discord, threadId: reused.threadId })
   expect(hide(await twin.discord.thread(reused.threadId).text())).toMatchInlineSnapshot(`
     "--- from: assistant (TestBot)
-    » **CLI:** Reuse checkout
+    -# » **CLI:** Reuse checkout
     -# *using deterministic-provider/deterministic-v2 ⋅ build*
     ok
     -# *isolated ⋅ opencode/kimaki-isolated ⋅ Ns ⋅ deterministic-v2*"

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

@@ -1,39 +0,0 @@
-// `kimaki --message-tool`: the plugin gives root sessions a send_message tool
-// and the thread shows only its text. The model's plain text stays hidden.
-import fs from 'node:fs';
-import { afterAll, beforeAll, expect, test } from 'vitest';
-import { scriptedTurn, seedProjectChannel, startOpencodeTestServer, startTestBot, startTwin, tempDataDir, TEST_USER_ID, waitForFooter, warmUp } from "./test/harness.js";
-const dataDir = tempDataDir();
-let server;
-let twin;
-let bot;
-beforeAll(async () => {
-    const matchers = scriptedTurn({
-        marker: 'message-tool-marker',
-        steps: [{ id: 'message-call', tool: 'send_message', input: { text: 'Hello from **send_message**' } }],
-        finalText: 'hidden scratchpad text',
-    });
-    [server, twin] = await Promise.all([startOpencodeTestServer({ matchers }), startTwin()]);
-    await seedProjectChannel({ dataDir, channelId: twin.channelId, guildId: twin.discord.guildId, directory: server.projectDirectory });
-    bot = await startTestBot({ dataDir, twin, server, messageTool: true });
-    await warmUp({ server });
-}, 60_000);
-afterAll(async () => {
-    await bot?.stop();
-    await Promise.all([server?.stop(), twin?.stop()]);
-    fs.rmSync(dataDir, { recursive: true, force: true });
-});
-test('send_message text shows in Discord, plain text of the same turn does not', async () => {
-    await twin.discord.channel(twin.channelId).user(TEST_USER_ID).sendMessage({ content: 'message-tool-marker' });
-    const thread = await twin.discord.channel(twin.channelId).waitForThread({ timeout: 8_000 });
-    await waitForFooter({ discord: twin.discord, threadId: thread.id });
-    expect(await twin.discord.thread(thread.id).text()).toMatchInlineSnapshot(`
-    "--- from: user (tommy)
-    message-tool-marker
-    --- from: assistant (TestBot)
-    -# *using deterministic-provider/deterministic-v2 ⋅ build*
-    Hello from **send_message**
-    -# *project ⋅ main ⋅ Ns ⋅ N% ⋅ deterministic-v2*"
-  `);
-});
-//# sourceMappingURL=message-tool.e2e.test.js.map

package/dist/message-tool.e2e.test.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"message-tool.e2e.test.js","sourceRoot":"","sources":["../src/message-tool.e2e.test.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,2EAA2E;AAE3E,OAAO,EAAE,MAAM,SAAS,CAAA;AACxB,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AAG1D,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,EAA0C,MAAM,mBAAmB,CAAA;AAEhN,MAAM,OAAO,GAAG,WAAW,EAAE,CAAA;AAC7B,IAAI,MAA0B,CAAA;AAC9B,IAAI,IAAc,CAAA;AAClB,IAAI,GAAc,CAAA;AAElB,SAAS,CAAC,KAAK,IAAI,EAAE;IACnB,MAAM,QAAQ,GAAG,YAAY,CAAC;QAC5B,MAAM,EAAE,qBAAqB;QAC7B,KAAK,EAAE,CAAC,EAAE,EAAE,EAAE,cAAc,EAAE,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,6BAA6B,EAAE,EAAE,CAAC;QACrG,SAAS,EAAE,wBAAwB;KACpC,CAAC,CACD;IAAA,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,uBAAuB,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAA;IACzF,MAAM,kBAAkB,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,SAAS,EAAE,MAAM,CAAC,gBAAgB,EAAE,CAAC,CAAA;IACnI,GAAG,GAAG,MAAM,YAAY,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAA;IACtE,MAAM,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC,CAAA;AAC1B,CAAC,EAAE,MAAM,CAAC,CAAA;AAEV,QAAQ,CAAC,KAAK,IAAI,EAAE;IAClB,MAAM,GAAG,EAAE,IAAI,EAAE,CAAA;IACjB,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAA;IACjD,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAA;AACtD,CAAC,CAAC,CAAA;AAEF,IAAI,CAAC,0EAA0E,EAAE,KAAK,IAAI,EAAE;IAC1F,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,WAAW,CAAC,EAAE,OAAO,EAAE,qBAAqB,EAAE,CAAC,CAAA;IAC7G,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,aAAa,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAA;IAC3F,MAAM,aAAa,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,EAAE,CAAC,CAAA;IACnE,MAAM,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,qBAAqB,CAAC;;;;;;;GAOzE,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA"}