@swarmclawai/swarmclaw 0.6.4 → 0.6.6

package/src/components/wallets/wallet-section.tsx

@@ -0,0 +1,100 @@
+'use client'
+
+import { useState, useCallback } from 'react'
+import { api } from '@/lib/api-client'
+import type { AgentWallet, WalletChain } from '@/types'
+
+interface WalletSectionProps {
+  agentId: string
+  wallet: (Omit<AgentWallet, 'encryptedPrivateKey'> & { balanceLamports?: number; balanceSol?: number }) | null
+  onWalletCreated: () => void
+}
+
+export function WalletSection({ agentId, wallet, onWalletCreated }: WalletSectionProps) {
+  const [creating, setCreating] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+  const [copied, setCopied] = useState(false)
+
+  const createWallet = useCallback(async () => {
+    setCreating(true)
+    setError(null)
+    try {
+      await api('POST', '/wallets', { agentId, chain: 'solana' as WalletChain })
+      onWalletCreated()
+    } catch (err: unknown) {
+      setError(err instanceof Error ? err.message : String(err))
+    } finally {
+      setCreating(false)
+    }
+  }, [agentId, onWalletCreated])
+
+  const copyAddress = useCallback(() => {
+    if (!wallet) return
+    navigator.clipboard.writeText(wallet.publicKey)
+    setCopied(true)
+    setTimeout(() => setCopied(false), 2000)
+  }, [wallet])
+
+  return (
+    <div className="mb-8">
+      <div className="flex items-center gap-2 mb-3">
+        <label className="block font-display text-[12px] font-600 text-text-2 uppercase tracking-[0.08em]">
+          Wallet
+        </label>
+        <span className="px-1.5 py-0.5 rounded-[4px] bg-amber-500/15 text-amber-400 text-[9px] font-600 uppercase tracking-wide">
+          Experimental
+        </span>
+      </div>
+
+      {!wallet ? (
+        <div className="p-4 rounded-[12px] border border-white/[0.06] bg-surface-2/50">
+          <p className="text-[12px] text-text-3/70 mb-3">
+            Create a Solana wallet for this agent to hold funds, pay for services, and trade autonomously.
+          </p>
+          <button
+            type="button"
+            onClick={createWallet}
+            disabled={creating}
+            className="px-3 py-1.5 rounded-[8px] bg-accent-soft text-accent-bright text-[11px] font-600 hover:bg-accent-bright/15 transition-all cursor-pointer disabled:opacity-50 border border-accent-bright/20"
+            style={{ fontFamily: 'inherit' }}
+          >
+            {creating ? 'Creating...' : 'Create Wallet'}
+          </button>
+          {error && <p className="text-[11px] text-red-400 mt-2">{error}</p>}
+        </div>
+      ) : (
+        <div className="p-4 rounded-[12px] border border-white/[0.06] bg-surface-2/50 space-y-3">
+          <div className="flex items-center gap-2">
+            <span className="text-[10px] text-text-3/60 uppercase tracking-wide font-600">
+              {wallet.chain}
+            </span>
+            <span className="flex-1" />
+            {typeof wallet.balanceSol === 'number' && (
+              <span className="text-[13px] font-600 text-text-1">
+                {wallet.balanceSol.toFixed(4)} SOL
+              </span>
+            )}
+          </div>
+          <div className="flex items-center gap-2">
+            <code className="text-[11px] text-text-3 bg-black/20 px-2 py-1 rounded-[6px] font-mono truncate flex-1">
+              {wallet.publicKey}
+            </code>
+            <button
+              type="button"
+              onClick={copyAddress}
+              className="shrink-0 px-2 py-1 rounded-[6px] text-[10px] text-text-3 hover:text-text-2 border border-white/[0.08] bg-surface transition-colors cursor-pointer"
+              style={{ fontFamily: 'inherit' }}
+            >
+              {copied ? 'Copied!' : 'Copy'}
+            </button>
+          </div>
+          <div className="flex items-center gap-3 text-[10px] text-text-3/60">
+            <span>Limit: {((wallet.spendingLimitLamports ?? 100_000_000) / 1e9).toFixed(2)} SOL/tx</span>
+            <span>Daily: {((wallet.dailyLimitLamports ?? 1_000_000_000) / 1e9).toFixed(1)} SOL</span>
+            <span>{wallet.requireApproval ? 'Approval required' : 'Auto-send'}</span>
+          </div>
+        </div>
+      )}
+    </div>
+  )
+}

package/src/lib/server/agent-registry.ts

@@ -63,8 +63,8 @@ export function buildAgentAwarenessBlock(excludeId: string): string {
   })
 
   return [
-    '## Available Agents',
+    '## My Colleagues',
+    'These are the other agents I work alongside. I can hand off tasks to any of them if their skills are a better fit:',
     ...lines,
-    'You can delegate tasks to any agent using the delegate_to_agent tool.',
   ].join('\n')
 }

package/src/lib/server/chat-execution.ts

@@ -109,6 +109,21 @@ function collectToolEvent(ev: SSEEvent, bag: MessageToolEvent[]) {
   }
 }
 
+function shouldReplaceRecentAssistantMessage(params: {
+  previous: Message | null | undefined
+  nextToolEvents: MessageToolEvent[]
+  nextKind: Message['kind']
+  now: number
+}): boolean {
+  const { previous, nextToolEvents, nextKind, now } = params
+  if (!previous || previous.role !== 'assistant') return false
+  if (nextToolEvents.length === 0) return false
+  if (previous.kind && nextKind && previous.kind !== nextKind) return false
+  if (typeof previous.time === 'number' && now - previous.time > 45_000) return false
+  const prevTools = Array.isArray(previous.toolEvents) ? previous.toolEvents.length : 0
+  return prevTools === 0
+}
+
 function requestedToolNamesFromMessage(message: string): string[] {
   const lower = message.toLowerCase()
   const candidates = [
@@ -377,6 +392,11 @@ function buildAgentSystemPrompt(session: any): string | undefined {
 
   const settings = loadSettings()
   const parts: string[] = []
+  // Identity block — agent needs to know who it is
+  const identityLines = [`## My Identity`, `My name is ${agent.name}.`]
+  if (agent.description) identityLines.push(agent.description)
+  identityLines.push('I should always refer to myself by this name. I am not "Assistant" — I have my own name and identity.')
+  parts.push(identityLines.join(' '))
   if (settings.userPrompt) parts.push(settings.userPrompt)
   parts.push(buildCurrentDateTimePromptContext())
   if (agent.soul) parts.push(agent.soul)
@@ -1014,14 +1034,26 @@ export async function executeSessionChatTurn(input: ExecuteChatTurnInput): Promi
       const persistedText = heartbeatClassification === 'strip'
         ? textForPersistence.replace(/HEARTBEAT_OK/gi, '').trim()
         : textForPersistence
-      current.messages.push({
+      const nowTs = Date.now()
+      const nextAssistantMessage: Message = {
         role: 'assistant',
         text: persistedText,
-        time: Date.now(),
+        time: nowTs,
         thinking: thinkingText || undefined,
         toolEvents: toolEvents.length ? toolEvents : undefined,
         kind: persistedKind,
-      })
+      }
+      const previous = current.messages.at(-1)
+      if (shouldReplaceRecentAssistantMessage({
+        previous,
+        nextToolEvents: toolEvents,
+        nextKind: persistedKind,
+        now: nowTs,
+      })) {
+        current.messages[current.messages.length - 1] = nextAssistantMessage
+      } else {
+        current.messages.push(nextAssistantMessage)
+      }
       changed = true
 
       // Conversation tone detection

package/src/lib/server/chatroom-health.ts

@@ -0,0 +1,60 @@
+import { getProvider } from '@/lib/providers'
+import type { Agent } from '@/types'
+import { resolveApiKey } from './chatroom-helpers'
+import { isProviderCoolingDown } from './provider-health'
+
+export interface ChatroomAgentHealthSkip {
+  agentId: string
+  reason: string
+}
+
+export interface ChatroomAgentHealthResult {
+  healthyAgentIds: string[]
+  skipped: ChatroomAgentHealthSkip[]
+}
+
+/**
+ * Filter chatroom participants to agents that are currently executable.
+ * This should never enforce model diversity rules; it only gates hard runtime blockers.
+ */
+export function filterHealthyChatroomAgents(
+  agentIds: string[],
+  agents: Record<string, Agent>,
+): ChatroomAgentHealthResult {
+  const healthyAgentIds: string[] = []
+  const skipped: ChatroomAgentHealthSkip[] = []
+
+  for (const agentId of agentIds) {
+    const agent = agents[agentId]
+    if (!agent) {
+      skipped.push({ agentId, reason: 'agent_not_found' })
+      continue
+    }
+
+    if (isProviderCoolingDown(agent.provider)) {
+      skipped.push({ agentId, reason: `provider_cooling_down:${agent.provider}` })
+      continue
+    }
+
+    const providerInfo = getProvider(agent.provider)
+    if (!providerInfo) {
+      skipped.push({ agentId, reason: `provider_not_configured:${agent.provider}` })
+      continue
+    }
+
+    const apiKey = resolveApiKey(agent.credentialId)
+    if (providerInfo.requiresApiKey && !apiKey) {
+      skipped.push({ agentId, reason: 'missing_api_credentials' })
+      continue
+    }
+    if (providerInfo.requiresEndpoint && !agent.apiEndpoint) {
+      skipped.push({ agentId, reason: 'missing_api_endpoint' })
+      continue
+    }
+
+    healthyAgentIds.push(agentId)
+  }
+
+  return { healthyAgentIds, skipped }
+}
+

package/src/lib/server/chatroom-helpers.test.ts

@@ -0,0 +1,94 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import type { Agent, Chatroom } from '@/types'
+import { parseMentions, compactChatroomMessages, buildHistoryForAgent } from './chatroom-helpers'
+
+function makeAgents(): Record<string, Agent> {
+  const now = Date.now()
+  return {
+    default: {
+      id: 'default',
+      name: 'Assistant',
+      description: '',
+      systemPrompt: '',
+      provider: 'openai',
+      model: 'gpt-4o',
+      createdAt: now,
+      updatedAt: now,
+    },
+    agent_analyst: {
+      id: 'agent_analyst',
+      name: 'Analyst',
+      description: '',
+      systemPrompt: '',
+      provider: 'openai',
+      model: 'gpt-4o',
+      createdAt: now,
+      updatedAt: now,
+    },
+  }
+}
+
+describe('chatroom-helpers', () => {
+  it('parses mentions with punctuation and agent ids', () => {
+    const agents = makeAgents()
+    const memberIds = ['default', 'agent_analyst']
+    const mentions = parseMentions('Hey @Assistant, can @agent_analyst review this?', agents, memberIds)
+    assert.deepEqual(mentions, ['default', 'agent_analyst'])
+  })
+
+  it('compacts long chatrooms with a persisted summary message', () => {
+    const now = Date.now()
+    const chatroom: Chatroom = {
+      id: 'room-1',
+      name: 'Room',
+      description: '',
+      agentIds: ['default'],
+      messages: Array.from({ length: 120 }, (_, idx) => ({
+        id: `m-${idx}`,
+        senderId: idx % 2 === 0 ? 'user' : 'default',
+        senderName: idx % 2 === 0 ? 'You' : 'Assistant',
+        role: idx % 2 === 0 ? 'user' : 'assistant',
+        text: `message ${idx}`,
+        mentions: [],
+        reactions: [],
+        time: now + idx,
+      })),
+      createdAt: now,
+      updatedAt: now,
+    }
+
+    const changed = compactChatroomMessages(chatroom, 90)
+    assert.equal(changed, true)
+    assert.equal(chatroom.messages.length, 91)
+    assert.equal(chatroom.messages[0].senderId, 'system')
+    assert.match(chatroom.messages[0].text, /^\[Conversation summary\]/)
+  })
+
+  it('only includes attachment-heavy context for recent history entries', () => {
+    const now = Date.now()
+    const chatroom: Chatroom = {
+      id: 'room-2',
+      name: 'Room',
+      agentIds: ['default'],
+      messages: Array.from({ length: 24 }, (_, idx) => ({
+        id: `x-${idx}`,
+        senderId: idx % 2 === 0 ? 'user' : 'default',
+        senderName: idx % 2 === 0 ? 'You' : 'Assistant',
+        role: idx % 2 === 0 ? 'user' : 'assistant',
+        text: `line ${idx}`,
+        mentions: [],
+        reactions: [],
+        time: now + idx,
+        ...(idx < 10 ? { attachedFiles: [`/tmp/file-${idx}.txt`] } : {}),
+      })),
+      createdAt: now,
+      updatedAt: now,
+    }
+
+    const history = buildHistoryForAgent(chatroom, 'default')
+    const attachmentMarkers = history.filter((msg) => msg.text.includes('[Attached:')).length
+    assert.ok(attachmentMarkers <= 6)
+  })
+})
+

package/src/lib/server/chatroom-helpers.ts

@@ -1,5 +1,6 @@
 import { loadSettings, loadSkills, loadCredentials, decryptKey } from './storage'
 import { buildCurrentDateTimePromptContext } from './prompt-runtime-context'
+import { genId } from '@/lib/id'
 import type { Chatroom, Agent, Session, Message } from '@/types'
 
 /** Resolve API key from an agent's credentialId */
@@ -11,17 +12,36 @@ export function resolveApiKey(credentialId: string | null | undefined): string |
   try { return decryptKey(cred.encryptedKey) } catch { return null }
 }
 
+const COMPACTION_PREFIX = '[Conversation summary]'
+
+function normalizeMentionToken(raw: string): string {
+  return raw
+    .toLowerCase()
+    .replace(/[.,!?;:]+$/g, '')
+    .replace(/\s+/g, '')
+    .trim()
+}
+
+function truncateText(text: string, max: number): string {
+  const compact = String(text || '').replace(/\s+/g, ' ').trim()
+  if (compact.length <= max) return compact
+  return `${compact.slice(0, Math.max(0, max - 3))}...`
+}
+
 /** Parse @mentions from message text, returns matching agentIds */
 export function parseMentions(text: string, agents: Record<string, Agent>, memberIds: string[]): string[] {
   if (/@all\b/i.test(text)) return [...memberIds]
-  const mentionPattern = /@(\S+)/g
+  const mentionPattern = /(?:^|[\s(])@([a-zA-Z0-9._-]+)/g
   const mentioned: string[] = []
   let match: RegExpExecArray | null
   while ((match = mentionPattern.exec(text)) !== null) {
-    const name = match[1].toLowerCase()
+    const token = normalizeMentionToken(match[1] || '')
+    if (!token) continue
     for (const id of memberIds) {
       const agent = agents[id]
-      if (agent && agent.name.toLowerCase().replace(/\s+/g, '') === name) {
+      const normalizedName = normalizeMentionToken(agent?.name || '')
+      const normalizedId = normalizeMentionToken(id)
+      if (agent && (normalizedName === token || normalizedId === token)) {
         if (!mentioned.includes(id)) mentioned.push(id)
       }
     }
@@ -29,6 +49,34 @@ export function parseMentions(text: string, agents: Record<string, Agent>, membe
   return mentioned
 }
 
+/**
+ * Persisted chatroom compaction so long-lived rooms stay inside context budgets.
+ * Returns true when the message list was compacted.
+ */
+export function compactChatroomMessages(chatroom: Chatroom, keepLast = 90): boolean {
+  const maxKeep = Math.max(20, keepLast)
+  if (!Array.isArray(chatroom.messages) || chatroom.messages.length <= maxKeep) return false
+
+  const dropped = chatroom.messages.length - maxKeep
+  const kept = chatroom.messages.slice(-maxKeep).filter((msg, idx) => {
+    if (idx !== 0) return true
+    return !(msg.senderId === 'system' && typeof msg.text === 'string' && msg.text.startsWith(COMPACTION_PREFIX))
+  })
+  const summaryMessage = {
+    id: genId(),
+    senderId: 'system',
+    senderName: 'System',
+    role: 'assistant' as const,
+    text: `${COMPACTION_PREFIX} ${dropped} earlier chat message(s) were condensed to keep the room responsive.`,
+    mentions: [],
+    reactions: [],
+    time: Date.now(),
+  }
+  chatroom.messages = [summaryMessage, ...kept]
+  chatroom.updatedAt = Date.now()
+  return true
+}
+
 /** Build chatroom context as a system prompt addendum with agent profiles and collaboration guidelines */
 export function buildChatroomSystemPrompt(chatroom: Chatroom, agents: Record<string, Agent>, agentId: string): string {
   const selfAgent = agents[agentId]
@@ -47,9 +95,10 @@ export function buildChatroomSystemPrompt(chatroom: Chatroom, agents: Record<str
     .filter(Boolean)
     .join('\n')
 
-  const recentMessages = chatroom.messages.slice(-30).map((m) => {
-    return `[${m.senderName}]: ${m.text}`
-  }).join('\n')
+  const recentMessages = chatroom.messages
+    .slice(-8)
+    .map((m) => `[${m.senderName}]: ${truncateText(m.text, 180)}`)
+    .join('\n')
 
   const memberCount = chatroom.agentIds.length
   const otherNames = chatroom.agentIds
@@ -70,6 +119,8 @@ export function buildChatroomSystemPrompt(chatroom: Chatroom, agents: Record<str
     '- **You are in a group chat.** Talk like you are in a real-time conversation with teammates — be direct, casual, and concise.',
     '- **Be yourself.** Respond with personality. Don\'t give generic "let me know if you need anything" responses. Actually engage with what was said.',
     '- **Answer the question or react to the message.** If someone says "how are you doing?" just answer naturally. If someone asks a question you can help with, help directly.',
+    '- **Do not meta-narrate user intent.** Avoid phrases like "it seems like you\'re trying to..." — respond directly to what they said.',
+    '- **Handle greetings like a human.** For "hello", "how are you", or light check-ins, give a normal conversational reply instead of tool/process commentary.',
     '- **Keep responses short** unless depth is needed. A few sentences is usually enough. This is a chat, not an essay.',
     '- **@mention teammates** only when you genuinely need their specific expertise. Don\'t tag people just to be polite.',
     '- **Don\'t narrate your capabilities** unless asked. Just demonstrate them by doing things.',
@@ -121,10 +172,12 @@ export function buildAgentSystemPromptForChatroom(agent: Agent): string {
 
 /** Convert chatroom messages to Message history format for LLM */
 export function buildHistoryForAgent(chatroom: Chatroom, agentId: string, imagePath?: string, attachedFiles?: string[]): Message[] {
-  const history = chatroom.messages.slice(-50).map((m) => {
+  const recentMessages = chatroom.messages.slice(-24)
+  const includeAttachmentsFrom = Math.max(0, recentMessages.length - 6)
+  const history = recentMessages.map((m, idx) => {
     let msgText = `[${m.senderName}]: ${m.text}`
-    // Include attachment info in history
-    if (m.attachedFiles?.length) {
+    const includeAttachments = idx >= includeAttachmentsFrom
+    if (includeAttachments && m.attachedFiles?.length) {
       const names = m.attachedFiles.map((f) => f.split('/').pop()).join(', ')
       msgText += `\n[Attached: ${names}]`
     }
@@ -132,8 +185,8 @@ export function buildHistoryForAgent(chatroom: Chatroom, agentId: string, imageP
       role: m.senderId === agentId ? 'assistant' as const : 'user' as const,
       text: msgText,
       time: m.time,
-      ...(m.imagePath ? { imagePath: m.imagePath } : {}),
-      ...(m.attachedFiles ? { attachedFiles: m.attachedFiles } : {}),
+      ...(includeAttachments && m.imagePath ? { imagePath: m.imagePath } : {}),
+      ...(includeAttachments && m.attachedFiles ? { attachedFiles: m.attachedFiles } : {}),
     }
   })
   // Pass through imagePath/attachedFiles from the current message to the last history entry

package/src/lib/server/connectors/inbound-audio-transcription.test.ts

@@ -0,0 +1,191 @@
+import { afterEach, beforeEach, describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import fs from 'node:fs'
+import path from 'node:path'
+import { enrichInboundMessageWithAudioTranscript } from './inbound-audio-transcription'
+import type { InboundMessage } from './types'
+import { UPLOAD_DIR, loadSettings, saveSettings } from '../storage'
+
+const ENV_KEYS = [
+  'OPENAI_API_KEY',
+  'SWARMCLAW_OPENAI_STT_API_KEY',
+  'SWARMCLAW_OPENAI_STT_BASE_URL',
+  'SWARMCLAW_OPENAI_STT_MODEL',
+  'SWARMCLAW_ELEVENLABS_STT_MODEL',
+  'SWARMCLAW_CONNECTOR_AUDIO_TRANSCRIBE',
+  'SWARMCLAW_CONNECTOR_AUDIO_TRANSCRIBE_TIMEOUT_MS',
+  'SWARMCLAW_CONNECTOR_AUDIO_TRANSCRIBE_MAX_BYTES',
+  'ELEVENLABS_API_KEY',
+] as const
+
+type EnvSnapshot = Record<(typeof ENV_KEYS)[number], string | undefined>
+
+let originalFetch: typeof fetch
+let originalSettings: Record<string, unknown>
+let originalEnv: EnvSnapshot
+let tempFiles: string[] = []
+
+function setEnv(name: (typeof ENV_KEYS)[number], value: string | undefined): void {
+  if (value === undefined) delete process.env[name]
+  else process.env[name] = value
+}
+
+function createAudioFixture(name: string): string {
+  fs.mkdirSync(UPLOAD_DIR, { recursive: true })
+  const filePath = path.join(UPLOAD_DIR, `${Date.now()}-${name}.ogg`)
+  fs.writeFileSync(filePath, Buffer.from('voice-note-bytes'))
+  tempFiles.push(filePath)
+  return filePath
+}
+
+function buildInboundMessage(localPath: string, text = '(media message)'): InboundMessage {
+  return {
+    platform: 'whatsapp',
+    channelId: '15550001111@s.whatsapp.net',
+    senderId: '15550001111@s.whatsapp.net',
+    senderName: 'Tester',
+    text,
+    media: [{ type: 'audio', localPath, mimeType: 'audio/ogg', fileName: 'voice.ogg' }],
+  }
+}
+
+beforeEach(() => {
+  originalFetch = global.fetch
+  originalSettings = loadSettings()
+  originalEnv = Object.fromEntries(
+    ENV_KEYS.map((key) => [key, process.env[key]]),
+  ) as EnvSnapshot
+  tempFiles = []
+})
+
+afterEach(() => {
+  global.fetch = originalFetch
+  saveSettings(originalSettings)
+  for (const key of ENV_KEYS) setEnv(key, originalEnv[key])
+  for (const filePath of tempFiles) fs.rmSync(filePath, { force: true })
+})
+
+describe('enrichInboundMessageWithAudioTranscript', () => {
+  it('transcribes placeholder audio messages with OpenAI STT', async () => {
+    const audioPath = createAudioFixture('openai')
+    setEnv('OPENAI_API_KEY', 'openai-test-key')
+    setEnv('SWARMCLAW_CONNECTOR_AUDIO_TRANSCRIBE_TIMEOUT_MS', '5000')
+    saveSettings({
+      ...originalSettings,
+      elevenLabsEnabled: false,
+      elevenLabsApiKey: null,
+    })
+
+    let called = 0
+    global.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+      called += 1
+      const url = String(input)
+      assert.ok(url.endsWith('/audio/transcriptions'))
+      assert.equal(init?.method, 'POST')
+      assert.equal((init?.headers as Record<string, string>)?.Authorization, 'Bearer openai-test-key')
+      return new Response(JSON.stringify({ text: 'Please move this task to tomorrow morning.' }), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+      })
+    }) as typeof fetch
+
+    const inbound = buildInboundMessage(audioPath)
+    const enriched = await enrichInboundMessageWithAudioTranscript({ msg: inbound })
+
+    assert.equal(called, 1)
+    assert.equal(enriched.text, 'Please move this task to tomorrow morning.')
+  })
+
+  it('tries ElevenLabs first and falls back to OpenAI when ElevenLabs fails', async () => {
+    const audioPath = createAudioFixture('fallback')
+    setEnv('OPENAI_API_KEY', 'openai-fallback-key')
+    saveSettings({
+      ...originalSettings,
+      elevenLabsEnabled: true,
+      elevenLabsApiKey: 'el-test-key',
+    })
+
+    const calledUrls: string[] = []
+    global.fetch = (async (input: RequestInfo | URL) => {
+      const url = String(input)
+      calledUrls.push(url)
+      if (url.includes('api.elevenlabs.io/v1/speech-to-text')) {
+        return new Response(JSON.stringify({ detail: 'upstream unavailable' }), {
+          status: 503,
+          headers: { 'Content-Type': 'application/json' },
+        })
+      }
+      if (url.endsWith('/audio/transcriptions')) {
+        return new Response(JSON.stringify({ text: 'Fallback transcription succeeded.' }), {
+          status: 200,
+          headers: { 'Content-Type': 'application/json' },
+        })
+      }
+      return new Response('unexpected url', { status: 404 })
+    }) as typeof fetch
+
+    const inbound = buildInboundMessage(audioPath)
+    const enriched = await enrichInboundMessageWithAudioTranscript({ msg: inbound })
+
+    assert.equal(enriched.text, 'Fallback transcription succeeded.')
+    assert.equal(calledUrls.length, 2)
+    assert.ok(calledUrls[0].includes('api.elevenlabs.io/v1/speech-to-text'))
+    assert.ok(calledUrls[1].endsWith('/audio/transcriptions'))
+  })
+
+  it('skips transcription when the inbound message already has non-placeholder text', async () => {
+    const audioPath = createAudioFixture('skip')
+    setEnv('OPENAI_API_KEY', 'openai-test-key')
+
+    let called = false
+    global.fetch = (async () => {
+      called = true
+      return new Response(JSON.stringify({ text: 'should not be used' }), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+      })
+    }) as typeof fetch
+
+    const inbound = buildInboundMessage(audioPath, 'Already typed this manually')
+    const enriched = await enrichInboundMessageWithAudioTranscript({ msg: inbound })
+
+    assert.equal(enriched.text, 'Already typed this manually')
+    assert.equal(called, false)
+  })
+
+  it('returns a clear failure note when STT providers error out', async () => {
+    const audioPath = createAudioFixture('provider-error')
+    setEnv('OPENAI_API_KEY', 'openai-error-key')
+    saveSettings({
+      ...originalSettings,
+      elevenLabsEnabled: true,
+      elevenLabsApiKey: 'el-error-key',
+    })
+
+    global.fetch = (async () => {
+      return new Response(JSON.stringify({ error: 'upstream down' }), {
+        status: 500,
+        headers: { 'Content-Type': 'application/json' },
+      })
+    }) as typeof fetch
+
+    const inbound = buildInboundMessage(audioPath)
+    const enriched = await enrichInboundMessageWithAudioTranscript({ msg: inbound })
+
+    assert.ok(enriched.text.toLowerCase().includes('automatic transcription failed'))
+  })
+
+  it('returns a clear note when inbound audio cannot be loaded from disk', async () => {
+    const inbound: InboundMessage = {
+      platform: 'whatsapp',
+      channelId: '15550001111@s.whatsapp.net',
+      senderId: '15550001111@s.whatsapp.net',
+      senderName: 'Tester',
+      text: '(media message)',
+      media: [{ type: 'audio', localPath: '/tmp/nonexistent-voice-note.ogg', mimeType: 'audio/ogg', fileName: 'voice.ogg' }],
+    }
+
+    const enriched = await enrichInboundMessageWithAudioTranscript({ msg: inbound })
+    assert.ok(enriched.text.toLowerCase().includes('audio attachment could not be loaded'))
+  })
+})