@swarmclawai/swarmclaw 0.5.3 → 0.6.2

package/src/lib/server/connectors/manager.ts

@@ -2,12 +2,27 @@ import { genId } from '@/lib/id'
 import {
   loadConnectors, saveConnectors, loadSessions, saveSessions,
   loadAgents, loadCredentials, decryptKey, loadSettings, loadSkills,
+  loadChatrooms, saveChatrooms,
 } from '../storage'
 import { WORKSPACE_DIR } from '../data-dir'
+import { UPLOAD_DIR } from '../storage'
+import fs from 'fs'
+import path from 'path'
 import { streamAgentChat } from '../stream-agent-chat'
 import { notify } from '../ws-hub'
 import { logExecution } from '../execution-log'
-import type { Connector } from '@/types'
+import { enqueueSystemEvent } from '../system-events'
+import { requestHeartbeatNow } from '../heartbeat-wake'
+import { buildCurrentDateTimePromptContext } from '../prompt-runtime-context'
+import {
+  parseMentions,
+  buildChatroomSystemPrompt,
+  buildSyntheticSession,
+  buildAgentSystemPromptForChatroom,
+  buildHistoryForAgent,
+  resolveApiKey as resolveApiKeyHelper,
+} from '../chatroom-helpers'
+import type { Connector, MessageSource, Chatroom, ChatroomMessage } from '@/types'
 import type { ConnectorInstance, InboundMessage, InboundMedia } from './types'
 import {
   addAllowedSender,
@@ -21,6 +36,30 @@ import {
   type PairingPolicy,
 } from './pairing'
 
+/**
+ * Extract embedded media references from agent response text.
+ * Parses markdown image/link patterns like ![alt](/api/uploads/filename)
+ * and resolves them to actual file paths on disk.
+ */
+function extractEmbeddedMedia(text: string): { cleanText: string; files: Array<{ path: string; alt: string }> } {
+  const files: Array<{ path: string; alt: string }> = []
+  // Match markdown images: ![alt](/api/uploads/filename)
+  const imgRegex = /!\[([^\]]*)\]\(\/api\/uploads\/([^)]+)\)/g
+  let match: RegExpExecArray | null
+  while ((match = imgRegex.exec(text)) !== null) {
+    const [, alt, filename] = match
+    const safeName = filename.replace(/[^a-zA-Z0-9._-]/g, '')
+    const filePath = path.join(UPLOAD_DIR, safeName)
+    if (fs.existsSync(filePath)) {
+      files.push({ path: filePath, alt: alt || '' })
+    }
+  }
+  if (files.length === 0) return { cleanText: text, files }
+  // Strip the image markdown from text — the files will be sent as separate media
+  const cleanText = text.replace(imgRegex, '').replace(/\n{3,}/g, '\n\n').trim()
+  return { cleanText, files }
+}
+
 /** Sentinel value agents return when no outbound reply should be sent */
 export const NO_MESSAGE_SENTINEL = 'NO_MESSAGE'
 
@@ -419,6 +458,132 @@ async function handleConnectorCommand(params: {
   return 'Unknown command.'
 }
 
+/** Route an inbound message to a chatroom — process mentioned agents and return concatenated responses */
+async function routeMessageToChatroom(connector: Connector, msg: InboundMessage): Promise<string> {
+  const chatroomId = connector.chatroomId
+  if (!chatroomId) return '[Error] No chatroom configured.'
+
+  const chatrooms = loadChatrooms()
+  const chatroom = chatrooms[chatroomId] as Chatroom | undefined
+  if (!chatroom) return '[Error] Chatroom not found.'
+
+  const agents = loadAgents()
+  const source: MessageSource = {
+    platform: connector.platform,
+    connectorId: connector.id,
+    connectorName: connector.name,
+    senderName: msg.senderName,
+  }
+
+  // Parse mentions from the message text
+  let mentions = parseMentions(msg.text || '', agents, chatroom.agentIds)
+  // Auto-address: if enabled and no explicit mentions, address all agents
+  if (chatroom.autoAddress && mentions.length === 0) {
+    mentions = [...chatroom.agentIds]
+  }
+
+  // Create and persist the user message in the chatroom
+  const userMessage: ChatroomMessage = {
+    id: genId(),
+    senderId: 'user',
+    senderName: msg.senderName || 'User',
+    role: 'user',
+    text: msg.text || '',
+    mentions,
+    reactions: [],
+    time: Date.now(),
+    source,
+  }
+  chatroom.messages.push(userMessage)
+  chatroom.updatedAt = Date.now()
+  chatrooms[chatroomId] = chatroom
+  saveChatrooms(chatrooms)
+  notify('chatrooms')
+  notify(`chatroom:${chatroomId}`)
+
+  // Process mentioned agents sequentially and collect responses
+  const responses: string[] = []
+  for (const agentId of mentions) {
+    const agent = agents[agentId]
+    if (!agent) continue
+
+    const apiKey = resolveApiKeyHelper(agent.credentialId)
+    const freshChatrooms = loadChatrooms()
+    const freshChatroom = freshChatrooms[chatroomId] as Chatroom
+
+    const syntheticSession = buildSyntheticSession(agent, chatroomId)
+    const agentSystemPrompt = buildAgentSystemPromptForChatroom(agent)
+    const chatroomContext = buildChatroomSystemPrompt(freshChatroom, agents, agent.id)
+    const fullSystemPrompt = [agentSystemPrompt, chatroomContext].filter(Boolean).join('\n\n')
+    const history = buildHistoryForAgent(freshChatroom, agent.id)
+
+    try {
+      const result = await streamAgentChat({
+        session: syntheticSession,
+        message: msg.text || '',
+        apiKey,
+        systemPrompt: fullSystemPrompt,
+        write: () => {},
+        history,
+      })
+
+      const responseText = result.finalResponse || result.fullText
+      if (responseText.trim() && !isNoMessage(responseText)) {
+        // Persist agent response to chatroom
+        const agentSource: MessageSource = {
+          platform: connector.platform,
+          connectorId: connector.id,
+          connectorName: connector.name,
+        }
+        const agentMessage: ChatroomMessage = {
+          id: genId(),
+          senderId: agent.id,
+          senderName: agent.name,
+          role: 'assistant',
+          text: responseText,
+          mentions: parseMentions(responseText, agents, freshChatroom.agentIds),
+          reactions: [],
+          time: Date.now(),
+          source: agentSource,
+        }
+        const latestChatrooms = loadChatrooms()
+        const latestChatroom = latestChatrooms[chatroomId] as Chatroom
+        latestChatroom.messages.push(agentMessage)
+        latestChatroom.updatedAt = Date.now()
+        latestChatrooms[chatroomId] = latestChatroom
+        saveChatrooms(latestChatrooms)
+        notify(`chatroom:${chatroomId}`)
+
+        responses.push(`[${agent.name}] ${responseText}`)
+      }
+    } catch (err: unknown) {
+      const errMsg = err instanceof Error ? err.message : String(err)
+      console.error(`[connector] Chatroom agent ${agent.name} error:`, errMsg)
+    }
+  }
+
+  if (responses.length === 0) return NO_MESSAGE_SENTINEL
+
+  const joined = responses.join('\n\n')
+  // Extract embedded media from agent responses and send them via connector
+  const extracted = extractEmbeddedMedia(joined)
+  if (extracted.files.length > 0) {
+    const inst = running.get(connector.id)
+    if (inst?.sendMessage) {
+      for (const file of extracted.files) {
+        try {
+          await inst.sendMessage(msg.channelId, '', { mediaPath: file.path, caption: file.alt || undefined })
+          console.log(`[connector] Sent chatroom media to ${msg.platform}: ${path.basename(file.path)}`)
+        } catch (err: unknown) {
+          console.error(`[connector] Failed to send chatroom media ${path.basename(file.path)}:`, err instanceof Error ? err.message : String(err))
+        }
+      }
+    }
+    return extracted.cleanText || '(no response)'
+  }
+  return joined
+}
+
 /** Route an inbound message through the assigned agent and return the response */
 async function routeMessage(connector: Connector, msg: InboundMessage): Promise<string> {
   if (msg?.channelId) {
@@ -426,11 +591,26 @@ async function routeMessage(connector: Connector, msg: InboundMessage): Promise<
   }
   lastInboundTimeByConnector.set(connector.id, Date.now())
 
+  // Route to chatroom if configured
+  if (connector.chatroomId) {
+    return routeMessageToChatroom(connector, msg)
+  }
+
   const agents = loadAgents()
   const effectiveAgentId = msg.agentIdOverride || connector.agentId
+  if (!effectiveAgentId) return '[Error] Connector has no agent configured.'
   const agent = agents[effectiveAgentId]
   if (!agent) return '[Error] Connector agent not found.'
 
+  // Enqueue system event + heartbeat wake for the agent
+  const preview = (msg.text || '').slice(0, 80)
+  enqueueSystemEvent(
+    `connector:${connector.id}:${msg.channelId}`,
+    `Inbound message from ${msg.platform}: ${preview}`,
+    'connector-message',
+  )
+  requestHeartbeatNow({ agentId: effectiveAgentId, reason: 'connector-message' })
+
   // Log connector trigger
   const triggerSessionKey = `connector:${connector.id}:${msg.channelId}`
   const allSessions = loadSessions()
@@ -461,11 +641,16 @@ async function routeMessage(connector: Connector, msg: InboundMessage): Promise<
     }
   }
 
-  // Find or create a session keyed by platform + channel
+  // Find a session for this connector message.
+  // Prefer the agent's thread session (visible in the agent chat UI) so connector
+  // messages appear inline alongside web UI messages.
+  // Fall back to a connector-keyed session if the agent has no thread session.
   const sessionKey = `connector:${connector.id}:${msg.channelId}`
   const sessions = loadSessions()
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  let session = Object.values(sessions).find((s: any) => s.name === sessionKey)
+  let session = (agent.threadSessionId && sessions[agent.threadSessionId])
+    ? sessions[agent.threadSessionId]
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    : Object.values(sessions).find((s: any) => s.name === sessionKey)
   if (!session) {
     const id = genId()
     session = {
@@ -553,6 +738,7 @@ async function routeMessage(connector: Connector, msg: InboundMessage): Promise<
   const settings = loadSettings()
   const promptParts: string[] = []
   if (settings.userPrompt) promptParts.push(settings.userPrompt)
+  promptParts.push(buildCurrentDateTimePromptContext())
   if (agent.soul) promptParts.push(agent.soul)
   if (agent.systemPrompt) promptParts.push(agent.systemPrompt)
   if (agent.skillIds?.length) {
@@ -583,12 +769,22 @@ The test: would a thoughtful friend feel compelled to type something back? If no
   const firstImageUrl = msg.imageUrl || (firstImage?.url) || undefined
   const firstImagePath = firstImage?.localPath || undefined
   const inboundText = formatInboundUserText(msg)
+  // Store the raw user text for display (source.senderName handles attribution).
+  // The formatted text with [SenderName] prefix is only used for LLM history context.
+  const rawText = (msg.text || '').trim()
+  const messageSource: MessageSource = {
+    platform: connector.platform,
+    connectorId: connector.id,
+    connectorName: connector.name,
+    senderName: msg.senderName,
+  }
   session.messages.push({
     role: 'user',
-    text: inboundText,
+    text: rawText || inboundText,
     time: Date.now(),
     imageUrl: firstImageUrl,
     imagePath: firstImagePath,
+    source: messageSource,
   })
   session.lastActiveAt = Date.now()
   const s1 = loadSessions()
@@ -668,9 +864,14 @@ The test: would a thoughtful friend feel compelled to type something back? If no
     },
   })
 
-  // Save assistant response to session
+  // Save assistant response to session (full text with image markdown for web UI rendering)
+  const assistantSource: MessageSource = {
+    platform: connector.platform,
+    connectorId: connector.id,
+    connectorName: connector.name,
+  }
   if (fullText.trim()) {
-    session.messages.push({ role: 'assistant', text: fullText.trim(), time: Date.now() })
+    session.messages.push({ role: 'assistant', text: fullText.trim(), time: Date.now(), source: assistantSource })
     session.lastActiveAt = Date.now()
     const s2 = loadSessions()
     s2[session.id] = session
@@ -678,6 +879,24 @@ The test: would a thoughtful friend feel compelled to type something back? If no
     notify(`messages:${session.id}`)
   }
 
+  // Extract embedded media (screenshots, uploaded files) and send them as separate
+  // media messages via the connector, then return the cleaned text
+  const extracted = extractEmbeddedMedia(fullText)
+  if (extracted.files.length > 0) {
+    const inst = running.get(connector.id)
+    if (inst?.sendMessage) {
+      for (const file of extracted.files) {
+        try {
+          await inst.sendMessage(msg.channelId, '', { mediaPath: file.path, caption: file.alt || undefined })
+          console.log(`[connector] Sent media to ${msg.platform}: ${path.basename(file.path)}`)
+        } catch (err: unknown) {
+          console.error(`[connector] Failed to send media ${path.basename(file.path)}:`, err instanceof Error ? err.message : String(err))
+        }
+      }
+    }
+    return extracted.cleanText || '(no response)'
+  }
+
   return fullText || '(no response)'
 }
 
@@ -862,6 +1081,7 @@ export function listRunningConnectors(platform?: string): Array<{
   id: string
   name: string
   platform: string
+  agentId: string | null
   supportsSend: boolean
   configuredTargets: string[]
   recentChannelId: string | null
@@ -871,6 +1091,7 @@ export function listRunningConnectors(platform?: string): Array<{
     id: string
     name: string
     platform: string
+    agentId: string | null
     supportsSend: boolean
     configuredTargets: string[]
     recentChannelId: string | null
@@ -896,6 +1117,7 @@ export function listRunningConnectors(platform?: string): Array<{
       id,
       name: connector.name,
       platform: connector.platform,
+      agentId: connector.agentId || null,
       supportsSend: typeof instance.sendMessage === 'function',
       configuredTargets: Array.from(new Set(configuredTargets)),
       recentChannelId: lastInboundChannelByConnector.get(id) || null,

package/src/lib/server/context-manager.ts

@@ -1,6 +1,17 @@
-import type { Message, ProviderType } from '@/types'
+import type { Message } from '@/types'
 import { getMemoryDb } from './memory-db'
 
+// --- LLM compaction constants ---
+
+const COMPACTION_CHUNK_BUDGET_RATIO = 0.4   // 40% of context per summarization chunk
+const COMPACTION_SAFETY_MARGIN = 1.2         // 20% buffer for token underestimation
+const COMPACTION_OVERHEAD_TOKENS = 4096      // reserved for summarization prompt + response
+const MAX_TOOL_FAILURES = 8
+const MAX_FAILURE_CHARS = 240
+
+/** Callback that sends a prompt to an LLM and returns response text */
+export type LLMSummarizer = (prompt: string) => Promise<string>
+
 // --- Context window sizes (tokens) per provider/model ---
 
 const PROVIDER_CONTEXT_WINDOWS: Record<string, number> = {
@@ -160,6 +171,125 @@ export function consolidateToMemory(
   return stored
 }
 
+// --- LLM compaction helpers ---
+
+/** Extract recent tool failures from messages for metadata appendix */
+export function extractToolFailures(messages: Message[]): string[] {
+  const failures: string[] = []
+  for (const m of messages) {
+    if (!m.toolEvents) continue
+    for (const te of m.toolEvents) {
+      if (!te.error) continue
+      const snippet = (te.output || '').slice(0, MAX_FAILURE_CHARS)
+      failures.push(`[${te.name}] error: ${snippet}`)
+    }
+  }
+  return failures.slice(-MAX_TOOL_FAILURES)
+}
+
+/** Extract file paths read and modified from tool events */
+export function extractFileOperations(messages: Message[]): { read: string[]; modified: string[] } {
+  const readSet = new Set<string>()
+  const modifiedSet = new Set<string>()
+
+  const READ_TOOLS = new Set(['read_file', 'list_files'])
+  const WRITE_TOOLS = new Set(['write_file', 'edit_file', 'copy_file', 'move_file', 'delete_file'])
+
+  for (const m of messages) {
+    if (!m.toolEvents) continue
+    for (const te of m.toolEvents) {
+      let parsed: Record<string, unknown> | null = null
+      try { parsed = JSON.parse(te.input) } catch { /* not JSON */ }
+      if (!parsed) continue
+
+      const paths: string[] = []
+      for (const key of ['filePath', 'sourcePath', 'destinationPath']) {
+        const v = parsed[key]
+        if (typeof v === 'string' && v) paths.push(v)
+      }
+
+      const isRead = READ_TOOLS.has(te.name)
+      const isWrite = WRITE_TOOLS.has(te.name)
+      for (const p of paths) {
+        if (isWrite) modifiedSet.add(p)
+        else if (isRead) readSet.add(p)
+      }
+    }
+  }
+  return { read: [...readSet], modified: [...modifiedSet] }
+}
+
+/** Split messages into chunks that fit within a token budget each */
+export function splitMessagesByTokenBudget(messages: Message[], budgetPerChunk: number): Message[][] {
+  if (messages.length === 0) return []
+  const chunks: Message[][] = []
+  let current: Message[] = []
+  let currentTokens = 0
+
+  for (const m of messages) {
+    const msgTokens = estimateMessagesTokens([m])
+    if (current.length > 0 && currentTokens + msgTokens > budgetPerChunk) {
+      chunks.push(current)
+      current = []
+      currentTokens = 0
+    }
+    current.push(m)
+    currentTokens += msgTokens
+  }
+  if (current.length > 0) chunks.push(current)
+  return chunks
+}
+
+/** Build an OpenClaw-aligned summarization prompt for a batch of messages */
+function buildSummarizationPrompt(messages: Message[]): string {
+  const transcript = messages.map((m) => {
+    let line = `[${m.role}]: ${m.text}`
+    if (m.toolEvents?.length) {
+      for (const te of m.toolEvents) {
+        const inp = (te.input || '').slice(0, 500)
+        const out = (te.output || '').slice(0, 500)
+        line += `\n  tool:${te.name}(${inp})${te.error ? ' [ERROR]' : ''} → ${out}`
+      }
+    }
+    return line
+  }).join('\n\n')
+
+  return [
+    'Summarize the following conversation transcript into structured notes.',
+    '',
+    'Rules:',
+    '- Preserve all decisions, TODOs, open questions, and constraints',
+    '- Preserve all opaque identifiers exactly as they appear (UUIDs, hashes, IDs, URLs, file paths, API keys, variable names)',
+    '- Note errors encountered and their resolutions',
+    '- Keep technical details needed to continue work (versions, configs, commands)',
+    '- Aim for 20-40% of original length',
+    '- Use structured notes with bullet points, not narrative prose',
+    '- Group by topic/theme when possible',
+    '',
+    '---TRANSCRIPT---',
+    transcript,
+    '---END TRANSCRIPT---',
+  ].join('\n')
+}
+
+/** Build a merge prompt for combining multiple partial summaries */
+function buildMergePrompt(partialSummaries: string[]): string {
+  const numbered = partialSummaries.map((s, i) => `--- Part ${i + 1} ---\n${s}`).join('\n\n')
+
+  return [
+    'Merge the following partial conversation summaries into a single cohesive summary.',
+    '',
+    'Rules:',
+    '- Remove redundancy across parts while preserving all important details',
+    '- Preserve all opaque identifiers exactly (UUIDs, hashes, IDs, URLs, file paths)',
+    '- Keep decisions, TODOs, open questions, constraints, and error resolutions',
+    '- Use structured notes with bullet points',
+    '- The result should be shorter than the combined input',
+    '',
+    numbered,
+  ].join('\n')
+}
+
 // --- Compaction strategies ---
 
 export interface CompactionResult {
@@ -178,15 +308,18 @@ export function slidingWindowCompact(
   return messages.slice(-keepLastN)
 }
 
-/** Summarize old messages, keep recent ones */
-export async function summarizeAndCompact(opts: {
+/** LLM-powered compaction: summarize old messages using an LLM, with progressive fallback */
+export async function llmCompact(opts: {
   messages: Message[]
-  keepLastN: number
+  provider: string
+  model: string
   agentId: string | null
   sessionId: string
-  generateSummary: (text: string) => Promise<string>
+  summarize: LLMSummarizer
+  keepLastN?: number
 }): Promise<CompactionResult> {
-  const { messages, keepLastN, agentId, sessionId, generateSummary } = opts
+  const { messages, provider, model, agentId, sessionId, summarize, keepLastN = 10 } = opts
+
   if (messages.length <= keepLastN) {
     return { messages, prunedCount: 0, memoriesStored: 0, summaryAdded: false }
   }
@@ -194,19 +327,75 @@ export async function summarizeAndCompact(opts: {
   const oldMessages = messages.slice(0, -keepLastN)
   const recentMessages = messages.slice(-keepLastN)
 
-  // Consolidate important info to memory before pruning
+  // 1. Consolidate important info to memory (existing regex extraction)
   const memoriesStored = consolidateToMemory(oldMessages, agentId, sessionId)
 
-  // Build text for summarization
-  const conversationText = oldMessages
-    .map((m) => `${m.role}: ${m.text}`)
-    .join('\n\n')
+  // 2. Extract metadata from old messages
+  const toolFailures = extractToolFailures(oldMessages)
+  const fileOps = extractFileOperations(oldMessages)
+
+  // 3. Compute chunk budget
+  const contextWindow = getContextWindowSize(provider, model)
+  const chunkBudget = Math.floor((contextWindow / COMPACTION_SAFETY_MARGIN) * COMPACTION_CHUNK_BUDGET_RATIO) - COMPACTION_OVERHEAD_TOKENS
+
+  // 4. Split old messages into chunks
+  const chunks = splitMessagesByTokenBudget(oldMessages, Math.max(chunkBudget, 2000))
+
+  // 5. Summarize chunks (progressive fallback on failure)
+  let finalSummary: string | null = null
+  try {
+    if (chunks.length === 1) {
+      finalSummary = await summarize(buildSummarizationPrompt(chunks[0]))
+    } else {
+      // Multi-chunk: summarize each, then merge
+      const partialSummaries: string[] = []
+      for (const chunk of chunks) {
+        try {
+          const partial = await summarize(buildSummarizationPrompt(chunk))
+          if (partial?.trim()) partialSummaries.push(partial.trim())
+        } catch {
+          // Skip failed chunks — progressive fallback
+        }
+      }
+      if (partialSummaries.length === 0) {
+        finalSummary = null // all chunks failed
+      } else if (partialSummaries.length === 1) {
+        finalSummary = partialSummaries[0]
+      } else {
+        finalSummary = await summarize(buildMergePrompt(partialSummaries))
+      }
+    }
+  } catch {
+    finalSummary = null
+  }
+
+  // 6. Fall back to sliding window if LLM summarization failed entirely
+  if (!finalSummary?.trim()) {
+    return {
+      messages: slidingWindowCompact(messages, keepLastN),
+      prunedCount: oldMessages.length,
+      memoriesStored,
+      summaryAdded: false,
+    }
+  }
+
+  // 7. Append metadata sections
+  const metaSections: string[] = [finalSummary.trim()]
 
-  const summary = await generateSummary(conversationText)
+  if (toolFailures.length > 0) {
+    metaSections.push('\n## Tool Failures\n' + toolFailures.join('\n'))
+  }
+  if (fileOps.read.length > 0 || fileOps.modified.length > 0) {
+    const parts: string[] = []
+    if (fileOps.read.length) parts.push('Read: ' + fileOps.read.join(', '))
+    if (fileOps.modified.length) parts.push('Modified: ' + fileOps.modified.join(', '))
+    metaSections.push('\n## File Operations\n' + parts.join('\n'))
+  }
 
+  // 8. Build context summary message
   const summaryMessage: Message = {
     role: 'assistant',
-    text: `[Context Summary]\n${summary}`,
+    text: `[Context Summary]\n${metaSections.join('\n')}`,
     time: Date.now(),
     kind: 'system',
   }
@@ -219,6 +408,29 @@ export async function summarizeAndCompact(opts: {
   }
 }
 
+/** Summarize old messages, keep recent ones. Delegates to llmCompact for LLM-powered summarization. */
+export async function summarizeAndCompact(opts: {
+  messages: Message[]
+  keepLastN: number
+  agentId: string | null
+  sessionId: string
+  provider: string
+  model: string
+  generateSummary: LLMSummarizer
+}): Promise<CompactionResult> {
+  const { messages, keepLastN, agentId, sessionId, provider, model, generateSummary } = opts
+
+  return llmCompact({
+    messages,
+    provider,
+    model,
+    agentId,
+    sessionId,
+    summarize: generateSummary,
+    keepLastN,
+  })
+}
+
 /** Auto-compact: triggers when estimated tokens exceed threshold */
 export function shouldAutoCompact(
   messages: Message[],

package/src/lib/server/create-notification.ts

@@ -1,26 +1,38 @@
 import { genId } from '@/lib/id'
-import { saveNotification } from '@/lib/server/storage'
+import { saveNotification, hasUnreadNotificationWithKey } from '@/lib/server/storage'
 import { notify } from '@/lib/server/ws-hub'
 import type { AppNotification } from '@/types'
 
 /**
  * Create and persist a notification, then push a WS invalidation.
+ * If `dedupKey` is provided and an unread notification with the same key
+ * already exists, returns `null` (no insert, no WS push).
  */
 export function createNotification(opts: {
   type: AppNotification['type']
   title: string
   message?: string
+  actionLabel?: string
+  actionUrl?: string
   entityType?: string
   entityId?: string
-}) {
+  dedupKey?: string
+}): AppNotification | null {
+  if (opts.dedupKey && hasUnreadNotificationWithKey(opts.dedupKey)) {
+    return null
+  }
+
   const id = genId()
   const notification: AppNotification = {
     id,
     type: opts.type,
     title: opts.title,
     message: opts.message,
+    actionLabel: opts.actionLabel,
+    actionUrl: opts.actionUrl,
     entityType: opts.entityType,
     entityId: opts.entityId,
+    dedupKey: opts.dedupKey,
     read: false,
     createdAt: Date.now(),
   }