@swarmclawai/swarmclaw 0.6.0 → 0.6.2

package/src/hooks/use-voice-conversation.ts

@@ -1,40 +1,68 @@
 'use client'
 
-import { useCallback, useRef, useState } from 'react'
+import { useCallback, useEffect, useRef, useState } from 'react'
 import { useContinuousSpeech } from './use-continuous-speech'
 import { SentenceAccumulator, AudioChunkQueue, fetchStreamTts } from '@/lib/tts-stream'
 import { useChatStore } from '@/stores/use-chat-store'
 
 export type VoiceConversationState = 'idle' | 'listening' | 'processing' | 'speaking'
 
+/** Max time to wait in 'processing' before falling back to listening (30s). */
+const PROCESSING_TIMEOUT_MS = 30_000
+
 export function useVoiceConversation() {
-  const [active, setActive] = useState(false)
   const [voiceState, setVoiceState] = useState<VoiceConversationState>('idle')
   const accumulatorRef = useRef<SentenceAccumulator | null>(null)
   const queueRef = useRef<AudioChunkQueue | null>(null)
+  const activeRef = useRef(false)
+  const processingTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+  const [resumeNeeded, setResumeNeeded] = useState(0)
   const sendMessage = useChatStore((s) => s.sendMessage)
 
+  const clearProcessingTimer = () => {
+    if (processingTimerRef.current) {
+      clearTimeout(processingTimerRef.current)
+      processingTimerRef.current = null
+    }
+  }
+
   const speech = useContinuousSpeech({
     onUtterance: useCallback((text: string) => {
       setVoiceState('processing')
-      // Send the transcribed text as a chat message
       sendMessage(text)
+      // Safety net: if no stream events arrive within timeout, resume listening
+      clearProcessingTimer()
+      processingTimerRef.current = setTimeout(() => {
+        if (activeRef.current) {
+          setVoiceState('listening')
+          setResumeNeeded((n) => n + 1)
+        }
+      }, PROCESSING_TIMEOUT_MS)
     }, [sendMessage]),
   })
 
+  // When resumeNeeded increments, call speech.resume
+  useEffect(() => {
+    if (resumeNeeded > 0) speech.resume()
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [resumeNeeded])
+
   // Called by the chat store's onStreamEvent callback
   const handleStreamEvent = useCallback((event: { t: string; text?: string }) => {
-    if (!active) return
+    if (!activeRef.current) return
 
     if (event.t === 'd' && event.text) {
+      clearProcessingTimer()
       setVoiceState('speaking')
       if (!accumulatorRef.current) {
         const queue = new AudioChunkQueue()
         queueRef.current = queue
         queue.onComplete = () => {
           // Resume listening after TTS playback finishes
-          setVoiceState('listening')
-          speech.resume()
+          if (activeRef.current) {
+            setVoiceState('listening')
+            speech.resume()
+          }
         }
         accumulatorRef.current = new SentenceAccumulator((sentence) => {
           queue.enqueue(fetchStreamTts(sentence))
@@ -42,16 +70,30 @@ export function useVoiceConversation() {
       }
       accumulatorRef.current.push(event.text)
     } else if (event.t === 'done') {
+      clearProcessingTimer()
       // Flush remaining text to TTS
       if (accumulatorRef.current) {
         accumulatorRef.current.flush()
         accumulatorRef.current = null
+      } else {
+        // No text was streamed (empty response or error) — resume listening
+        if (activeRef.current) {
+          setVoiceState('listening')
+          speech.resume()
+        }
+      }
+    } else if (event.t === 'err') {
+      // Error from the LLM — resume listening instead of staying stuck
+      clearProcessingTimer()
+      if (activeRef.current) {
+        setVoiceState('listening')
+        speech.resume()
       }
     }
-  }, [active, speech])
+  }, [speech])
 
   const start = useCallback(() => {
-    setActive(true)
+    activeRef.current = true
     setVoiceState('listening')
     // Register the stream event handler on the chat store
     useChatStore.setState({ onStreamEvent: handleStreamEvent, voiceConversationActive: true })
@@ -59,8 +101,9 @@ export function useVoiceConversation() {
   }, [speech, handleStreamEvent])
 
   const stop = useCallback(() => {
-    setActive(false)
+    activeRef.current = false
     setVoiceState('idle')
+    clearProcessingTimer()
     speech.stop()
     queueRef.current?.stop()
     queueRef.current = null
@@ -69,7 +112,7 @@ export function useVoiceConversation() {
   }, [speech])
 
   return {
-    active,
+    active: activeRef.current || voiceState !== 'idle',
     state: voiceState,
     interimText: speech.interimText,
     transcript: speech.transcript,

package/src/hooks/use-ws.ts

@@ -32,8 +32,10 @@ export function useWs(topic: string, handler: () => void, fallbackMs?: number) {
     let fallbackId: ReturnType<typeof setInterval> | null = null
     const cb = () => handlerRef.current()
 
-    // When page becomes visible again, fire an immediate refresh
-    if (isActive) {
+    // When page becomes visible again, fire an immediate refresh —
+    // but only for topics that use fallback polling (i.e. data-fetch topics).
+    // Event-only topics (like heartbeat pulses) should never fire from this effect.
+    if (isActive && fallbackMsRef.current && fallbackMsRef.current > 0) {
       cb()
     }
 

package/src/lib/providers/anthropic.ts

@@ -23,9 +23,9 @@ function fileToContentBlocks(filePath: string): any[] {
   return [{ type: 'text', text: `[Attached file: ${filePath.split('/').pop()}]` }]
 }
 
-export function streamAnthropicChat({ session, message, imagePath, apiKey, systemPrompt, write, active, loadHistory, onUsage }: StreamChatOptions): Promise<string> {
+export function streamAnthropicChat({ session, message, imagePath, imageUrl, apiKey, systemPrompt, write, active, loadHistory, onUsage }: StreamChatOptions): Promise<string> {
   return new Promise((resolve) => {
-    const messages = buildMessages(session, message, imagePath, loadHistory)
+    const messages = buildMessages(session, message, imagePath, loadHistory, imageUrl)
     const model = session.model || 'claude-sonnet-4-6'
     let usageInput = 0
     let usageOutput = 0
@@ -122,14 +122,19 @@ export function streamAnthropicChat({ session, message, imagePath, apiKey, syste
   })
 }
 
-function buildMessages(session: any, message: string, imagePath: string | undefined, loadHistory: (id: string) => any[]) {
+function urlToImageBlock(url: string): { type: string; source: { type: string; url: string } } {
+  return { type: 'image', source: { type: 'url', url } }
+}
+
+function buildMessages(session: any, message: string, imagePath: string | undefined, loadHistory: (id: string) => any[], imageUrl?: string) {
   const msgs: Array<{ role: string; content: any }> = []
 
   if (loadHistory) {
     const history = loadHistory(session.id).slice(-40)
     for (const m of history) {
-      if (m.role === 'user' && m.imagePath) {
-        const blocks = fileToContentBlocks(m.imagePath)
+      if (m.role === 'user' && (m.imagePath || m.imageUrl)) {
+        const blocks = m.imagePath ? fileToContentBlocks(m.imagePath) : []
+        if (m.imageUrl) blocks.push(urlToImageBlock(m.imageUrl))
         msgs.push({ role: 'user', content: [...blocks, { type: 'text', text: m.text }] })
       } else {
         msgs.push({ role: m.role, content: m.text })
@@ -138,8 +143,9 @@ function buildMessages(session: any, message: string, imagePath: string | undefi
   }
 
   // Current message with optional attachment
-  if (imagePath) {
-    const blocks = fileToContentBlocks(imagePath)
+  if (imagePath || imageUrl) {
+    const blocks = imagePath ? fileToContentBlocks(imagePath) : []
+    if (imageUrl) blocks.push(urlToImageBlock(imageUrl))
     msgs.push({ role: 'user', content: [...blocks, { type: 'text', text: message }] })
   } else {
     msgs.push({ role: 'user', content: message })

package/src/lib/providers/index.ts

@@ -22,6 +22,7 @@ export interface StreamChatOptions {
   session: any
   message: string
   imagePath?: string
+  imageUrl?: string
   apiKey?: string | null
   systemPrompt?: string
   write: (data: string) => void

package/src/lib/providers/openai.ts

@@ -43,9 +43,9 @@ async function fileToContentParts(filePath: string): Promise<any[]> {
   return [{ type: 'text', text: `[Attached file: ${name}]` }]
 }
 
-export function streamOpenAiChat({ session, message, imagePath, apiKey, systemPrompt, write, active, loadHistory, onUsage }: StreamChatOptions): Promise<string> {
+export function streamOpenAiChat({ session, message, imagePath, imageUrl, apiKey, systemPrompt, write, active, loadHistory, onUsage }: StreamChatOptions): Promise<string> {
   return new Promise(async (resolve) => {
-    const messages = await buildMessages(session, message, imagePath, systemPrompt, loadHistory)
+    const messages = await buildMessages(session, message, imagePath, systemPrompt, loadHistory, imageUrl)
     const model = session.model || 'gpt-4o'
 
     const payload = JSON.stringify({
@@ -163,7 +163,11 @@ export function streamOpenAiChat({ session, message, imagePath, apiKey, systemPr
   })
 }
 
-async function buildMessages(session: any, message: string, imagePath: string | undefined, systemPrompt: string | undefined, loadHistory: (id: string) => any[]) {
+function urlToImagePart(url: string): { type: string; image_url: { url: string; detail: string } } {
+  return { type: 'image_url', image_url: { url, detail: 'auto' } }
+}
+
+async function buildMessages(session: any, message: string, imagePath: string | undefined, systemPrompt: string | undefined, loadHistory: (id: string) => any[], imageUrl?: string) {
   const msgs: Array<{ role: string; content: any }> = []
 
   if (systemPrompt) {
@@ -173,8 +177,9 @@ async function buildMessages(session: any, message: string, imagePath: string |
   if (loadHistory) {
     const history = loadHistory(session.id).slice(-40)
     for (const m of history) {
-      if (m.role === 'user' && m.imagePath) {
-        const parts = await fileToContentParts(m.imagePath)
+      if (m.role === 'user' && (m.imagePath || m.imageUrl)) {
+        const parts = m.imagePath ? await fileToContentParts(m.imagePath) : []
+        if (m.imageUrl) parts.push(urlToImagePart(m.imageUrl))
         msgs.push({ role: 'user', content: [...parts, { type: 'text', text: m.text }] })
       } else {
         msgs.push({ role: m.role, content: m.text })
@@ -183,8 +188,9 @@ async function buildMessages(session: any, message: string, imagePath: string |
   }
 
   // Current message with optional attachment
-  if (imagePath) {
-    const parts = await fileToContentParts(imagePath)
+  if (imagePath || imageUrl) {
+    const parts = imagePath ? await fileToContentParts(imagePath) : []
+    if (imageUrl) parts.push(urlToImagePart(imageUrl))
     msgs.push({ role: 'user', content: [...parts, { type: 'text', text: message }] })
   } else {
     msgs.push({ role: 'user', content: message })

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

@@ -24,11 +24,20 @@ import { getMemoryDb } from './memory-db'
 import { routeTaskIntent } from './capability-router'
 import { notify } from './ws-hub'
 import { resolveConcreteToolPolicyBlock, resolveSessionToolPolicy } from './tool-capability-policy'
-import type { MessageToolEvent, SSEEvent, UsageRecord } from '@/types'
+import { buildCurrentDateTimePromptContext } from './prompt-runtime-context'
+import type { Message, MessageToolEvent, SSEEvent, UsageRecord } from '@/types'
 import { markProviderFailure, markProviderSuccess, rankDelegatesByHealth } from './provider-health'
 import { NON_LANGGRAPH_PROVIDER_IDS } from '@/lib/provider-sets'
 type DelegateTool = 'delegate_to_claude_code' | 'delegate_to_codex_cli' | 'delegate_to_opencode_cli'
 
+/** Slice history from the most recent context-clear marker forward */
+function applyContextClearBoundary(messages: Message[]): Message[] {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    if (messages[i].kind === 'context-clear') return messages.slice(i + 1)
+  }
+  return messages
+}
+
 interface SessionWithTools {
   tools?: string[] | null
 }
@@ -307,11 +316,11 @@ function buildAgentSystemPrompt(session: any): string | undefined {
   if (!session.agentId) return undefined
   const agents = loadAgents()
   const agent = agents[session.agentId]
-  if (!agent?.systemPrompt && !agent?.soul) return undefined
 
   const settings = loadSettings()
   const parts: string[] = []
   if (settings.userPrompt) parts.push(settings.userPrompt)
+  parts.push(buildCurrentDateTimePromptContext())
   if (agent.soul) parts.push(agent.soul)
   if (agent.systemPrompt) parts.push(agent.systemPrompt)
   if (agent.skillIds?.length) {
@@ -321,6 +330,7 @@ function buildAgentSystemPrompt(session: any): string | undefined {
       if (skill?.content) parts.push(`## Skill: ${skill.name}\n${skill.content}`)
     }
   }
+  if (!parts.length) return undefined
   return parts.join('\n\n')
 }
 
@@ -354,13 +364,13 @@ function stripMarkupForHeartbeat(text: string): string {
 const HEARTBEAT_OK_RE = /HEARTBEAT_OK[^\w]{0,4}$/
 const NO_MESSAGE_RE = /NO_MESSAGE[^\w]{0,4}$/
 
-function classifyHeartbeatResponse(text: string, ackMaxChars: number): 'suppress' | 'strip' | 'keep' {
+function classifyHeartbeatResponse(text: string, ackMaxChars: number, hadToolCalls: boolean): 'suppress' | 'strip' | 'keep' {
   const cleaned = stripMarkupForHeartbeat(text)
   if (cleaned === 'HEARTBEAT_OK' || cleaned === 'NO_MESSAGE') return 'suppress'
   if (HEARTBEAT_OK_RE.test(cleaned) || NO_MESSAGE_RE.test(cleaned)) return 'suppress'
   const stripped = cleaned.replace(/HEARTBEAT_OK/gi, '').replace(/NO_MESSAGE/gi, '').trim()
   if (!stripped) return 'suppress'
-  if (stripped.length <= ackMaxChars) return 'suppress'
+  if (!hadToolCalls && stripped.length <= ackMaxChars) return 'suppress'
   return stripped.length < cleaned.length ? 'strip' : 'keep'
 }
 
@@ -566,6 +576,7 @@ export async function executeSessionChatTurn(input: ExecuteChatTurnInput): Promi
   const toolEvents: MessageToolEvent[] = []
   const streamErrors: string[] = []
 
+  let thinkingText = ''
   const emit = (ev: SSEEvent) => {
     if (ev.t === 'err' && typeof ev.text === 'string') {
       const trimmed = ev.text.trim()
@@ -574,6 +585,9 @@ export async function executeSessionChatTurn(input: ExecuteChatTurnInput): Promi
         if (streamErrors.length > 8) streamErrors.shift()
       }
     }
+    if (ev.t === 'thinking' && ev.text) {
+      thinkingText += ev.text
+    }
     collectToolEvent(ev, toolEvents)
     onEvent?.(ev)
   }
@@ -608,9 +622,12 @@ export async function executeSessionChatTurn(input: ExecuteChatTurnInput): Promi
   const hasTools = !!sessionForRun.tools?.length && !NON_LANGGRAPH_PROVIDER_IDS.has(providerType)
 
   try {
-    // Heartbeat runs are self-contained — skip conversation history to avoid
-    // blowing past the context window on long-lived sessions.
-    const heartbeatHistory = isAutoRunNoHistory ? [] : undefined
+    // Heartbeat runs get a small tail of recent messages so the agent can see
+    // prior findings and avoid repeating the same searches. Full history is
+    // skipped to avoid blowing the context window on long-lived sessions.
+    const heartbeatHistory = isAutoRunNoHistory
+      ? getSessionMessages(sessionId).slice(-6)
+      : undefined
 
     console.log(`[chat-execution] provider=${providerType}, hasTools=${hasTools}, imagePath=${imagePath || 'none'}, attachedFiles=${attachedFiles?.length || 0}, tools=${(sessionForRun.tools || []).length}`)
 
@@ -623,7 +640,7 @@ export async function executeSessionChatTurn(input: ExecuteChatTurnInput): Promi
           apiKey,
           systemPrompt,
           write: (raw) => parseAndEmit(raw),
-          history: heartbeatHistory ?? getSessionMessages(sessionId),
+          history: heartbeatHistory ?? applyContextClearBoundary(getSessionMessages(sessionId)),
           signal: abortController.signal,
         })).fullText
       : await provider.handler.streamChat({
@@ -634,7 +651,7 @@ export async function executeSessionChatTurn(input: ExecuteChatTurnInput): Promi
           systemPrompt,
           write: (raw: string) => parseAndEmit(raw),
           active,
-          loadHistory: isAutoRunNoHistory ? () => [] : getSessionMessages,
+          loadHistory: isAutoRunNoHistory ? () => getSessionMessages(sessionId).slice(-6) : (sid: string) => applyContextClearBoundary(getSessionMessages(sid)),
           onUsage: (u) => { directUsage.inputTokens = u.inputTokens; directUsage.outputTokens = u.outputTokens; directUsage.received = true },
         })
   } catch (err: any) {
@@ -723,7 +740,13 @@ export async function executeSessionChatTurn(input: ExecuteChatTurnInput): Promi
       const toolOutput = await selectedTool.invoke(args)
       const outputText = typeof toolOutput === 'string' ? toolOutput : JSON.stringify(toolOutput)
       emit({ t: 'tool_result', toolName, toolOutput: outputText })
-      if (outputText?.trim()) fullResponse = outputText.trim()
+      // Don't overwrite fullResponse with raw tool output — it's already captured
+      // in toolEvents. Only set a brief notice when the LLM produced no text,
+      // so the message bubble isn't empty.
+      if (!fullResponse.trim() && outputText?.trim()) {
+        const label = toolName.replace(/_/g, ' ')
+        fullResponse = `Used **${label}** — see tool output above for details.`
+      }
       calledNames.add(toolName)
       return true
     } catch (forceErr: any) {
@@ -869,7 +892,7 @@ export async function executeSessionChatTurn(input: ExecuteChatTurnInput): Promi
   const heartbeatConfig = input.heartbeatConfig
   let heartbeatClassification: 'suppress' | 'strip' | 'keep' | null = null
   if (isHeartbeatRun && textForPersistence.length > 0) {
-    heartbeatClassification = classifyHeartbeatResponse(textForPersistence, heartbeatConfig?.ackMaxChars ?? 300)
+    heartbeatClassification = classifyHeartbeatResponse(textForPersistence, heartbeatConfig?.ackMaxChars ?? 300, toolEvents.length > 0)
   }
 
   // Emit WS notification for every heartbeat completion so UI can show pulse
@@ -924,6 +947,7 @@ export async function executeSessionChatTurn(input: ExecuteChatTurnInput): Promi
         role: 'assistant',
         text: persistedText,
         time: Date.now(),
+        thinking: thinkingText || undefined,
         toolEvents: toolEvents.length ? toolEvents : undefined,
         kind: persistedKind,
       })
@@ -964,6 +988,22 @@ export async function executeSessionChatTurn(input: ExecuteChatTurnInput): Promi
           // Best effort — connector manager may not be loaded
         }
       }
+
+      // Auto-discover connectors linked to this agent when no explicit target is set
+      if (isHeartbeatRun && !heartbeatConfig?.target && heartbeatConfig?.showAlerts !== false && session.agentId) {
+        try {
+          // eslint-disable-next-line @typescript-eslint/no-require-imports
+          const { listRunningConnectors: listRunning, sendConnectorMessage: sendMsg } = require('./connectors/manager')
+          const agentConnectors = listRunning().filter((c: { agentId: string | null; recentChannelId: string | null; supportsSend: boolean }) =>
+            c.agentId === session.agentId && c.recentChannelId && c.supportsSend
+          )
+          for (const conn of agentConnectors) {
+            sendMsg({ connectorId: conn.id, channelId: conn.recentChannelId, text: persistedText }).catch(() => {})
+          }
+        } catch {
+          // Best effort — connector manager may not be loaded
+        }
+      }
     }
 
     const autoMemoryEligible = shouldStoreAutoMemoryNote({

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

@@ -0,0 +1,146 @@
+import { loadSettings, loadSkills, loadCredentials, decryptKey } from './storage'
+import { buildCurrentDateTimePromptContext } from './prompt-runtime-context'
+import type { Chatroom, Agent, Session, Message } from '@/types'
+
+/** Resolve API key from an agent's credentialId */
+export function resolveApiKey(credentialId: string | null | undefined): string | null {
+  if (!credentialId) return null
+  const creds = loadCredentials()
+  const cred = creds[credentialId]
+  if (!cred?.encryptedKey) return null
+  try { return decryptKey(cred.encryptedKey) } catch { return null }
+}
+
+/** 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 mentioned: string[] = []
+  let match: RegExpExecArray | null
+  while ((match = mentionPattern.exec(text)) !== null) {
+    const name = match[1].toLowerCase()
+    for (const id of memberIds) {
+      const agent = agents[id]
+      if (agent && agent.name.toLowerCase().replace(/\s+/g, '') === name) {
+        if (!mentioned.includes(id)) mentioned.push(id)
+      }
+    }
+  }
+  return mentioned
+}
+
+/** 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]
+  const selfName = selfAgent?.name || agentId
+
+  // Build team profiles with capabilities
+  const teamProfiles = chatroom.agentIds
+    .filter((id) => id !== agentId)
+    .map((id) => {
+      const a = agents[id]
+      if (!a) return null
+      const tools = a.tools?.length ? `Tools: ${a.tools.join(', ')}` : 'No specialized tools'
+      const desc = a.description || a.soul || 'No description'
+      return `- **${a.name}**: ${desc}\n  ${tools}`
+    })
+    .filter(Boolean)
+    .join('\n')
+
+  const recentMessages = chatroom.messages.slice(-30).map((m) => {
+    return `[${m.senderName}]: ${m.text}`
+  }).join('\n')
+
+  const memberCount = chatroom.agentIds.length
+  const otherNames = chatroom.agentIds
+    .filter((id) => id !== agentId)
+    .map((id) => agents[id]?.name)
+    .filter(Boolean)
+
+  return [
+    `## Chatroom Context`,
+    `You are **${selfName}** in a group chatroom called "${chatroom.name}" with ${memberCount} participants (you, ${otherNames.join(', ') || 'others'}, and the user).`,
+    selfAgent?.description ? `Your role: ${selfAgent.description}` : '',
+    selfAgent?.tools?.length ? `Your available tools: ${selfAgent.tools.join(', ')}` : '',
+    '',
+    '## Team Members',
+    teamProfiles || '(no other agents)',
+    '',
+    '## How to Behave in This Chatroom',
+    '- **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.',
+    '- **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.',
+    '- **Read the room.** Look at recent messages to understand context. Don\'t repeat what others already said.',
+    '',
+    '## Recent Messages',
+    recentMessages || '(no messages yet)',
+  ].filter((line) => line !== undefined).join('\n')
+}
+
+/** Build a synthetic session object for an agent in a chatroom */
+export function buildSyntheticSession(agent: Agent, chatroomId: string): Session {
+  return {
+    id: `chatroom-${chatroomId}-${agent.id}`,
+    name: `Chatroom session for ${agent.name}`,
+    cwd: process.cwd(),
+    user: 'chatroom',
+    provider: agent.provider,
+    model: agent.model,
+    credentialId: agent.credentialId ?? null,
+    fallbackCredentialIds: agent.fallbackCredentialIds,
+    apiEndpoint: agent.apiEndpoint ?? null,
+    claudeSessionId: null,
+    messages: [],
+    createdAt: Date.now(),
+    lastActiveAt: Date.now(),
+    tools: agent.tools || [],
+    agentId: agent.id,
+  }
+}
+
+/** Build agent's system prompt including skills */
+export function buildAgentSystemPromptForChatroom(agent: Agent): string {
+  const settings = loadSettings()
+  const parts: string[] = []
+  if (settings.userPrompt) parts.push(settings.userPrompt)
+  parts.push(buildCurrentDateTimePromptContext())
+  if (agent.soul) parts.push(agent.soul)
+  if (agent.systemPrompt) parts.push(agent.systemPrompt)
+  if (agent.skillIds?.length) {
+    const allSkills = loadSkills()
+    for (const skillId of agent.skillIds) {
+      const skill = allSkills[skillId]
+      if (skill?.content) parts.push(`## Skill: ${skill.name}\n${skill.content}`)
+    }
+  }
+  return parts.join('\n\n')
+}
+
+/** 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) => {
+    let msgText = `[${m.senderName}]: ${m.text}`
+    // Include attachment info in history
+    if (m.attachedFiles?.length) {
+      const names = m.attachedFiles.map((f) => f.split('/').pop()).join(', ')
+      msgText += `\n[Attached: ${names}]`
+    }
+    return {
+      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 } : {}),
+    }
+  })
+  // Pass through imagePath/attachedFiles from the current message to the last history entry
+  if (history.length > 0 && (imagePath || attachedFiles)) {
+    const last = history[history.length - 1]
+    if (imagePath && !last.imagePath) last.imagePath = imagePath
+    if (attachedFiles && !last.attachedFiles) last.attachedFiles = attachedFiles
+  }
+  return history
+}