@swarmclawai/swarmclaw 0.5.3 → 0.6.2

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

@@ -111,3 +111,128 @@ export function getProviderHealthSnapshot(): Record<string, ProviderHealthState
   return out
 }
 
+// ---------------------------------------------------------------------------
+// Lightweight provider ping functions (extracted from check-provider/route.ts)
+// ---------------------------------------------------------------------------
+
+const PING_TIMEOUT_MS = 8_000
+
+async function parseErrorMessage(res: Response, fallback: string): Promise<string> {
+  const text = await res.text().catch(() => '')
+  if (!text) return fallback
+  try {
+    const parsed = JSON.parse(text)
+    if (typeof parsed?.error?.message === 'string' && parsed.error.message.trim()) return parsed.error.message.trim()
+    if (typeof parsed?.error === 'string' && parsed.error.trim()) return parsed.error.trim()
+    if (typeof parsed?.message === 'string' && parsed.message.trim()) return parsed.message.trim()
+    if (typeof parsed?.detail === 'string' && parsed.detail.trim()) return parsed.detail.trim()
+  } catch { /* non-JSON */ }
+  return text.slice(0, 300).trim() || fallback
+}
+
+export const OPENAI_COMPATIBLE_DEFAULTS: Record<string, { name: string; defaultEndpoint: string }> = {
+  openai: { name: 'OpenAI', defaultEndpoint: 'https://api.openai.com/v1' },
+  google: { name: 'Google Gemini', defaultEndpoint: 'https://generativelanguage.googleapis.com/v1beta/openai' },
+  deepseek: { name: 'DeepSeek', defaultEndpoint: 'https://api.deepseek.com/v1' },
+  groq: { name: 'Groq', defaultEndpoint: 'https://api.groq.com/openai/v1' },
+  together: { name: 'Together AI', defaultEndpoint: 'https://api.together.xyz/v1' },
+  mistral: { name: 'Mistral AI', defaultEndpoint: 'https://api.mistral.ai/v1' },
+  xai: { name: 'xAI (Grok)', defaultEndpoint: 'https://api.x.ai/v1' },
+  fireworks: { name: 'Fireworks AI', defaultEndpoint: 'https://api.fireworks.ai/inference/v1' },
+}
+
+export async function pingOpenAiCompatible(
+  apiKey: string,
+  endpoint: string,
+): Promise<{ ok: boolean; message: string }> {
+  const normalizedEndpoint = endpoint.replace(/\/+$/, '')
+  const res = await fetch(`${normalizedEndpoint}/models`, {
+    headers: { authorization: `Bearer ${apiKey}` },
+    signal: AbortSignal.timeout(PING_TIMEOUT_MS),
+    cache: 'no-store',
+  })
+  if (!res.ok) {
+    const detail = await parseErrorMessage(res, `Provider returned ${res.status}.`)
+    return { ok: false, message: detail }
+  }
+  return { ok: true, message: 'Connected.' }
+}
+
+export async function pingAnthropic(apiKey: string): Promise<{ ok: boolean; message: string }> {
+  const res = await fetch('https://api.anthropic.com/v1/models', {
+    headers: {
+      'x-api-key': apiKey,
+      'anthropic-version': '2023-06-01',
+    },
+    signal: AbortSignal.timeout(PING_TIMEOUT_MS),
+    cache: 'no-store',
+  })
+  if (!res.ok) {
+    const detail = await parseErrorMessage(res, `Anthropic returned ${res.status}.`)
+    return { ok: false, message: detail }
+  }
+  return { ok: true, message: 'Connected to Anthropic.' }
+}
+
+export async function pingOllama(endpoint: string): Promise<{ ok: boolean; message: string }> {
+  const normalizedEndpoint = (endpoint || 'http://localhost:11434').replace(/\/+$/, '')
+  const res = await fetch(`${normalizedEndpoint}/api/tags`, {
+    signal: AbortSignal.timeout(PING_TIMEOUT_MS),
+    cache: 'no-store',
+  })
+  if (!res.ok) {
+    const detail = await parseErrorMessage(res, `Ollama returned ${res.status}.`)
+    return { ok: false, message: detail }
+  }
+  return { ok: true, message: 'Connected to Ollama.' }
+}
+
+export async function pingOpenClaw(
+  apiKey: string | undefined,
+  endpoint: string,
+): Promise<{ ok: boolean; message: string }> {
+  const { wsConnect } = await import('@/lib/providers/openclaw')
+  let url = (endpoint || 'http://localhost:18789').replace(/\/+$/, '')
+  if (!/^(https?|wss?):\/\//i.test(url)) url = `http://${url}`
+  const wsUrl = url.replace(/^http:/i, 'ws:').replace(/^https:/i, 'wss:')
+  const result = await wsConnect(wsUrl, apiKey || undefined, true, PING_TIMEOUT_MS)
+  if (result.ws) try { result.ws.close() } catch { /* ignore */ }
+  return { ok: result.ok, message: result.ok ? 'Connected to OpenClaw.' : result.message }
+}
+
+/**
+ * Ping a provider to check reachability. Returns `{ ok, message }`.
+ * Skips CLI-based providers (claude-cli, codex-cli, opencode-cli) — returns ok.
+ */
+export async function pingProvider(
+  provider: string,
+  apiKey: string | undefined,
+  endpoint: string | undefined,
+): Promise<{ ok: boolean; message: string }> {
+  const CLI_PROVIDERS = ['claude-cli', 'codex-cli', 'opencode-cli']
+  if (CLI_PROVIDERS.includes(provider)) return { ok: true, message: 'CLI provider — skipped.' }
+
+  try {
+    if (provider === 'anthropic') {
+      if (!apiKey) return { ok: false, message: 'No API key configured.' }
+      return await pingAnthropic(apiKey)
+    }
+    if (provider === 'ollama') {
+      return await pingOllama(endpoint || 'http://localhost:11434')
+    }
+    if (provider === 'openclaw') {
+      return await pingOpenClaw(apiKey, endpoint || 'http://localhost:18789')
+    }
+    // OpenAI-compatible providers (openai, google, deepseek, groq, together, mistral, xai, fireworks, custom)
+    const defaults = OPENAI_COMPATIBLE_DEFAULTS[provider]
+    const resolvedEndpoint = endpoint || defaults?.defaultEndpoint
+    if (!resolvedEndpoint) return { ok: false, message: `No endpoint for provider "${provider}".` }
+    if (!apiKey) return { ok: false, message: 'No API key configured.' }
+    return await pingOpenAiCompatible(apiKey, resolvedEndpoint)
+  } catch (err: unknown) {
+    const msg = err instanceof Error && err.name === 'TimeoutError'
+      ? 'Connection timed out.'
+      : (err instanceof Error ? err.message : String(err))
+    return { ok: false, message: msg }
+  }
+}

package/src/lib/server/queue.ts

@@ -12,13 +12,14 @@ import { getCheckpointSaver } from './langgraph-checkpoint'
 import { isProtectedMainSession } from './main-session'
 import type { Agent, BoardTask, Message } from '@/types'
 
-let processing = false
+// HMR-safe: pin processing flag to globalThis so hot reloads don't reset it
+const _queueState = ((globalThis as Record<string, unknown>).__swarmclaw_queue__ ??= { processing: false, pendingKick: false }) as { processing: boolean; pendingKick: boolean }
 
 interface SessionMessageLike {
   role?: string
   text?: string
   time?: number
-  kind?: 'chat' | 'heartbeat' | 'system'
+  kind?: 'chat' | 'heartbeat' | 'system' | 'context-clear'
   toolEvents?: Array<{ name?: string; output?: string }>
 }
 
@@ -279,19 +280,44 @@ function notifyAgentThreadTaskResult(task: BoardTask): void {
     changed = true
   }
 
-  // 2. If delegated, push to delegating agent's thread
+  // 2. If delegated, push to delegating agent's thread AND active chat sessions
   const delegatedBy = (task as unknown as Record<string, unknown>).delegatedByAgentId
   if (typeof delegatedBy === 'string' && delegatedBy !== task.agentId) {
     const delegator = agents[delegatedBy]
+    const agentName = agent?.name || task.agentId
+    const delegationBody = buildResultBlock(`Delegated task ${statusLabel}: **${taskLink}** (by ${agentName})`)
+
+    // Push to delegating agent's thread
     if (delegator?.threadSessionId && sessions[delegator.threadSessionId]) {
       const thread = sessions[delegator.threadSessionId]
       if (!Array.isArray(thread.messages)) thread.messages = []
-      const agentName = agent?.name || task.agentId
-      const body = buildResultBlock(`Delegated task ${statusLabel}: **${taskLink}** (by ${agentName})`)
-      thread.messages.push(buildMsg(body))
+      thread.messages.push(buildMsg(delegationBody))
       thread.lastActiveAt = now
       changed = true
     }
+
+    // Push to delegating agent's active user-facing chat sessions
+    // so the result is visible in the chat the user is looking at
+    if (delegator) {
+      for (const session of Object.values(sessions)) {
+        if (!session || session.agentId !== delegatedBy) continue
+        // Skip thread sessions and orchestrated/subagent sessions
+        if (session.id === delegator.threadSessionId) continue
+        if (session.sessionType === 'orchestrated') continue
+        // Only push to recently-active sessions (within last 30 minutes)
+        const lastActive = typeof session.lastActiveAt === 'number' ? session.lastActiveAt : 0
+        if (now - lastActive > 30 * 60_000) continue
+        if (!Array.isArray(session.messages)) session.messages = []
+        // Avoid duplicate push
+        const lastMsg = session.messages.at(-1)
+        if (lastMsg?.text === delegationBody && typeof lastMsg?.time === 'number' && now - lastMsg.time < 30_000) continue
+        session.messages.push(buildMsg(delegationBody))
+        session.lastActiveAt = now
+        changed = true
+        // Notify the specific session's message topic for real-time UI update
+        notify(`messages:${session.id}`)
+      }
+    }
   }
 
   if (changed) saveSessions(sessions)
@@ -330,6 +356,10 @@ export function enqueueTask(taskId: string) {
     text: `Task queued: "${task.title}" (${task.id})`,
   })
 
+  // If processNext is already running, mark a pending kick so it re-enters after finishing
+  if (_queueState.processing) {
+    _queueState.pendingKick = true
+  }
   // Delay before kicking worker so UI shows the queued state
   setTimeout(() => processNext(), 2000)
 }
@@ -467,8 +497,8 @@ function dequeueNextRunnableTask(queue: string[], tasks: Record<string, BoardTas
 }
 
 export async function processNext() {
-  if (processing) return
-  processing = true
+  if (_queueState.processing) return
+  _queueState.processing = true
 
   try {
     // Recover orphaned tasks: status is 'queued' but missing from the queue array
@@ -618,10 +648,21 @@ export async function processNext() {
       // Save initial assistant message so user sees context when opening the session
       const sessions = loadSessions()
       if (sessions[sessionId]) {
+        const isDelegation = (task as unknown as Record<string, unknown>).sourceType === 'delegation'
+        let initialText: string
+        if (isDelegation) {
+          const delegatorId = (task as unknown as Record<string, unknown>).delegatedByAgentId as string | undefined
+          const delegator = delegatorId ? agents[delegatorId] : null
+          const prefix = `[delegation-source:${delegatorId || ''}:${delegator?.name || 'Agent'}:${delegator?.avatarSeed || ''}]`
+          initialText = `${prefix}\nDelegated by **${delegator?.name || 'another agent'}** | [${task.title}](#task:${task.id})\n\n${task.description || ''}\n\nWorking directory: \`${taskCwd}\`\n\nI'll begin working on this now.`
+        } else {
+          initialText = `Starting task: **${task.title}**\n\n${task.description || ''}\n\nWorking directory: \`${taskCwd}\`\n\nI'll begin working on this now.`
+        }
         sessions[sessionId].messages.push({
           role: 'assistant',
-          text: `Starting task: **${task.title}**\n\n${task.description || ''}\n\nWorking directory: \`${taskCwd}\`\n\nI'll begin working on this now.`,
+          text: initialText,
           time: Date.now(),
+          ...(isDelegation ? { kind: 'system' as const } : {}),
         })
         saveSessions(sessions)
       }
@@ -805,7 +846,12 @@ export async function processNext() {
       }
     }
   } finally {
-    processing = false
+    _queueState.processing = false
+    // If tasks were enqueued while we were processing, kick another round
+    if (_queueState.pendingKick) {
+      _queueState.pendingKick = false
+      setTimeout(() => processNext(), 500)
+    }
   }
 }
 

package/src/lib/server/scheduler.ts

@@ -4,6 +4,8 @@ import { enqueueTask } from './queue'
 import { CronExpressionParser } from 'cron-parser'
 import { pushMainLoopEventToMainSessions } from './main-agent-loop'
 import { getScheduleSignatureKey } from '@/lib/schedule-dedupe'
+import { enqueueSystemEvent } from './system-events'
+import { requestHeartbeatNow } from './heartbeat-wake'
 
 const TICK_INTERVAL = 60_000 // 60 seconds
 let intervalId: ReturnType<typeof setInterval> | null = null
@@ -192,5 +194,11 @@ async function tick() {
       type: 'schedule_fired',
       text: `Schedule fired: "${schedule.name}" (${schedule.id}) run #${schedule.runNumber} — task ${taskId}`,
     })
+
+    // Enqueue system event + heartbeat wake for the schedule's agent
+    if (schedule.createdInSessionId) {
+      enqueueSystemEvent(schedule.createdInSessionId, `Schedule triggered: ${schedule.name}`)
+    }
+    requestHeartbeatNow({ agentId: schedule.agentId, reason: 'schedule' })
   }
 }

package/src/lib/server/session-run-manager.ts

@@ -37,6 +37,7 @@ interface QueueEntry {
   maxRuntimeMs?: number
   modelOverride?: string
   heartbeatConfig?: { ackMaxChars: number; showOk: boolean; showAlerts: boolean; target: string | null }
+  replyToId?: string
   resolve: (value: ExecuteChatTurnResult) => void
   reject: (error: Error) => void
   promise: Promise<ExecuteChatTurnResult>
@@ -245,6 +246,7 @@ async function drainExecution(executionKey: string): Promise<void> {
       onEvent: (event) => emitToSubscribers(next, event),
       modelOverride: next.modelOverride,
       heartbeatConfig: next.heartbeatConfig,
+      replyToId: next.replyToId,
     })
 
     const failed = !!result.error
@@ -344,6 +346,7 @@ export interface EnqueueSessionRunInput {
   maxRuntimeMs?: number
   modelOverride?: string
   heartbeatConfig?: { ackMaxChars: number; showOk: boolean; showAlerts: boolean; target: string | null }
+  replyToId?: string
 }
 
 export interface EnqueueSessionRunResult {
@@ -454,6 +457,7 @@ export function enqueueSessionRun(input: EnqueueSessionRunInput): EnqueueSession
     maxRuntimeMs: effectiveMaxRuntimeMs > 0 ? effectiveMaxRuntimeMs : undefined,
     modelOverride: input.modelOverride,
     heartbeatConfig: input.heartbeatConfig,
+    replyToId: input.replyToId,
     resolve,
     reject,
     promise,

package/src/lib/server/session-tools/canvas.ts

@@ -0,0 +1,67 @@
+import { z } from 'zod'
+import { tool, type StructuredToolInterface } from '@langchain/core/tools'
+import { loadSessions, saveSessions } from '../storage'
+import { notify } from '../ws-hub'
+import type { ToolBuildContext } from './context'
+
+export function buildCanvasTools(bctx: ToolBuildContext): StructuredToolInterface[] {
+  const { ctx, hasTool } = bctx
+  if (!hasTool('canvas')) return []
+
+  return [
+    tool(
+      async ({ action, content }) => {
+        try {
+          const sessionId = ctx?.sessionId
+          if (!sessionId) return 'Error: no active session for canvas.'
+
+          const sessions = loadSessions()
+          const session = sessions[sessionId]
+          if (!session) return 'Error: session not found.'
+
+          if (action === 'present') {
+            if (!content) return 'Error: content is required for present action.'
+            ;(session as Record<string, unknown>).canvasContent = content
+            session.lastActiveAt = Date.now()
+            sessions[sessionId] = session
+            saveSessions(sessions)
+            notify(`canvas:${sessionId}`)
+            return JSON.stringify({ ok: true, action: 'present', contentLength: content.length })
+          }
+
+          if (action === 'hide') {
+            ;(session as Record<string, unknown>).canvasContent = null
+            session.lastActiveAt = Date.now()
+            sessions[sessionId] = session
+            saveSessions(sessions)
+            notify(`canvas:${sessionId}`)
+            return JSON.stringify({ ok: true, action: 'hide' })
+          }
+
+          if (action === 'snapshot') {
+            const current = (session as Record<string, unknown>).canvasContent
+            return JSON.stringify({
+              ok: true,
+              action: 'snapshot',
+              hasContent: !!current,
+              contentLength: typeof current === 'string' ? current.length : 0,
+              preview: typeof current === 'string' ? current.slice(0, 500) : null,
+            })
+          }
+
+          return `Unknown canvas action "${action}". Valid: present, hide, snapshot`
+        } catch (err: unknown) {
+          return `Error: ${err instanceof Error ? err.message : String(err)}`
+        }
+      },
+      {
+        name: 'canvas',
+        description: 'Present live HTML/CSS/JS content to the user in an interactive canvas panel. Use "present" to show content, "hide" to dismiss, "snapshot" to check current state. The canvas renders in a sandboxed iframe alongside the chat.',
+        schema: z.object({
+          action: z.enum(['present', 'hide', 'snapshot']).describe('Canvas action to perform'),
+          content: z.string().optional().describe('HTML content to render (required for "present"). Can include inline CSS and JS.'),
+        }),
+      },
+    ),
+  ]
+}

package/src/lib/server/session-tools/chatroom.ts

@@ -0,0 +1,136 @@
+import { z } from 'zod'
+import { tool, type StructuredToolInterface } from '@langchain/core/tools'
+import { loadChatrooms, saveChatrooms, loadAgents } from '../storage'
+import { genId } from '@/lib/id'
+import { notify } from '../ws-hub'
+import type { ToolBuildContext } from './context'
+import type { Chatroom } from '@/types'
+
+export function buildChatroomTools(bctx: ToolBuildContext): StructuredToolInterface[] {
+  const tools: StructuredToolInterface[] = []
+  const { hasTool } = bctx
+
+  if (hasTool('manage_chatrooms')) {
+    tools.push(
+      tool(
+        async ({ action, chatroomId, name, description, agentIds, agentId, message }) => {
+          try {
+            const chatrooms = loadChatrooms() as Record<string, Chatroom>
+
+            if (action === 'list_chatrooms') {
+              const list = Object.values(chatrooms).map((cr) => ({
+                id: cr.id,
+                name: cr.name,
+                description: cr.description,
+                memberCount: cr.agentIds.length,
+                messageCount: cr.messages.length,
+              }))
+              return JSON.stringify(list)
+            }
+
+            if (action === 'create_chatroom') {
+              const id = genId()
+              const agents = loadAgents()
+              const validAgentIds = (agentIds || []).filter((aid: string) => agents[aid])
+              const chatroom: Chatroom = {
+                id,
+                name: name || 'New Chatroom',
+                description: description || '',
+                agentIds: validAgentIds,
+                messages: [],
+                createdAt: Date.now(),
+                updatedAt: Date.now(),
+              }
+              chatrooms[id] = chatroom
+              saveChatrooms(chatrooms)
+              notify('chatrooms')
+              return JSON.stringify({ ok: true, chatroom: { id, name: chatroom.name, agentIds: validAgentIds } })
+            }
+
+            if (!chatroomId) return 'Error: chatroomId is required for this action.'
+            const chatroom = chatrooms[chatroomId]
+            if (!chatroom) return `Error: chatroom not found: ${chatroomId}`
+
+            if (action === 'add_agent') {
+              if (!agentId) return 'Error: agentId is required.'
+              const agents = loadAgents()
+              if (!agents[agentId]) return `Error: agent not found: ${agentId}`
+              if (!chatroom.agentIds.includes(agentId)) {
+                chatroom.agentIds.push(agentId)
+                chatroom.updatedAt = Date.now()
+                chatrooms[chatroomId] = chatroom
+                saveChatrooms(chatrooms)
+                notify('chatrooms')
+                notify(`chatroom:${chatroomId}`)
+              }
+              return JSON.stringify({ ok: true, agentIds: chatroom.agentIds })
+            }
+
+            if (action === 'remove_agent') {
+              if (!agentId) return 'Error: agentId is required.'
+              chatroom.agentIds = chatroom.agentIds.filter((id: string) => id !== agentId)
+              chatroom.updatedAt = Date.now()
+              chatrooms[chatroomId] = chatroom
+              saveChatrooms(chatrooms)
+              notify('chatrooms')
+              notify(`chatroom:${chatroomId}`)
+              return JSON.stringify({ ok: true, agentIds: chatroom.agentIds })
+            }
+
+            if (action === 'list_members') {
+              const agents = loadAgents()
+              const members = chatroom.agentIds.map((id: string) => {
+                const agent = agents[id]
+                return agent ? { id, name: agent.name, description: agent.description } : { id, name: 'Unknown' }
+              })
+              return JSON.stringify(members)
+            }
+
+            if (action === 'send_message') {
+              if (!message) return 'Error: message is required.'
+              const msgId = genId()
+              const senderName = bctx.ctx?.agentId
+                ? (loadAgents()[bctx.ctx.agentId]?.name || 'Agent')
+                : 'Agent'
+              chatroom.messages.push({
+                id: msgId,
+                senderId: bctx.ctx?.agentId || 'agent',
+                senderName,
+                role: 'assistant' as const,
+                text: message,
+                mentions: [],
+                reactions: [],
+                time: Date.now(),
+              })
+              chatroom.updatedAt = Date.now()
+              chatrooms[chatroomId] = chatroom
+              saveChatrooms(chatrooms)
+              notify(`chatroom:${chatroomId}`)
+              return JSON.stringify({ ok: true, messageId: msgId })
+            }
+
+            return `Error: unknown action "${action}". Valid actions: list_chatrooms, create_chatroom, add_agent, remove_agent, list_members, send_message`
+          } catch (err: unknown) {
+            return `Error: ${err instanceof Error ? err.message : String(err)}`
+          }
+        },
+        {
+          name: 'manage_chatrooms',
+          description: 'Manage chatrooms for multi-agent collaboration. Actions: list_chatrooms, create_chatroom, add_agent, remove_agent, list_members, send_message.',
+          schema: z.object({
+            action: z.enum(['list_chatrooms', 'create_chatroom', 'add_agent', 'remove_agent', 'list_members', 'send_message'])
+              .describe('The action to perform'),
+            chatroomId: z.string().optional().describe('Chatroom ID (required for most actions except list/create)'),
+            name: z.string().optional().describe('Chatroom name (for create_chatroom)'),
+            description: z.string().optional().describe('Chatroom description (for create_chatroom)'),
+            agentIds: z.array(z.string()).optional().describe('Initial agent IDs (for create_chatroom)'),
+            agentId: z.string().optional().describe('Agent ID (for add_agent/remove_agent)'),
+            message: z.string().optional().describe('Message text (for send_message)'),
+          }),
+        },
+      ),
+    )
+  }
+
+  return tools
+}

package/src/lib/server/session-tools/connector.ts

@@ -1,8 +1,21 @@
 import { z } from 'zod'
 import { tool, type StructuredToolInterface } from '@langchain/core/tools'
-import { loadConnectors, loadSettings } from '../storage'
+import path from 'path'
+import fs from 'fs'
+import { loadConnectors, loadSettings, UPLOAD_DIR } from '../storage'
 import type { ToolBuildContext } from './context'
 
+/** Resolve /api/uploads/filename URLs to actual disk paths */
+function resolveUploadUrl(url: string | undefined): { mediaPath: string; mimeType?: string } | null {
+  if (!url) return null
+  const match = url.match(/^\/api\/uploads\/([^?#]+)/)
+  if (!match) return null
+  const safeName = match[1].replace(/[^a-zA-Z0-9._-]/g, '')
+  const filePath = path.join(UPLOAD_DIR, safeName)
+  if (!fs.existsSync(filePath)) return null
+  return { mediaPath: filePath }
+}
+
 export function buildConnectorTools(bctx: ToolBuildContext): StructuredToolInterface[] {
   const tools: StructuredToolInterface[] = []
   const { ctx, hasTool } = bctx
@@ -32,6 +45,29 @@ export function buildConnectorTools(bctx: ToolBuildContext): StructuredToolInter
               return JSON.stringify(running)
             }
 
+            if (action === 'start') {
+              if (!connectorId) {
+                // If no ID given, list available connectors to start
+                const allConnectors = loadConnectors()
+                const stopped = Object.values(allConnectors)
+                  .filter((c) => !platform || c.platform === platform)
+                  .filter((c) => !running.find((r) => r.id === c.id))
+                  .map((c) => ({ id: c.id, name: c.name, platform: c.platform }))
+                if (!stopped.length) return 'All connectors are already running.'
+                return `Error: connectorId is required. Stopped connectors available to start: ${JSON.stringify(stopped)}`
+              }
+              const { startConnector: doStart } = await import('../connectors/manager')
+              await doStart(connectorId)
+              return JSON.stringify({ status: 'started', connectorId })
+            }
+
+            if (action === 'stop') {
+              if (!connectorId) return 'Error: connectorId is required for stop action.'
+              const { stopConnector: doStop } = await import('../connectors/manager')
+              await doStop(connectorId)
+              return JSON.stringify({ status: 'stopped', connectorId })
+            }
+
             if (action === 'send') {
               const settings = loadSettings()
               if (settings.safetyRequireApprovalForOutbound === true && approved !== true) {
@@ -41,7 +77,15 @@ export function buildConnectorTools(bctx: ToolBuildContext): StructuredToolInter
               const hasMedia = !!imageUrl?.trim() || !!fileUrl?.trim()
               if (!hasText && !hasMedia) return 'Error: message or media URL is required for send action.'
               if (!running.length) {
-                return `Error: no running connectors${platform ? ` for platform "${platform}"` : ''}.`
+                // Check for configured-but-not-running connectors to give actionable feedback
+                const allConnectors = loadConnectors()
+                const configured = Object.values(allConnectors)
+                  .filter((c) => !platform || c.platform === platform)
+                  .map((c) => ({ id: c.id, name: c.name, platform: c.platform, agentId: c.agentId || null }))
+                if (configured.length) {
+                  return `Error: no running connectors${platform ? ` for platform "${platform}"` : ''}, but ${configured.length} configured connector(s) found: ${JSON.stringify(configured)}. These connectors exist but are not currently started. Ask the user if they'd like you to start one (use action "start" with the connectorId), then retry the send.`
+                }
+                return `Error: no running connectors${platform ? ` for platform "${platform}"` : ''}. No connectors are configured for this platform either — the user needs to set one up in the Connectors panel first.`
               }
 
               const selected = connectorId
@@ -75,19 +119,49 @@ export function buildConnectorTools(bctx: ToolBuildContext): StructuredToolInter
                 if (allowed.length) channelId = allowed[0]
               }
               if (!channelId) {
-                return `Error: no target recipient configured. Provide "to", or set connector config "outboundJid"/"allowedJids"/"outboundTarget"/"allowFrom".`
+                // Collect any known numbers/targets from config to help the agent suggest them
+                const knownTargets: string[] = []
+                const jids = connector.config?.allowedJids?.split(',').map((s: string) => s.trim()).filter(Boolean) || []
+                const from = connector.config?.allowFrom?.split(',').map((s: string) => s.trim()).filter(Boolean) || []
+                const outJid = connector.config?.outboundJid?.trim()
+                const outTarget = connector.config?.outboundTarget?.trim()
+                if (outJid) knownTargets.push(outJid)
+                if (outTarget) knownTargets.push(outTarget)
+                knownTargets.push(...jids, ...from)
+                const unique = [...new Set(knownTargets)]
+                if (unique.length) {
+                  return `Error: no default outbound target is set, but the connector has ${unique.length} configured number(s)/target(s): ${JSON.stringify(unique)}. Ask the user which one to send to, then re-call with the "to" parameter set to their choice.`
+                }
+                return `Error: no target recipient configured and no known contacts on this connector. Ask the user for the recipient number/ID, then re-call with the "to" parameter. They can also configure "allowedJids" or "outboundJid" in the connector settings.`
               }
               if (connector.platform === 'whatsapp') {
                 channelId = normalizeWhatsAppTarget(channelId)
               }
 
+              // Resolve /api/uploads/ URLs to actual disk paths so connectors can read the files
+              let resolvedMediaPath = mediaPath?.trim() || undefined
+              let resolvedImageUrl = imageUrl?.trim() || undefined
+              let resolvedFileUrl = fileUrl?.trim() || undefined
+              if (!resolvedMediaPath) {
+                const fromImage = resolveUploadUrl(resolvedImageUrl)
+                if (fromImage) {
+                  resolvedMediaPath = fromImage.mediaPath
+                  resolvedImageUrl = undefined
+                }
+                const fromFile = resolveUploadUrl(resolvedFileUrl)
+                if (fromFile) {
+                  resolvedMediaPath = fromFile.mediaPath
+                  resolvedFileUrl = undefined
+                }
+              }
+
               const sent = await sendConnectorMessage({
                 connectorId: selected.id,
                 channelId,
                 text: message?.trim() || '',
-                imageUrl: imageUrl?.trim() || undefined,
-                fileUrl: fileUrl?.trim() || undefined,
-                mediaPath: mediaPath?.trim() || undefined,
+                imageUrl: resolvedImageUrl,
+                fileUrl: resolvedFileUrl,
+                mediaPath: resolvedMediaPath,
                 mimeType: mimeType?.trim() || undefined,
                 fileName: fileName?.trim() || undefined,
                 caption: caption?.trim() || undefined,
@@ -140,16 +214,16 @@ export function buildConnectorTools(bctx: ToolBuildContext): StructuredToolInter
               }
             }
 
-            return 'Unknown action. Use list_running, list_targets, or send.'
+            return 'Unknown action. Use list_running, list_targets, start, stop, or send.'
           } catch (err: unknown) {
             return `Error: ${err instanceof Error ? err.message : String(err)}`
           }
         },
         {
           name: 'connector_message_tool',
-          description: 'Send proactive outbound messages and perform rich messaging actions through running connectors. Supports listing running connectors/targets, sending text/media, and rich messaging (react, edit, delete, pin). For rich actions: connectorId + message (as messageId) required; caption carries emoji for react or new text for edit.',
+          description: 'Manage and send messages through chat platform connectors (WhatsApp, Telegram, Slack, Discord, etc.). Use "start"/"stop" to manage connector lifecycle, "list_running"/"list_targets" to discover available connectors and recipients, "send" to deliver messages, and rich actions (react, edit, delete, pin) for message management. When a send fails because no connector is running, check if one is configured and offer to start it. When no target is set, list available configured numbers and ask the user which to send to.',
           schema: z.object({
-            action: z.enum(['list_running', 'list_targets', 'send', 'message_react', 'message_edit', 'message_delete', 'message_pin']).describe('connector messaging action'),
+            action: z.enum(['list_running', 'list_targets', 'start', 'stop', 'send', 'message_react', 'message_edit', 'message_delete', 'message_pin']).describe('connector messaging action'),
             connectorId: z.string().optional().describe('Optional connector id. Defaults to the first running connector (or first for selected platform).'),
             platform: z.string().optional().describe('Optional platform filter (whatsapp, telegram, slack, discord, bluebubbles, etc.).'),
             to: z.string().optional().describe('Target channel id / recipient. For WhatsApp, phone number or full JID.'),