@swarmclawai/swarmclaw 0.8.0 → 0.8.2

package/README.md

@@ -148,7 +148,7 @@ curl -fsSL https://raw.githubusercontent.com/swarmclawai/swarmclaw/main/install.
 ```
 
 The installer resolves the latest stable release tag and installs that version by default.
-To pin a version: `SWARMCLAW_VERSION=v0.8.0 curl ... | bash`
+To pin a version: `SWARMCLAW_VERSION=v0.8.2 curl ... | bash`
 
 Or run locally from the repo (friendly for non-technical users):
 
@@ -701,7 +701,7 @@ npm run update:easy     # safe update helper for local installs
 SwarmClaw uses tag-based releases (`vX.Y.Z`) as the stable channel.
 
 ```bash
-# example minor release (v0.8.0 style)
+# example minor release (v0.8.2 style)
 npm version minor
 git push origin main --follow-tags
 ```
@@ -711,13 +711,14 @@ On `v*` tags, GitHub Actions will:
 2. Create a GitHub Release
 3. Build and publish Docker images to `ghcr.io/swarmclawai/swarmclaw` (`:vX.Y.Z`, `:latest`, `:sha-*`)
 
-#### v0.8.0 Release Readiness Notes
+#### v0.8.2 Release Readiness Notes
 
-Before shipping `v0.8.0`, confirm the following user-facing changes are reflected in docs:
+Before shipping `v0.8.2`, confirm the following user-facing changes are reflected in docs:
 
-1. Voice and connector docs mention that outbound voice-note sends now retry with the built-in ElevenLabs fallback voice when a configured default voice is rejected as paid-only.
-2. Release notes call out the Molly-style regression case explicitly: WhatsApp voice-note delivery should keep working even if the saved default voice ID points at a paid library voice.
-3. Site and README install/version strings are updated to `v0.8.0`, including install snippets, release notes index text, and sidebar/footer labels.
+1. Runtime/defaults docs mention the higher default agent recursion limit so long-running bounded turns get more headroom without custom tuning.
+2. Memory/tooling docs mention the narrower direct-memory-write routing: remember-and-confirm turns stay on `memory_store`/`memory_update`, bundled related facts should be stored as one canonical write, and same-thread recall should not steal those turns.
+3. File-output guidance notes that exact bullet-count and titled-section constraints are now treated as hard structure requirements during deliverable follow-through.
+4. Site and README install/version strings are updated to `v0.8.2`, including install snippets, release notes index text, and sidebar/footer labels.
 
 ## CLI
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmclawai/swarmclaw",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "Self-hosted AI agent orchestration dashboard — manage LLM providers, orchestrate agent swarms, schedule tasks, and bridge agents to chat platforms.",
   "license": "MIT",
   "publishConfig": {
@@ -9,7 +9,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/swarmclawai/swarmclaw.git"
+    "url": "git+https://github.com/swarmclawai/swarmclaw.git"
   },
   "keywords": [
     "ai",

package/src/app/api/notifications/route.ts

@@ -1,6 +1,7 @@
 import { NextResponse } from 'next/server'
-import { genId } from '@/lib/id'
-import { loadNotifications, saveNotification, deleteNotification } from '@/lib/server/storage'
+import { getNotificationActivityAt } from '@/lib/notification-utils'
+import { createNotification } from '@/lib/server/create-notification'
+import { loadNotifications, deleteNotification } from '@/lib/server/storage'
 import { notify } from '@/lib/server/ws-hub'
 import type { AppNotification } from '@/types'
 export const dynamic = 'force-dynamic'
@@ -20,7 +21,7 @@ export async function GET(req: Request) {
     entries = entries.filter((e) => !e.read)
   }
 
-  entries.sort((a, b) => b.createdAt - a.createdAt)
+  entries.sort((a, b) => getNotificationActivityAt(b) - getNotificationActivityAt(a))
   entries = entries.slice(0, limit)
 
   return NextResponse.json(entries)
@@ -30,9 +31,10 @@ export async function POST(req: Request) {
   const body = (await req.json()) as Record<string, unknown>
   const actionLabel = typeof body.actionLabel === 'string' ? body.actionLabel : undefined
   const actionUrl = typeof body.actionUrl === 'string' ? body.actionUrl : undefined
-  const id = genId()
-  const notification: AppNotification = {
-    id,
+  const dedupKey = typeof body.dedupKey === 'string' && body.dedupKey.trim()
+    ? body.dedupKey.trim()
+    : undefined
+  const { notification, created } = createNotification({
     type: (['info', 'success', 'warning', 'error'].includes(body.type as string) ? body.type : 'info') as AppNotification['type'],
     title: typeof body.title === 'string' ? body.title : 'Notification',
     message: typeof body.message === 'string' ? body.message : undefined,
@@ -40,13 +42,10 @@ export async function POST(req: Request) {
     actionUrl,
     entityType: typeof body.entityType === 'string' ? body.entityType : undefined,
     entityId: typeof body.entityId === 'string' ? body.entityId : undefined,
-    read: false,
-    createdAt: Date.now(),
-  }
+    dedupKey,
+  })
 
-  saveNotification(id, notification)
-  notify('notifications')
-  return NextResponse.json(notification, { status: 201 })
+  return NextResponse.json(notification, { status: created ? 201 : 200 })
 }
 
 export async function DELETE(req: Request) {

package/src/app/page.tsx

@@ -7,6 +7,7 @@ import { getStoredAccessKey, clearStoredAccessKey, api } from '@/lib/api-client'
 import { safeStorageGet, safeStorageRemove, safeStorageSet } from '@/lib/safe-storage'
 import { connectWs, disconnectWs } from '@/lib/ws-client'
 import { fetchWithTimeout } from '@/lib/fetch-timeout'
+import { isLocalhostBrowser } from '@/lib/local-observability'
 import { useWs } from '@/hooks/use-ws'
 import { AccessKeyGate } from '@/components/auth/access-key-gate'
 import { UserPicker } from '@/components/auth/user-picker'
@@ -270,6 +271,14 @@ export default function Home() {
 
   useWs('sessions', loadSessions, 5000)
 
+  useEffect(() => {
+    if (!authenticated || !isLocalhostBrowser()) return
+    const pollId = setInterval(() => {
+      void loadSessions()
+    }, 5000)
+    return () => clearInterval(pollId)
+  }, [authenticated, loadSessions])
+
   // Auto-select agent's thread on load — resolves a persisted agentId into a session,
   // or falls back to defaultAgentId from settings, then first agent.
   const [agentReady, setAgentReady] = useState(false)

package/src/components/chat/chat-list.tsx

@@ -5,6 +5,7 @@ import { useAppStore } from '@/stores/use-app-store'
 import { useChatStore } from '@/stores/use-chat-store'
 import { ChatCard } from './chat-card'
 import { fetchMessages } from '@/lib/chats'
+import { isLocalhostBrowser, isVisibleSessionForViewer } from '@/lib/local-observability'
 import { toast } from 'sonner'
 import { Skeleton } from '@/components/shared/skeleton'
 import { EmptyState } from '@/components/shared/empty-state'
@@ -38,6 +39,7 @@ export function ChatList({ inSidebar, onSelect }: Props) {
   const [typeFilter, setTypeFilter] = useState<SessionFilter>('all')
   const [sortMode, setSortMode] = useState<SortMode>('lastActive')
   const [loaded, setLoaded] = useState(Object.keys(sessions).length > 0)
+  const [showLocalPlatformSessions, setShowLocalPlatformSessions] = useState(false)
   const [bulkMenuOpen, setBulkMenuOpen] = useState(false)
   const [confirmClearIds, setConfirmClearIds] = useState<string[] | null>(null)
   const [clearing, setClearing] = useState(false)
@@ -50,16 +52,15 @@ export function ChatList({ inSidebar, onSelect }: Props) {
     void loadConnectors()
   }, [loadConnectors])
 
+  useEffect(() => {
+    setShowLocalPlatformSessions(isLocalhostBrowser())
+  }, [])
+
   const allUserSessions = useMemo(() => {
-    return Object.values(sessions).filter((s) => {
-      const owner = (s.user || '').toLowerCase()
-      const isPlatformOwned = owner === 'system' || owner === 'connector' || owner === 'swarm'
-      const isCurrentUserOwned = !!currentUser && owner === currentUser.toLowerCase()
-      const isUnownedLegacy = !owner
-      if (!isCurrentUserOwned && !isPlatformOwned && !isUnownedLegacy) return false
-      return true
-    })
-  }, [sessions, currentUser])
+    return Object.values(sessions).filter((s) => isVisibleSessionForViewer(s, currentUser, {
+      localhost: showLocalPlatformSessions,
+    }))
+  }, [sessions, currentUser, showLocalPlatformSessions])
 
   const filtered = useMemo(() => {
     return allUserSessions

package/src/components/home/home-view.tsx

@@ -6,6 +6,8 @@ import { useAppStore } from '@/stores/use-app-store'
 import { useChatStore } from '@/stores/use-chat-store'
 import { AgentAvatar } from '@/components/agents/agent-avatar'
 import { api } from '@/lib/api-client'
+import { isLocalhostBrowser, isVisibleSessionForViewer } from '@/lib/local-observability'
+import { getNotificationActivityAt, getNotificationOccurrenceCount } from '@/lib/notification-utils'
 import type { Agent, Session, ActivityEntry, BoardTask, AppNotification } from '@/types'
 import { HintTip } from '@/components/shared/hint-tip'
 
@@ -68,6 +70,7 @@ const PLATFORM_LABELS: Record<string, string> = {
 export function HomeView() {
   const agents = useAppStore((s) => s.agents)
   const sessions = useAppStore((s) => s.sessions)
+  const currentUser = useAppStore((s) => s.currentUser)
   const tasks = useAppStore((s) => s.tasks)
   const connectors = useAppStore((s) => s.connectors)
   const schedules = useAppStore((s) => s.schedules)
@@ -95,9 +98,10 @@ export function HomeView() {
   const recentChats = useMemo(
     () =>
       Object.values(sessions)
+        .filter((session) => isVisibleSessionForViewer(session, currentUser, { localhost: isLocalhostBrowser() }))
         .sort((a, b) => (b.lastActiveAt || 0) - (a.lastActiveAt || 0))
         .slice(0, 5),
-    [sessions],
+    [currentUser, sessions],
   )
 
   // Quick stats
@@ -382,7 +386,14 @@ export function HomeView() {
                       <span className="text-[13px] font-500 text-text">{n.title}</span>
                       {n.message && <p className="text-[11px] text-text-3/60 truncate mt-0.5 m-0">{n.message}</p>}
                     </div>
-                    <span className="text-[10px] text-text-3/40 shrink-0 mt-0.5">{timeAgo(n.createdAt)}</span>
+                    <div className="flex items-center gap-1.5 shrink-0 mt-0.5">
+                      {getNotificationOccurrenceCount(n) > 1 && (
+                        <span className="rounded-full border border-white/[0.08] bg-white/[0.04] px-1.5 py-0.5 text-[9px] font-600 text-text-3/80">
+                          x{getNotificationOccurrenceCount(n)}
+                        </span>
+                      )}
+                      <span className="text-[10px] text-text-3/40">{timeAgo(getNotificationActivityAt(n))}</span>
+                    </div>
                   </button>
                 ))}
               </div>

package/src/components/layout/app-layout.tsx

@@ -224,6 +224,7 @@ export function AppLayout() {
       actionUrl: GITHUB_REPO_URL,
       entityType: 'support',
       entityId: 'github-star',
+      dedupKey: 'support:github-star',
     }).then(() => {
       void useAppStore.getState().loadNotifications()
     }).catch(() => {})

package/src/components/shared/command-palette.tsx

@@ -2,6 +2,7 @@
 
 import { useState, useEffect, useCallback, useMemo, useRef } from 'react'
 import { useAppStore } from '@/stores/use-app-store'
+import { isLocalhostBrowser, isVisibleSessionForViewer } from '@/lib/local-observability'
 import { toast } from 'sonner'
 
 interface CommandItem {
@@ -22,6 +23,7 @@ export function CommandPalette() {
 
   const agents = useAppStore((s) => s.agents)
   const sessions = useAppStore((s) => s.sessions)
+  const currentUser = useAppStore((s) => s.currentUser)
   const tasks = useAppStore((s) => s.tasks)
   const setCurrentAgent = useAppStore((s) => s.setCurrentAgent)
   const setCurrentSession = useAppStore((s) => s.setCurrentSession)
@@ -149,6 +151,7 @@ export function CommandPalette() {
 
     // Chats (sessions)
     for (const session of Object.values(sessions)) {
+      if (!isVisibleSessionForViewer(session, currentUser, { localhost: isLocalhostBrowser() })) continue
       const sessionAgent = session.agentId ? agents[session.agentId] : null
       result.push({
         id: `chat:${session.id}`,
@@ -174,7 +177,7 @@ export function CommandPalette() {
     }
 
     return result
-  }, [agents, openSettingsSection, sessions, setActiveView, setCurrentAgent, setCurrentSession, setEditingTaskId, setTaskSheetOpen, tasks])
+  }, [agents, currentUser, openSettingsSection, sessions, setActiveView, setCurrentAgent, setCurrentSession, setEditingTaskId, setTaskSheetOpen, tasks])
 
   const filtered = useMemo(() => {
     if (!query.trim()) return items.slice(0, 20)

package/src/components/shared/notification-center.tsx

@@ -5,6 +5,7 @@ import { createPortal } from 'react-dom'
 import type { CSSProperties } from 'react'
 import { useAppStore } from '@/stores/use-app-store'
 import { useWs } from '@/hooks/use-ws'
+import { getNotificationActivityAt, getNotificationOccurrenceCount } from '@/lib/notification-utils'
 import type { AppNotification } from '@/types'
 
 function timeAgo(ts: number): string {
@@ -207,7 +208,12 @@ export function NotificationCenter({
                 <div className="flex-1 min-w-0">
                   <div className="flex items-center gap-2">
                     <span className="text-[12px] font-600 text-text truncate flex-1">{n.title}</span>
-                    <span className="text-[10px] text-text-3/50 shrink-0">{timeAgo(n.createdAt)}</span>
+                    {getNotificationOccurrenceCount(n) > 1 && (
+                      <span className="shrink-0 rounded-full border border-white/[0.08] bg-white/[0.04] px-1.5 py-0.5 text-[9px] font-600 text-text-3/80">
+                        x{getNotificationOccurrenceCount(n)}
+                      </span>
+                    )}
+                    <span className="text-[10px] text-text-3/50 shrink-0">{timeAgo(getNotificationActivityAt(n))}</span>
                   </div>
                   {n.message && (
                     <p className="text-[11px] text-text-3 mt-0.5 leading-relaxed line-clamp-2 m-0">

package/src/components/shared/search-dialog.tsx

@@ -4,6 +4,7 @@ import { useState, useEffect, useRef, useCallback } from 'react'
 import { Dialog, DialogContent, DialogTitle } from '@/components/ui/dialog'
 import { useAppStore } from '@/stores/use-app-store'
 import { api } from '@/lib/api-client'
+import { isLocalhostBrowser, isVisibleSessionForViewer } from '@/lib/local-observability'
 import type { AppView } from '@/types'
 
 interface SearchResult {
@@ -61,6 +62,8 @@ export function SearchDialog() {
   const debounceRef = useRef<ReturnType<typeof setTimeout> | null>(null)
   const listRef = useRef<HTMLDivElement>(null)
 
+  const sessions = useAppStore((s) => s.sessions)
+  const currentUser = useAppStore((s) => s.currentUser)
   const setActiveView = useAppStore((s) => s.setActiveView)
   const setSidebarOpen = useAppStore((s) => s.setSidebarOpen)
   const setEditingAgentId = useAppStore((s) => s.setEditingAgentId)
@@ -114,14 +117,19 @@ export function SearchDialog() {
     setLoading(true)
     try {
       const data = await api<{ results: SearchResult[] }>('GET', `/search?q=${encodeURIComponent(q)}`)
-      setResults(data.results)
+      setResults(data.results.filter((result) => {
+        if (result.type !== 'session' && result.type !== 'message') return true
+        const session = sessions[result.id]
+        if (!session) return true
+        return isVisibleSessionForViewer(session, currentUser, { localhost: isLocalhostBrowser() })
+      }))
       setSelectedIdx(0)
     } catch {
       setResults([])
     } finally {
       setLoading(false)
     }
-  }, [])
+  }, [currentUser, sessions])
 
   const handleQueryChange = (value: string) => {
     setQuery(value)

package/src/lib/local-observability.test.ts

@@ -0,0 +1,73 @@
+import assert from 'node:assert/strict'
+import { afterEach, describe, it } from 'node:test'
+
+import type { Session } from '@/types'
+
+import {
+  findLatestObservablePlatformSession,
+  isLocalhostBrowser,
+  isVisibleSessionForViewer,
+} from './local-observability'
+
+const originalWindow = globalThis.window
+
+function makeSession(overrides: Partial<Session>): Session {
+  return {
+    id: overrides.id || 'session-test',
+    name: overrides.name || 'Test Session',
+    user: overrides.user || 'default',
+    messages: overrides.messages || [],
+    createdAt: overrides.createdAt || 1,
+    updatedAt: overrides.updatedAt || overrides.createdAt || 1,
+    lastActiveAt: overrides.lastActiveAt || overrides.updatedAt || overrides.createdAt || 1,
+    provider: overrides.provider || 'openai',
+    model: overrides.model || 'gpt-test',
+    ...overrides,
+  } as Session
+}
+
+afterEach(() => {
+  if (originalWindow === undefined) {
+    delete (globalThis as { window?: Window }).window
+    return
+  }
+  globalThis.window = originalWindow
+})
+
+describe('local observability', () => {
+  it('shows observable platform sessions only on localhost', () => {
+    const workbench = makeSession({ id: 'wb-1', user: 'workbench' })
+    const swarm = makeSession({ id: 'sw-1', user: 'swarm' })
+    const mine = makeSession({ id: 'me-1', user: 'wayde' })
+
+    assert.equal(isVisibleSessionForViewer(workbench, 'wayde', { localhost: false }), false)
+    assert.equal(isVisibleSessionForViewer(workbench, 'wayde', { localhost: true }), true)
+    assert.equal(isVisibleSessionForViewer(swarm, 'wayde', { localhost: false }), true)
+    assert.equal(isVisibleSessionForViewer(mine, 'wayde', { localhost: false }), true)
+  })
+
+  it('prefers the latest live observable platform session for an agent', () => {
+    const sessions: Record<string, Session> = {
+      old: makeSession({ id: 'old', agentId: 'agent-1', user: 'workbench', lastActiveAt: 100 }),
+      shortcut: makeSession({
+        id: 'shortcut',
+        agentId: 'agent-1',
+        user: 'workbench',
+        lastActiveAt: 500,
+        shortcutForAgentId: 'agent-1',
+      }),
+      latest: makeSession({ id: 'latest', agentId: 'agent-1', user: 'comparison-bench', lastActiveAt: 300 }),
+      otherAgent: makeSession({ id: 'other', agentId: 'agent-2', user: 'workbench', lastActiveAt: 999 }),
+    }
+
+    assert.equal(findLatestObservablePlatformSession(sessions, 'agent-1')?.id, 'latest')
+  })
+
+  it('detects localhost browser hosts', () => {
+    globalThis.window = { location: { hostname: 'localhost' } } as Window
+    assert.equal(isLocalhostBrowser(), true)
+
+    globalThis.window = { location: { hostname: 'swarmclaw.ai' } } as Window
+    assert.equal(isLocalhostBrowser(), false)
+  })
+})

package/src/lib/local-observability.ts

@@ -0,0 +1,47 @@
+import type { Session } from '@/types'
+
+const LOCALHOST_HOSTNAMES = new Set(['localhost', '127.0.0.1', '::1', '0.0.0.0'])
+const OBSERVABLE_PLATFORM_SESSION_OWNERS = new Set(['workbench', 'comparison-bench'])
+const VISIBLE_NON_USER_SESSION_OWNERS = new Set(['system', 'connector', 'swarm'])
+
+function normalizeHostname(hostname: string): string {
+  return hostname.trim().toLowerCase().replace(/^\[(.*)\]$/, '$1')
+}
+
+export function isLocalhostBrowser(): boolean {
+  if (typeof window === 'undefined') return false
+  return LOCALHOST_HOSTNAMES.has(normalizeHostname(window.location.hostname))
+}
+
+export function isObservablePlatformSessionOwner(user: string | null | undefined): boolean {
+  const normalized = typeof user === 'string' ? user.trim().toLowerCase() : ''
+  return OBSERVABLE_PLATFORM_SESSION_OWNERS.has(normalized)
+}
+
+export function isVisibleSessionForViewer(
+  session: Session,
+  currentUser: string | null | undefined,
+  options?: { localhost?: boolean },
+): boolean {
+  const owner = (session.user || '').trim().toLowerCase()
+  if (!owner) return true
+  if (currentUser && owner === currentUser.trim().toLowerCase()) return true
+  if (VISIBLE_NON_USER_SESSION_OWNERS.has(owner)) return true
+  return options?.localhost === true && isObservablePlatformSessionOwner(owner)
+}
+
+export function findLatestObservablePlatformSession(
+  sessions: Record<string, Session>,
+  agentId: string,
+): Session | null {
+  let latest: Session | null = null
+  for (const session of Object.values(sessions)) {
+    if (session.agentId !== agentId) continue
+    if (!isObservablePlatformSessionOwner(session.user)) continue
+    if (session.shortcutForAgentId) continue
+    if (!latest || (session.lastActiveAt || session.createdAt || 0) > (latest.lastActiveAt || latest.createdAt || 0)) {
+      latest = session
+    }
+  }
+  return latest
+}

package/src/lib/notification-utils.test.ts

@@ -0,0 +1,72 @@
+import assert from 'node:assert/strict'
+import { describe, it } from 'node:test'
+
+import {
+  getNotificationActivityAt,
+  getNotificationOccurrenceCount,
+  upsertNotificationRecord,
+} from './notification-utils'
+
+describe('notification utils', () => {
+  it('creates fresh notifications with a count and activity timestamp', () => {
+    const { created, notification } = upsertNotificationRecord(
+      null,
+      {
+        type: 'info',
+        title: 'Provider unreachable',
+        message: 'Gateway timeout',
+        dedupKey: 'provider-down:test',
+      },
+      {
+        now: 1_700_000_000_000,
+        createId: () => 'notif_1',
+      },
+    )
+
+    assert.equal(created, true)
+    assert.equal(notification.id, 'notif_1')
+    assert.equal(notification.read, false)
+    assert.equal(notification.createdAt, 1_700_000_000_000)
+    assert.equal(notification.updatedAt, 1_700_000_000_000)
+    assert.equal(notification.occurrenceCount, 1)
+  })
+
+  it('refreshes an existing notification instead of duplicating it', () => {
+    const { created, notification } = upsertNotificationRecord(
+      {
+        id: 'notif_existing',
+        type: 'warning',
+        title: 'Provider unreachable',
+        message: 'Old failure',
+        dedupKey: 'provider-down:test',
+        read: true,
+        createdAt: 1_700_000_000_000,
+      },
+      {
+        type: 'warning',
+        title: 'Provider unreachable',
+        message: 'Still down',
+        dedupKey: 'provider-down:test',
+      },
+      {
+        now: 1_700_000_123_000,
+        createId: () => 'unused',
+      },
+    )
+
+    assert.equal(created, false)
+    assert.equal(notification.id, 'notif_existing')
+    assert.equal(notification.read, false)
+    assert.equal(notification.createdAt, 1_700_000_000_000)
+    assert.equal(notification.updatedAt, 1_700_000_123_000)
+    assert.equal(notification.occurrenceCount, 2)
+    assert.equal(notification.message, 'Still down')
+  })
+
+  it('prefers updatedAt when sorting and formatting activity', () => {
+    assert.equal(getNotificationActivityAt({ createdAt: 100, updatedAt: 250 }), 250)
+    assert.equal(getNotificationActivityAt({ createdAt: 100 }), 100)
+    assert.equal(getNotificationOccurrenceCount({ occurrenceCount: 4 }), 4)
+    assert.equal(getNotificationOccurrenceCount({ occurrenceCount: 0 }), 1)
+  })
+})

package/src/lib/notification-utils.ts

@@ -0,0 +1,68 @@
+import type { AppNotification } from '@/types'
+
+export type NotificationDraft = Pick<
+  AppNotification,
+  'type' | 'title' | 'message' | 'actionLabel' | 'actionUrl' | 'entityType' | 'entityId' | 'dedupKey'
+>
+
+export function getNotificationActivityAt(
+  notification: Pick<AppNotification, 'createdAt' | 'updatedAt'>,
+): number {
+  return typeof notification.updatedAt === 'number' ? notification.updatedAt : notification.createdAt
+}
+
+export function getNotificationOccurrenceCount(
+  notification: Pick<AppNotification, 'occurrenceCount'>,
+): number {
+  return typeof notification.occurrenceCount === 'number' && notification.occurrenceCount > 1
+    ? notification.occurrenceCount
+    : 1
+}
+
+export function upsertNotificationRecord(
+  existing: AppNotification | null | undefined,
+  draft: NotificationDraft,
+  options: {
+    now: number
+    createId: () => string
+  },
+): { notification: AppNotification; created: boolean } {
+  if (existing) {
+    return {
+      created: false,
+      notification: {
+        ...existing,
+        type: draft.type,
+        title: draft.title,
+        message: draft.message,
+        actionLabel: draft.actionLabel,
+        actionUrl: draft.actionUrl,
+        entityType: draft.entityType,
+        entityId: draft.entityId,
+        dedupKey: draft.dedupKey,
+        read: false,
+        updatedAt: options.now,
+        occurrenceCount: getNotificationOccurrenceCount(existing) + 1,
+      },
+    }
+  }
+
+  return {
+    created: true,
+    notification: {
+      id: options.createId(),
+      type: draft.type,
+      title: draft.title,
+      message: draft.message,
+      actionLabel: draft.actionLabel,
+      actionUrl: draft.actionUrl,
+      entityType: draft.entityType,
+      entityId: draft.entityId,
+      dedupKey: draft.dedupKey,
+      read: false,
+      createdAt: options.now,
+      updatedAt: options.now,
+      occurrenceCount: 1,
+    },
+  }
+}

package/src/lib/providers/openclaw.test.ts

@@ -1,7 +1,7 @@
 import assert from 'node:assert/strict'
 import { afterEach, test } from 'node:test'
 
-import { resolveGatewayAgentId } from './openclaw'
+import { buildOpenClawSessionKey, resolveGatewayAgentId } from './openclaw'
 import { loadAgents, saveAgents } from '../server/storage'
 import type { Agent } from '@/types'
 
@@ -52,3 +52,23 @@ test('resolveGatewayAgentId falls back to the session name when no OpenClaw agen
 
   assert.equal(resolved, 'fallback-agent-name')
 })
+
+test('buildOpenClawSessionKey namespaces sessions by agent and local session id', () => {
+  const sessionKey = buildOpenClawSessionKey({
+    id: 'cmp-session-1',
+    agentId: 'openclaw-agent-test',
+    name: 'Ignored Name',
+  }, 'Research Operator')
+
+  assert.equal(sessionKey, 'agent:research-operator:swarm:cmp-session-1')
+})
+
+test('buildOpenClawSessionKey honors explicit OpenClaw session keys when provided', () => {
+  const sessionKey = buildOpenClawSessionKey({
+    id: 'cmp-session-2',
+    name: 'Ignored Name',
+    openclawSessionKey: 'agent:ops:benchmark:fixed-key',
+  })
+
+  assert.equal(sessionKey, 'agent:ops:benchmark:fixed-key')
+})

package/src/lib/providers/openclaw.ts

@@ -302,6 +302,25 @@ export function resolveGatewayAgentId(session: Record<string, unknown> & { id: s
   return 'main'
 }
 
+export function buildOpenClawSessionKey(
+  session: Record<string, unknown> & { id: string },
+  gatewayAgentId?: string,
+): string {
+  const explicit = typeof (session as { openclawSessionKey?: unknown }).openclawSessionKey === 'string'
+    ? String((session as { openclawSessionKey?: unknown }).openclawSessionKey).trim()
+    : ''
+  if (explicit) return explicit
+
+  const sessionId = typeof session.id === 'string' && session.id.trim()
+    ? session.id.trim()
+    : randomUUID()
+  const agentId = typeof gatewayAgentId === 'string' && gatewayAgentId.trim()
+    ? normalizeOpenClawAgentId(gatewayAgentId)
+    : resolveGatewayAgentId(session)
+
+  return `agent:${agentId}:swarm:${sessionId}`
+}
+
 async function rpcOnConnectedGateway(
   ws: InstanceType<typeof WebSocket>,
   method: string,
@@ -425,6 +444,7 @@ export function streamOpenClawChat({ session, message, imagePath, apiKey, write,
 
       const ws = result.ws
       const gatewayAgentId = await resolveConnectedGatewayAgentId(ws, session)
+      const sessionKey = buildOpenClawSessionKey(session, gatewayAgentId)
       const timeout = setTimeout(() => {
         ws.close()
         finish('OpenClaw gateway timed out after 120s.')
@@ -445,6 +465,8 @@ export function streamOpenClawChat({ session, message, imagePath, apiKey, write,
         params: {
           message: prompt,
           agentId: gatewayAgentId,
+          sessionKey,
+          label: typeof session.name === 'string' && session.name.trim() ? session.name.trim() : undefined,
           timeout: 120,
           idempotencyKey: randomUUID(),
         },