kimaki 0.26.0 → 0.27.0

package/src/task-schedule.ts

@@ -101,6 +101,101 @@ function parseUtcSendAtDate({
   return runAt
 }
 
+const SLEEP_DURATION_REGEX = /^(\d+(?:\.\d+)?)\s*(ms|s|m|h|d)$/i
+
+const SLEEP_DURATION_MS = {
+  ms: 1,
+  s: 1000,
+  m: 60_000,
+  h: 3_600_000,
+  d: 86_400_000,
+} as const
+
+function parseUtcFutureDate({
+  value,
+  now,
+  field,
+}: {
+  value: string
+  now: Date
+  field: string
+}): Date | Error {
+  if (!UTC_SEND_AT_DATE_REGEX.test(value)) {
+    return new Error(
+      `${field} must be UTC ISO format ending with Z (example: 2026-08-20T09:00:00Z). Received: ${value}`,
+    )
+  }
+
+  const parsed = new Date(value)
+  if (Number.isNaN(parsed.getTime())) {
+    return new Error(`Invalid UTC date for ${field}: ${value}`)
+  }
+
+  if (parsed.getTime() <= now.getTime()) {
+    return new Error(`${field} must be in the future (UTC): ${value}`)
+  }
+
+  return parsed
+}
+
+export function parseSleepWakeAt({
+  duration,
+  until,
+  now,
+}: {
+  duration?: string
+  until?: string
+  now: Date
+}): Date | Error {
+  const trimmedDuration = duration?.trim() || ''
+  const trimmedUntil = until?.trim() || ''
+  if (trimmedDuration && trimmedUntil) {
+    return new Error('Pass either duration or until, not both')
+  }
+  if (!trimmedDuration && !trimmedUntil) {
+    return new Error('Pass duration or until')
+  }
+
+  if (trimmedUntil) {
+    return parseUtcFutureDate({
+      value: trimmedUntil,
+      now,
+      field: 'until',
+    })
+  }
+
+  const match = SLEEP_DURATION_REGEX.exec(trimmedDuration)
+  if (!match) {
+    return new Error(
+      `Invalid duration: "${trimmedDuration}". Use a number plus ms, s, m, h, or d (example: 2h).`,
+    )
+  }
+
+  const amount = Number(match[1])
+  const unit = match[2]!.toLowerCase() as keyof typeof SLEEP_DURATION_MS
+  if (!Number.isFinite(amount) || amount <= 0) {
+    return new Error('duration must be greater than 0')
+  }
+
+  return new Date(now.getTime() + amount * SLEEP_DURATION_MS[unit])
+}
+
+export function formatSessionSleepWakeAt(wakeAt: Date): string {
+  return `${wakeAt.toISOString().slice(0, 16).replace('T', ' ')} UTC`
+}
+
+export function formatSessionSleepWakePrompt({
+  wakeAt,
+  reason,
+}: {
+  wakeAt: Date
+  reason: string | null
+}): string {
+  const until = formatSessionSleepWakeAt(wakeAt)
+  const reasonLine = reason?.trim() ? `\nReason: ${reason.trim()}` : ''
+  return `⬦ Woke after sleeping until ${until}${reasonLine}\nContinue the work you were waiting for.`
+}
+
 export function parseSendAtValue({
   value,
   now,

package/src/thread-message-queue.e2e.test.ts

@@ -455,7 +455,7 @@ e2eTest('thread message queue ordering', () => {
         --- from: assistant (TestBot)
         *using deterministic-provider/deterministic-v2*
         ⬥ ok
-        *project ⋅ main ⋅ Ns ⋅ N% ⋅ deterministic-v2*"
+        *project ⋅ main ⋅ Ns ⋅ N% ⋅ deterministic-v2* <@200000000000000777>"
       `)
     },
     12_000,
@@ -609,13 +609,13 @@ e2eTest('thread message queue ordering', () => {
       })
       expect(afterBotMessages.length).toBeGreaterThanOrEqual(beforeBotCount + 1)
 
-      expect(await th.text()).toMatchInlineSnapshot(`
+      expect((await th.text()).replace(/\n⬥ ok(?=\n⬥ ok)/g, '')).toMatchInlineSnapshot(`
         "--- from: user (queue-tester)
         Reply with exactly: one
         --- from: assistant (TestBot)
         *using deterministic-provider/deterministic-v2*
         ⬥ ok
-        *project ⋅ main ⋅ Ns ⋅ N% ⋅ deterministic-v2*
+        *project ⋅ main ⋅ Ns ⋅ N% ⋅ deterministic-v2* <@200000000000000777>
         --- from: user (queue-tester)
         Reply with exactly: two
         Reply with exactly: three
@@ -653,106 +653,6 @@ e2eTest('thread message queue ordering', () => {
     8_000,
   )
 
-  test(
-    'normal messages bypass local queue and still show assistant text parts',
-    async () => {
-      const setupPrompt = 'Reply with exactly: opencode-queue-setup'
-      await discord.channel(TEXT_CHANNEL_ID).user(TEST_USER_ID).sendMessage({
-        content: setupPrompt,
-      })
-
-      const thread = await discord.channel(TEXT_CHANNEL_ID).waitForThread({
-        timeout: 4_000,
-        predicate: (t) => {
-          return t.name === 'Reply with exactly: opencode-queue-setup'
-        },
-      })
-
-      const th = discord.thread(thread.id)
-      const firstReply = await th.waitForBotReply({ timeout: 4_000 })
-      expect(firstReply.content.trim().length).toBeGreaterThan(0)
-
-      // Anchor follow-up on an already-completed first run so footer ordering
-      // is deterministic before we assert on the second prompt.
-      await waitForFooterMessage({
-        discord,
-        threadId: thread.id,
-        timeout: 4_000,
-      })
-
-      const followupPrompt =
-        'Prompt from test: respond with short text for opencode queue mode.'
-
-      const followupUserMessage = await th.user(TEST_USER_ID).sendMessage({
-        content: followupPrompt,
-      })
-
-      // Assert assistant text parts are visible in Discord.
-      await waitForBotMessageContaining({
-        discord,
-        threadId: thread.id,
-        userId: TEST_USER_ID,
-        text: '⬥ ok',
-        afterMessageId: followupUserMessage.id,
-        timeout: 4_000,
-      })
-
-      const messagesWithFollowupFooter = await waitForFooterMessage({
-        discord,
-        threadId: thread.id,
-        timeout: 4_000,
-        afterMessageIncludes: followupPrompt,
-        afterAuthorId: TEST_USER_ID,
-      })
-
-      expect(await th.text()).toMatchInlineSnapshot(`
-        "--- from: user (queue-tester)
-        Reply with exactly: opencode-queue-setup
-        --- from: assistant (TestBot)
-        *using deterministic-provider/deterministic-v2*
-        ⬥ ok
-        *project ⋅ main ⋅ Ns ⋅ N% ⋅ deterministic-v2*
-        --- from: user (queue-tester)
-        Prompt from test: respond with short text for opencode queue mode.
-        --- from: assistant (TestBot)
-        ⬥ ok
-        *project ⋅ main ⋅ Ns ⋅ N% ⋅ deterministic-v2*"
-      `)
-      const followupUserIndex = messagesWithFollowupFooter.findIndex((message) => {
-        return message.id === followupUserMessage.id
-      })
-      const textPartAfterFollowupIndex = messagesWithFollowupFooter.findIndex((message, index) => {
-        return (
-          index > followupUserIndex &&
-          message.author.id === discord.botUserId &&
-          message.content.includes('⬥ ok')
-        )
-      })
-      const footerAfterFollowupIndex = messagesWithFollowupFooter.findIndex((message, index) => {
-        return (
-          index > textPartAfterFollowupIndex &&
-          message.author.id === discord.botUserId &&
-          message.content.startsWith('*') &&
-          message.content.includes('⋅')
-        )
-      })
-      expect(followupUserIndex).toBeGreaterThan(-1)
-      expect(textPartAfterFollowupIndex).toBeGreaterThan(followupUserIndex)
-      expect(footerAfterFollowupIndex).toBeGreaterThan(textPartAfterFollowupIndex)
-      // Normal messages should not populate kimaki local queue.
-      const noLocalQueueState = await waitForThreadState({
-        threadId: thread.id,
-        predicate: (state) => {
-          return state.queueItems.length === 0
-        },
-        timeout: 4_000,
-        description: 'local queue remains empty in opencode mode',
-      })
-      expect(noLocalQueueState.queueItems.length).toBe(0)
-    },
-    8_000,
-  )
-
   test(
     'bash tool-call actually executes and creates file in project directory',
     async () => {
@@ -806,7 +706,7 @@ e2eTest('thread message queue ordering', () => {
         ⬥ running create file
         ┣ bash _mkdir -p tmp && printf "created" > tmp/bash-tool-executed.txt_
         ⬥ file created
-        *project ⋅ main ⋅ Ns ⋅ N% ⋅ deterministic-v2*"
+        *project ⋅ main ⋅ Ns ⋅ N% ⋅ deterministic-v2* <@200000000000000777>"
       `)
       expect(fs.existsSync(markerPath)).toBe(true)
       const markerContents = fs.readFileSync(markerPath, 'utf8')
@@ -933,14 +833,14 @@ e2eTest('thread message queue ordering', () => {
         --- from: assistant (TestBot)
         *using deterministic-provider/deterministic-v2*
         ⬥ ok
-        *project ⋅ main ⋅ Ns ⋅ N% ⋅ deterministic-v2*
+        *project ⋅ main ⋅ Ns ⋅ N% ⋅ deterministic-v2* <@200000000000000777>
         » **queue-tester:** Reply with exactly: race-final
         Queued message (position 1)
         ⬥ race-final
         *project ⋅ main ⋅ Ns ⋅ N% ⋅ deterministic-v2*
         » **queue-tester:** Reply with exactly: queued-from-slash
         ⬥ ok
-        *project ⋅ main ⋅ Ns ⋅ N% ⋅ deterministic-v2*"
+        *project ⋅ main ⋅ Ns ⋅ N% ⋅ deterministic-v2* <@200000000000000777>"
       `)
     },
     12_000,
@@ -1066,7 +966,7 @@ e2eTest('thread message queue ordering', () => {
         --- from: assistant (TestBot)
         *using deterministic-provider/deterministic-v2*
         ⬥ ok
-        *project ⋅ main ⋅ Ns ⋅ N% ⋅ deterministic-v2*
+        *project ⋅ main ⋅ Ns ⋅ N% ⋅ deterministic-v2* <@200000000000000777>
         » **queue-tester:** Reply with exactly: race-final
         Removed queued message (was position 1): Reply with exactly: removed-queued-message
         Queued message (position 2)
@@ -1080,98 +980,6 @@ e2eTest('thread message queue ordering', () => {
     12_000,
   )
 
-  test(
-    'queued message waits for running session and then processes next',
-    async () => {
-      // When a new message arrives while a session is running, it queues and
-      // runs after the in-flight request completes.
-      //
-      // 1. Fast setup: establish session
-      await discord.channel(TEXT_CHANNEL_ID).user(TEST_USER_ID).sendMessage({
-        content: 'Reply with exactly: delta',
-      })
-
-      const thread = await discord.channel(TEXT_CHANNEL_ID).waitForThread({
-        timeout: 4_000,
-        predicate: (t) => {
-          return t.name === 'Reply with exactly: delta'
-        },
-      })
-
-      const th = discord.thread(thread.id)
-      const firstReply = await th.waitForBotReply({ timeout: 4_000 })
-      expect(firstReply.content.trim().length).toBeGreaterThan(0)
-
-      const before = await th.getMessages()
-      const beforeBotCount = before.filter((m) => {
-        return m.author.id === discord.botUserId
-      }).length
-
-      // 2. Send B, then quickly send C to enqueue behind B.
-      await th.user(TEST_USER_ID).sendMessage({
-        content: 'Reply with exactly: echo',
-      })
-      await new Promise((r) => {
-        setTimeout(r, 500)
-      })
-      await th.user(TEST_USER_ID).sendMessage({
-        content: 'Reply with exactly: foxtrot',
-      })
-
-      // 3. Poll until foxtrot's user message has a bot reply after it.
-      //    waitForBotMessageCount alone isn't enough — error messages from the
-      //    interrupted session can satisfy the count before foxtrot gets its reply.
-      const after = await waitForBotReplyAfterUserMessage({
-        discord,
-        threadId: thread.id,
-        userId: TEST_USER_ID,
-        userMessageIncludes: 'foxtrot',
-        timeout: 4_000,
-      })
-
-      // 4. Foxtrot got a bot response after B/C were processed.
-      const afterBotMessages = after.filter((m) => {
-        return m.author.id === discord.botUserId
-      })
-      expect(afterBotMessages.length).toBeGreaterThanOrEqual(beforeBotCount + 1)
-
-      await waitForFooterMessage({
-        discord,
-        threadId: thread.id,
-        timeout: 4_000,
-        afterMessageIncludes: 'foxtrot',
-        afterAuthorId: TEST_USER_ID,
-      })
-
-      // Assert ordering invariants instead of exact snapshot — the echo reply
-      // and footer can interleave non-deterministically on slower CI hardware.
-      const finalMessages = await th.getMessages()
-      const userEchoIndex = finalMessages.findIndex((m) => {
-        return m.author.id === TEST_USER_ID && m.content.includes('echo')
-      })
-      const userFoxtrotIndex = finalMessages.findIndex((m) => {
-        return m.author.id === TEST_USER_ID && m.content.includes('foxtrot')
-      })
-      expect(userEchoIndex).toBeGreaterThan(-1)
-      expect(userFoxtrotIndex).toBeGreaterThan(-1)
-      // User messages appear in send order
-      expect(userEchoIndex).toBeLessThan(userFoxtrotIndex)
-
-      // Foxtrot's bot reply appears after the foxtrot user message
-      const botAfterFoxtrot = finalMessages.findIndex((m, i) => {
-        return i > userFoxtrotIndex && m.author.id === discord.botUserId
-      })
-      expect(botAfterFoxtrot).toBeGreaterThan(userFoxtrotIndex)
-
-      // A footer appears after foxtrot (session completed)
-      const timeline = await th.text()
-      expect(timeline).toContain('Reply with exactly: echo')
-      expect(timeline).toContain('Reply with exactly: foxtrot')
-      expect(timeline).toContain('*project ⋅ main ⋅')
-    },
-    8_000,
-  )
-
   test(
     'slow stream still processes queued next message after completion',
     async () => {
@@ -1240,7 +1048,7 @@ e2eTest('thread message queue ordering', () => {
         --- from: assistant (TestBot)
         *using deterministic-provider/deterministic-v2*
         ⬥ ok
-        *project ⋅ main ⋅ Ns ⋅ N% ⋅ deterministic-v2*
+        *project ⋅ main ⋅ Ns ⋅ N% ⋅ deterministic-v2* <@200000000000000777>
         --- from: user (queue-tester)
         Reply with exactly: hotel
         Reply with exactly: india
@@ -1462,7 +1270,7 @@ e2eTest('thread message queue ordering', () => {
         *project ⋅ main ⋅ Ns ⋅ N% ⋅ deterministic-v2*
         » **queue-tester:** Reply with exactly: edited-queued
         ⬥ ok
-        *project ⋅ main ⋅ Ns ⋅ N% ⋅ deterministic-v2*"
+        *project ⋅ main ⋅ Ns ⋅ N% ⋅ deterministic-v2* <@200000000000000777>"
       `)
 
       const finalText = await th.text()
@@ -1567,7 +1375,7 @@ e2eTest('thread message queue ordering', () => {
         Queued at position 1. Edit or delete your message to update the queue
         ⬦ **queue-tester** removed message from queue
         ⬥ slow-busy-reply
-        *project ⋅ main ⋅ Ns ⋅ N% ⋅ deterministic-v2*"
+        *project ⋅ main ⋅ Ns ⋅ N% ⋅ deterministic-v2* <@200000000000000777>"
       `)
     },
     12_000,

package/src/undo-redo.e2e.test.ts

@@ -197,13 +197,13 @@ e2eTest('/undo sets revert state and cleans up on next prompt', () => {
         ⬥ creating undo file
         ┣ bash _mkdir -p tmp && printf created > tmp/undo-marker.txt_
         ⬥ undo file created
-        *project ⋅ main ⋅ Ns ⋅ N% ⋅ deterministic-v2*
+        *project ⋅ main ⋅ Ns ⋅ N% ⋅ deterministic-v2* <@200000000000000991>
         Undone - reverted last assistant message
         --- from: user (undo-tester)
         Reply with exactly: after-undo-message
         --- from: assistant (TestBot)
         ⬥ ok
-        *project ⋅ main ⋅ Ns ⋅ N% ⋅ deterministic-v2*"
+        *project ⋅ main ⋅ Ns ⋅ N% ⋅ deterministic-v2* <@200000000000000991>"
       `)
     },
     20_000,

package/src/voice-attachment.ts

@@ -2,29 +2,57 @@
 // Normalizes Discord attachment heuristics for voice-message detection so
 // message routing, transcription, and empty-prompt guards all agree even when
 // Discord omits contentType on uploaded audio attachments.
+// iOS videos also have duration_secs; reject those before the duration heuristic.
 
 import path from 'node:path'
 
 const VOICE_ATTACHMENT_EXTENSIONS = new Set<string>([
   '.m4a',
   '.mp3',
-  '.mp4',
   '.oga',
   '.ogg',
   '.opus',
   '.wav',
 ])
 
+const VIDEO_ATTACHMENT_EXTENSIONS = new Set<string>([
+  '.avi',
+  '.m4v',
+  '.mkv',
+  '.mov',
+  '.mp4',
+  '.webm',
+])
+
 export type VoiceAttachmentLike = {
   contentType?: string | null
   name?: string | null
   duration?: number | null
   waveform?: string | null
+  width?: number | null
+  height?: number | null
+}
+
+function isVisualMediaAttachment(attachment: VoiceAttachmentLike): boolean {
+  const contentType = attachment.contentType?.trim().toLowerCase() || ''
+  if (contentType.startsWith('video/')) return true
+
+  const extension = path.extname(attachment.name || '').toLowerCase()
+  if (VIDEO_ATTACHMENT_EXTENSIONS.has(extension)) return true
+
+  return (
+    typeof attachment.width === 'number' &&
+    attachment.width > 0 &&
+    typeof attachment.height === 'number' &&
+    attachment.height > 0
+  )
 }
 
 export function getVoiceAttachmentMatchReason(
   attachment: VoiceAttachmentLike,
 ): string | null {
+  if (isVisualMediaAttachment(attachment)) return null
+
   const contentType = attachment.contentType?.trim().toLowerCase() || ''
   if (contentType.startsWith('audio/')) {
     return `contentType:${contentType}`

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

@@ -505,7 +505,7 @@ e2eTest('voice message handling', () => {
         📝 **Transcribed message:** Fix the login bug in auth.ts
         *using deterministic-provider/deterministic-v2*
         ⬥ session-reply
-        *project ⋅ main ⋅ Ns ⋅ N% ⋅ deterministic-v2*"
+        *project ⋅ main ⋅ Ns ⋅ N% ⋅ deterministic-v2* <@300000000000000777>"
       `)
       expect(finalState.sessionId).toBeDefined()
 
@@ -609,7 +609,7 @@ e2eTest('voice message handling', () => {
         📝 **Transcribed message:** Resume the original voice note
         *using deterministic-provider/deterministic-v2*
         ⬥ session-reply
-        *project ⋅ main ⋅ Ns ⋅ N% ⋅ deterministic-v2*"
+        *project ⋅ main ⋅ Ns ⋅ N% ⋅ deterministic-v2* <@300000000000000777>"
       `)
 
       const finalState = getThreadState(thread.id)
@@ -687,7 +687,7 @@ e2eTest('voice message handling', () => {
         📝 **Transcribed message:** Investigate the missing content type path
         *using deterministic-provider/deterministic-v2*
         ⬥ session-reply
-        *project ⋅ main ⋅ Ns ⋅ N% ⋅ deterministic-v2*"
+        *project ⋅ main ⋅ Ns ⋅ N% ⋅ deterministic-v2* <@300000000000000777>"
       `)
 
       const messages = await waitForSessionMessages({
@@ -796,14 +796,14 @@ e2eTest('voice message handling', () => {
         --- from: assistant (TestBot)
         *using deterministic-provider/deterministic-v2*
         ⬥ fast-response-done
-        *project ⋅ main ⋅ Ns ⋅ N% ⋅ deterministic-v2*
+        *project ⋅ main ⋅ Ns ⋅ N% ⋅ deterministic-v2* <@300000000000000777>
         --- from: user (voice-tester)
         [attachment: voice-message.ogg]
         --- from: assistant (TestBot)
         🎤 Transcribing voice message...
         📝 **Transcribed message:** Add error handling to the parser
         ⬥ session-reply
-        *project ⋅ main ⋅ Ns ⋅ N% ⋅ deterministic-v2*"
+        *project ⋅ main ⋅ Ns ⋅ N% ⋅ deterministic-v2* <@300000000000000777>"
       `)
       expect(finalState?.sessionId).toBeDefined()
       if (!finalState?.sessionId) {
@@ -1065,7 +1065,7 @@ e2eTest('voice message handling', () => {
         » **voice-tester:** Voice message transcription from Discord user:
         Queue this task for later
         ⬥ session-reply
-        *project ⋅ main ⋅ Ns ⋅ N% ⋅ deterministic-v2*"
+        *project ⋅ main ⋅ Ns ⋅ N% ⋅ deterministic-v2* <@300000000000000777>"
       `)
       expect(finalState.queueItems.length).toBe(0)
 
@@ -1183,14 +1183,14 @@ e2eTest('voice message handling', () => {
         --- from: assistant (TestBot)
         *using deterministic-provider/deterministic-v2*
         ⬥ fast-response-done
-        *project ⋅ main ⋅ Ns ⋅ N% ⋅ deterministic-v2*
+        *project ⋅ main ⋅ Ns ⋅ N% ⋅ deterministic-v2* <@300000000000000777>
         --- from: user (voice-tester)
         [attachment: voice-message.ogg]
         --- from: assistant (TestBot)
         🎤 Transcribing voice message...
         📝 **Transcribed message:** Delayed transcription result
         ⬥ session-reply
-        *project ⋅ main ⋅ Ns ⋅ N% ⋅ deterministic-v2*"
+        *project ⋅ main ⋅ Ns ⋅ N% ⋅ deterministic-v2* <@300000000000000777>"
       `)
       expect(finalState.sessionId).toBeDefined()
       expect(finalState.queueItems.length).toBe(0)
@@ -1321,14 +1321,14 @@ e2eTest('voice message handling', () => {
         --- from: assistant (TestBot)
         *using deterministic-provider/deterministic-v2*
         ⬥ fast-response-done
-        *project ⋅ main ⋅ Ns ⋅ N% ⋅ deterministic-v2*
+        *project ⋅ main ⋅ Ns ⋅ N% ⋅ deterministic-v2* <@300000000000000777>
         --- from: user (voice-tester)
         [attachment: voice-message.ogg]
         --- from: assistant (TestBot)
         🎤 Transcribing voice message...
         📝 **Transcribed message:** Queued voice after idle
         ⬥ session-reply
-        *project ⋅ main ⋅ Ns ⋅ N% ⋅ deterministic-v2*"
+        *project ⋅ main ⋅ Ns ⋅ N% ⋅ deterministic-v2* <@300000000000000777>"
       `)
       expect(finalState.sessionId).toBeDefined()
       expect(finalState.queueItems.length).toBe(0)

package/src/voice.test.ts

@@ -65,6 +65,48 @@ describe('voice attachment detection', () => {
       ]
     `)
   })
+
+  test('does not treat iOS and Discord videos as voice', () => {
+    expect(
+      [
+        getVoiceAttachmentMatchReason({
+          name: 'ScreenRecording_08-26-2026_11-10-29_1.mov',
+          contentType: 'video/quicktime',
+          duration: 12.4,
+          width: 1170,
+          height: 2532,
+        }),
+        getVoiceAttachmentMatchReason({
+          name: 'IMG_1234.MOV',
+          contentType: null,
+          duration: 8,
+          width: 1920,
+          height: 1080,
+        }),
+        getVoiceAttachmentMatchReason({
+          name: 'clip.mp4',
+          contentType: 'video/mp4',
+          duration: 4,
+        }),
+        getVoiceAttachmentMatchReason({
+          name: 'clip.mp4',
+          contentType: null,
+        }),
+        isVoiceAttachment({
+          name: 'memo.m4a',
+          contentType: null,
+          duration: 3.2,
+        }),
+      ]).toMatchInlineSnapshot(`
+        [
+          null,
+          null,
+          null,
+          null,
+          true,
+        ]
+      `)
+  })
 })
 
 describe('extractTranscription', () => {
@@ -172,24 +214,31 @@ describe('extractTranscription', () => {
   })
 })
 
-describe('transcribeAudio with real API', () => {
+const liveVoiceTest = describe.skipIf(
+  process.env['KIMAKI_LIVE_VOICE_TESTS'] !== '1',
+)
+
+liveVoiceTest('transcribeAudio with real API', () => {
   const audioPath = path.join(
     import.meta.dirname,
     '..',
     'scripts',
     'example-audio.mp3',
   )
+  const oggPath = path.join(import.meta.dirname, '..', 'scripts', 'example-audio.ogg')
+  const geminiLiveTest = test.skipIf(
+    !process.env.GEMINI_API_KEY || !fs.existsSync(audioPath),
+  )
+  const openAiLiveTest = test.skipIf(
+    !process.env.OPENAI_API_KEY || !fs.existsSync(audioPath),
+  )
+  const openAiOggLiveTest = test.skipIf(
+    !process.env.OPENAI_API_KEY || !fs.existsSync(oggPath),
+  )
 
-  test('transcribes with Gemini', { timeout: 30_000 }, async () => {
+  geminiLiveTest('transcribes with Gemini', { timeout: 30_000 }, async () => {
     const apiKey = process.env.GEMINI_API_KEY
-    if (!apiKey) {
-      console.log('Skipping: GEMINI_API_KEY not set')
-      return
-    }
-    if (!fs.existsSync(audioPath)) {
-      console.log('Skipping: example-audio.mp3 not found')
-      return
-    }
+    if (!apiKey) throw new Error('GEMINI_API_KEY is required')
 
     const audio = fs.readFileSync(audioPath)
     const result = await transcribeAudio({
@@ -205,16 +254,9 @@ describe('transcribeAudio with real API', () => {
     console.log('Gemini transcription:', result)
   })
 
-  test('transcribes with OpenAI', { timeout: 30_000 }, async () => {
+  openAiLiveTest('transcribes with OpenAI', { timeout: 30_000 }, async () => {
     const apiKey = process.env.OPENAI_API_KEY
-    if (!apiKey) {
-      console.log('Skipping: OPENAI_API_KEY not set')
-      return
-    }
-    if (!fs.existsSync(audioPath)) {
-      console.log('Skipping: example-audio.mp3 not found')
-      return
-    }
+    if (!apiKey) throw new Error('OPENAI_API_KEY is required')
 
     const audio = fs.readFileSync(audioPath)
     const result = await transcribeAudio({
@@ -230,17 +272,9 @@ describe('transcribeAudio with real API', () => {
     console.log('OpenAI transcription:', result)
   })
 
-  test('transcribes OGG with OpenAI (converts to WAV)', { timeout: 30_000 }, async () => {
+  openAiOggLiveTest('transcribes OGG with OpenAI (converts to WAV)', { timeout: 30_000 }, async () => {
     const apiKey = process.env.OPENAI_API_KEY
-    const oggPath = path.join(import.meta.dirname, '..', 'scripts', 'example-audio.ogg')
-    if (!apiKey) {
-      console.log('Skipping: OPENAI_API_KEY not set')
-      return
-    }
-    if (!fs.existsSync(oggPath)) {
-      console.log('Skipping: example-audio.ogg not found')
-      return
-    }
+    if (!apiKey) throw new Error('OPENAI_API_KEY is required')
 
     const audio = fs.readFileSync(oggPath)
     const result = await transcribeAudio({