@swarmclawai/swarmclaw 1.2.4 → 1.2.6

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

@@ -1,14 +1,18 @@
 import fs from 'fs'
 import os from 'os'
 import path from 'path'
-import { loadSettings, loadSkills, loadCredentials, decryptKey, loadSessions, saveSessions } from '@/lib/server/storage'
 import { buildCurrentDateTimePromptContext } from '@/lib/server/prompt-runtime-context'
 import { buildIdentityContinuityContext } from '@/lib/server/identity-continuity'
 import { genId } from '@/lib/id'
 import { WORKSPACE_DIR } from '@/lib/server/data-dir'
 import { applyResolvedRoute, resolvePrimaryAgentRoute } from '@/lib/server/agents/agent-runtime-config'
+import { loadCredential, decryptKey } from '@/lib/server/credentials/credential-repository'
 import { resolveProviderApiEndpoint, resolveProviderCredentialId } from '@/lib/server/provider-endpoint'
+import { loadSettings } from '@/lib/server/settings/settings-repository'
 import { buildRuntimeSkillPromptBlocks, resolveRuntimeSkills } from '@/lib/server/skills/runtime-skill-resolver'
+import { loadSkills } from '@/lib/server/skills/skill-repository'
+import { loadSession, patchSession, saveSession } from '@/lib/server/sessions/session-repository'
+import { appendMessage } from '@/lib/server/messages/message-repository'
 import type { Chatroom, ChatroomMember, Agent, Session, Message, ChatroomMessage } from '@/types'
 import { getEnabledCapabilityIds, getEnabledToolIds } from '@/lib/capability-selection'
 
@@ -16,8 +20,7 @@ import { getEnabledCapabilityIds, getEnabledToolIds } from '@/lib/capability-sel
 export function resolveApiKey(credentialId: string | null | undefined): string | null {
   const resolvedCredentialId = resolveProviderCredentialId({ credentialId })
   if (!resolvedCredentialId) return null
-  const creds = loadCredentials()
-  const cred = creds[resolvedCredentialId]
+  const cred = loadCredential(resolvedCredentialId)
   if (!cred?.encryptedKey) return null
   try { return decryptKey(cred.encryptedKey) } catch { return null }
 }
@@ -136,6 +139,7 @@ export function parseMentions(
 
   // Check if the only explicit matches are the sender — if so, treat as "no explicit mentions"
   const senderId = opts?.senderId
+  const explicitSelfMentioned = senderId ? mentioned.includes(senderId) : false
   const explicitNonSelf = senderId ? mentioned.filter((id) => id !== senderId) : mentioned
 
   // 2. Reply-based implicit mention
@@ -158,8 +162,9 @@ export function parseMentions(
     }
   }
 
-  // Remove self from final list when senderId is provided
-  return senderId ? mentioned.filter((mid) => mid !== senderId) : mentioned
+  // Preserve explicit self-mentions so agents can intentionally address themselves.
+  if (!senderId || explicitSelfMentioned) return mentioned
+  return mentioned.filter((mid) => mid !== senderId)
 }
 
 export function resolveReplyTargetAgentId(
@@ -312,9 +317,8 @@ export function ensureSyntheticSession(agent: Agent, chatroomId: string): Sessio
   const roomWorkspace = resolveChatroomWorkspaceDir(chatroomId)
   fs.mkdirSync(roomWorkspace, { recursive: true })
   const sessionId = resolveSyntheticSessionId(chatroomId, agent.id)
-  const sessions = loadSessions()
   const now = Date.now()
-  const existing = sessions[sessionId]
+  const existing = loadSession(sessionId)
   const session: Session = existing
     ? applyResolvedRoute({
         ...existing,
@@ -348,8 +352,7 @@ export function ensureSyntheticSession(agent: Agent, chatroomId: string): Sessio
   }
   if (session.codexThreadId === undefined) session.codexThreadId = null
   if (session.opencodeSessionId === undefined) session.opencodeSessionId = null
-  sessions[sessionId] = session
-  saveSessions(sessions)
+  saveSession(sessionId, session)
   return session
 }
 
@@ -360,18 +363,16 @@ export function appendSyntheticSessionMessage(
 ): void {
   const trimmed = String(text || '').trim()
   if (!trimmed) return
-  const sessions = loadSessions()
-  const session = sessions[sessionId]
-  if (!session) return
-  if (!Array.isArray(session.messages)) session.messages = []
-  session.messages.push({
+  const timestamp = Date.now()
+  appendMessage(sessionId, {
     role,
     text: trimmed,
-    time: Date.now(),
+    time: timestamp,
+  })
+  patchSession(sessionId, (current) => {
+    if (!current) return null
+    return { ...current, lastActiveAt: timestamp }
   })
-  session.lastActiveAt = Date.now()
-  sessions[sessionId] = session
-  saveSessions(sessions)
 }
 
 /** Build agent's system prompt including skills and identity context */

package/src/lib/server/chatrooms/chatroom-repository.ts

@@ -1,10 +1,13 @@
 import type { Chatroom } from '@/types'
 
 import {
+  deleteStoredItem,
   loadChatroom as loadStoredChatroom,
   loadChatrooms as loadStoredChatrooms,
+  patchStoredItem,
   saveChatrooms as saveStoredChatrooms,
   upsertChatroom as upsertStoredChatroom,
+  upsertStoredItems,
 } from '@/lib/server/storage'
 import { createRecordRepository } from '@/lib/server/persistence/repository-utils'
 
@@ -20,13 +23,26 @@ export const chatroomRepository = createRecordRepository<Chatroom>(
     upsert(id, value) {
       upsertStoredChatroom(id, value as Chatroom)
     },
+    upsertMany(entries) {
+      upsertStoredItems('chatrooms', entries as Array<[string, Chatroom]>)
+    },
+    patch(id, updater) {
+      return patchStoredItem('chatrooms', id, updater as (current: Chatroom | null) => Chatroom | null) as Chatroom | null
+    },
     replace(data) {
       saveStoredChatrooms(data)
     },
+    delete(id) {
+      deleteStoredItem('chatrooms', id)
+    },
   },
 )
 
 export const loadChatrooms = () => chatroomRepository.list()
 export const loadChatroom = (id: string) => chatroomRepository.get(id)
+export const loadChatroomMany = (ids: string[]) => chatroomRepository.getMany(ids)
 export const saveChatrooms = (items: Record<string, Chatroom | Record<string, unknown>>) => chatroomRepository.replace(items as Record<string, Chatroom>)
 export const upsertChatroom = (id: string, value: Chatroom | Record<string, unknown>) => chatroomRepository.upsert(id, value as Chatroom)
+export const upsertChatrooms = (entries: Array<[string, Chatroom | Record<string, unknown>]>) => chatroomRepository.upsertMany(entries as Array<[string, Chatroom]>)
+export const patchChatroom = (id: string, updater: (current: Chatroom | null) => Chatroom | null) => chatroomRepository.patch(id, updater)
+export const deleteChatroom = (id: string) => chatroomRepository.delete(id)

package/src/lib/server/chatrooms/chatroom-routing.test.ts

@@ -0,0 +1,96 @@
+import assert from 'node:assert/strict'
+import { test } from 'node:test'
+import type { Agent, Chatroom } from '@/types'
+import {
+  ensureChatroomRoutingGuidance,
+  selectChatroomRecipients,
+  synthesizeRoutingGuidanceFromRules,
+} from './chatroom-routing'
+
+const agents: Record<string, Agent> = {
+  ops: {
+    id: 'ops',
+    name: 'Ops',
+    description: 'Handles deploys and infrastructure',
+    provider: 'openai',
+    model: 'gpt-test',
+    systemPrompt: '',
+    capabilities: ['deploy', 'infrastructure'],
+  },
+  design: {
+    id: 'design',
+    name: 'Design',
+    description: 'Handles design critique and UI polish',
+    provider: 'openai',
+    model: 'gpt-test',
+    systemPrompt: '',
+    capabilities: ['design', 'ui'],
+  },
+}
+
+function makeChatroom(overrides: Partial<Chatroom> = {}): Chatroom {
+  return {
+    id: 'room-1',
+    name: 'Test Room',
+    description: 'General routing test room',
+    agentIds: ['ops', 'design'],
+    messages: [],
+    createdAt: 1,
+    updatedAt: 1,
+    ...overrides,
+  }
+}
+
+test('synthesizes guidance from legacy routing rules and migrates the chatroom', () => {
+  const chatroom = makeChatroom({
+    routingRules: [
+      { id: 'rule-1', type: 'keyword', keywords: ['deploy', 'release'], agentId: 'ops', priority: 1 },
+      { id: 'rule-2', type: 'capability', pattern: 'design review', agentId: 'design', priority: 2 },
+    ],
+  })
+
+  const guidance = synthesizeRoutingGuidanceFromRules(chatroom.routingRules, agents)
+  assert.match(String(guidance || ''), /deploy/i)
+  assert.match(String(guidance || ''), /Design/i)
+
+  const changed = ensureChatroomRoutingGuidance(chatroom, agents)
+  assert.equal(changed, true)
+  assert.equal(typeof chatroom.routingGuidance, 'string')
+  assert.equal(chatroom.routingRules, undefined)
+})
+
+test('selects only member ids returned by the selector model', async () => {
+  const chatroom = makeChatroom({
+    routingGuidance: 'Route deployment incidents to Ops. Prefer Design for UI critique.',
+  })
+
+  const selected = await selectChatroomRecipients({
+    text: 'Please diagnose the failed deployment.',
+    chatroom,
+    agentsById: agents,
+  }, {
+    generateText: async () => '{"agentIds":["ops","non-member","ops"]}',
+  })
+
+  assert.deepEqual(selected, ['ops'])
+})
+
+test('fails open to no inferred mentions when there is no guidance or the selector output is invalid', async () => {
+  const unguided = await selectChatroomRecipients({
+    text: 'Anyone here?',
+    chatroom: makeChatroom(),
+    agentsById: agents,
+  }, {
+    generateText: async () => '{"agentIds":["ops"]}',
+  })
+  assert.deepEqual(unguided, [])
+
+  const invalid = await selectChatroomRecipients({
+    text: 'Please review the new layout.',
+    chatroom: makeChatroom({ routingGuidance: 'Prefer Design for UI review.' }),
+    agentsById: agents,
+  }, {
+    generateText: async () => 'not-json',
+  })
+  assert.deepEqual(invalid, [])
+})

package/src/lib/server/chatrooms/chatroom-routing.ts

@@ -1,66 +1,220 @@
-import type { ChatroomRoutingRule, Agent } from '@/types'
-import { matchesCapabilities } from '@/lib/server/agents/capability-match'
+import { HumanMessage } from '@langchain/core/messages'
+import type { Agent, Chatroom, ChatroomRoutingRule } from '@/types'
+import { buildLLM } from '@/lib/server/build-llm'
+import { log } from '@/lib/server/logger'
 
-/**
- * Evaluate routing rules against inbound message text.
- *
- * Rules are evaluated in priority order (lower number = higher priority).
- * First match wins — returns the matched agentIds.
- *
- * - 'keyword' rules: case-insensitive substring match against `keywords[]`,
- *   or regex match against `pattern`.
- * - 'capability' rules: match `pattern` against each agent's `capabilities[]`.
- */
-export function evaluateRoutingRules(
-  text: string,
-  rules: ChatroomRoutingRule[],
-  agents: Agent[],
-): string[] {
-  if (!rules.length) return []
+const TAG = 'chatroom-routing'
+const SELECTOR_TIMEOUT_MS = 4_000
 
-  const sorted = [...rules].sort((a, b) => a.priority - b.priority)
-  const lowerText = text.toLowerCase()
+interface ChatroomRecipientSelection {
+  agentIds: string[]
+}
 
-  for (const rule of sorted) {
-    if (rule.type === 'keyword') {
-      let matched = false
+function normalizeGuidance(value: string | null | undefined): string | null {
+  const trimmed = typeof value === 'string' ? value.trim() : ''
+  return trimmed || null
+}
 
-      // Check keywords (case-insensitive substring)
-      if (rule.keywords?.length) {
-        matched = rule.keywords.some((kw) => lowerText.includes(kw.toLowerCase()))
+function extractFirstJsonObject(text: string): string | null {
+  const source = String(text || '').trim()
+  if (!source) return null
+  let start = -1
+  let depth = 0
+  let inString = false
+  let escaped = false
+  for (let index = 0; index < source.length; index += 1) {
+    const char = source[index]
+    if (start === -1) {
+      if (char === '{') {
+        start = index
+        depth = 1
       }
+      continue
+    }
+    if (inString) {
+      if (escaped) escaped = false
+      else if (char === '\\') escaped = true
+      else if (char === '"') inString = false
+      continue
+    }
+    if (char === '"') {
+      inString = true
+      continue
+    }
+    if (char === '{') depth += 1
+    else if (char === '}') depth -= 1
+    if (depth === 0) return source.slice(start, index + 1)
+  }
+  return null
+}
 
-      // Check pattern (regex)
-      if (!matched && rule.pattern) {
-        try {
-          const re = new RegExp(rule.pattern, 'i')
-          matched = re.test(text)
-        } catch {
-          // Invalid regex — skip
-        }
-      }
+function extractModelText(content: unknown): string {
+  if (typeof content === 'string') return content
+  if (!Array.isArray(content)) return ''
+  return content
+    .map((part) => (part && typeof part === 'object' && 'text' in part && typeof part.text === 'string') ? part.text : '')
+    .join('')
+}
 
-      if (matched) return [rule.agentId]
+function parseRecipientSelection(text: string, allowedAgentIds: Set<string>): string[] {
+  const jsonText = extractFirstJsonObject(text)
+  if (!jsonText) return []
+  try {
+    const parsed = JSON.parse(jsonText) as Partial<ChatroomRecipientSelection>
+    if (!Array.isArray(parsed.agentIds)) return []
+    const seen = new Set<string>()
+    const selected: string[] = []
+    for (const value of parsed.agentIds) {
+      if (typeof value !== 'string') continue
+      const agentId = value.trim()
+      if (!agentId || !allowedAgentIds.has(agentId) || seen.has(agentId)) continue
+      seen.add(agentId)
+      selected.push(agentId)
     }
+    return selected
+  } catch {
+    return []
+  }
+}
+
+function formatLegacyRule(rule: ChatroomRoutingRule, agentsById: Record<string, Agent | undefined>): string | null {
+  const agentName = agentsById[rule.agentId]?.name || rule.agentId
+  if (rule.type === 'keyword') {
+    const parts = [
+      Array.isArray(rule.keywords) && rule.keywords.length > 0
+        ? `topics or phrases like ${rule.keywords.map((keyword) => `"${keyword}"`).join(', ')}`
+        : null,
+      rule.pattern ? `messages matching ${JSON.stringify(rule.pattern)}` : null,
+    ].filter(Boolean)
+    if (parts.length === 0) return null
+    return `Priority ${rule.priority}: route ${parts.join(' or ')} to ${agentName}.`
+  }
+  if (!rule.pattern) return null
+  return `Priority ${rule.priority}: prefer ${agentName} when the request best fits capability area ${JSON.stringify(rule.pattern)}.`
+}
+
+export function synthesizeRoutingGuidanceFromRules(
+  rules: ChatroomRoutingRule[] | null | undefined,
+  agentsById: Record<string, Agent | undefined>,
+): string | null {
+  if (!Array.isArray(rules) || rules.length === 0) return null
+  const lines = rules
+    .slice()
+    .sort((a, b) => a.priority - b.priority)
+    .map((rule) => formatLegacyRule(rule, agentsById))
+    .filter((line): line is string => typeof line === 'string' && line.trim().length > 0)
+  if (lines.length === 0) return null
+  return [
+    'Legacy routing guidance synthesized from older routing rules. Earlier priorities take precedence when multiple agents could fit.',
+    ...lines,
+  ].join('\n')
+}
 
-    if (rule.type === 'capability') {
-      if (!rule.pattern) continue
-      const patternLower = rule.pattern.toLowerCase()
+export function resolveChatroomRoutingGuidance(
+  chatroom: Chatroom,
+  agentsById: Record<string, Agent | undefined>,
+): string | null {
+  return normalizeGuidance(chatroom.routingGuidance)
+    || synthesizeRoutingGuidanceFromRules(chatroom.routingRules, agentsById)
+}
 
-      // Check if the specific agent has a matching capability
-      const agent = agents.find((a) => a.id === rule.agentId)
-      if (agent && matchesCapabilities(agent.capabilities, [rule.pattern])) {
-        // Only match if the message text is relevant to the capability
-        // Use the pattern as a keyword match against the message text too
-        try {
-          const re = new RegExp(rule.pattern, 'i')
-          if (re.test(text)) return [rule.agentId]
-        } catch {
-          if (lowerText.includes(patternLower)) return [rule.agentId]
-        }
+export function ensureChatroomRoutingGuidance(
+  chatroom: Chatroom,
+  agentsById: Record<string, Agent | undefined>,
+): boolean {
+  const guidance = resolveChatroomRoutingGuidance(chatroom, agentsById)
+  const nextGuidance = normalizeGuidance(guidance)
+  const hadRules = Array.isArray(chatroom.routingRules) && chatroom.routingRules.length > 0
+  const guidanceChanged = nextGuidance !== normalizeGuidance(chatroom.routingGuidance)
+  if (!guidanceChanged && !hadRules) return false
+  chatroom.routingGuidance = nextGuidance
+  delete chatroom.routingRules
+  return guidanceChanged || hadRules
+}
+
+function buildRecipientSelectionPrompt(params: {
+  text: string
+  chatroom: Chatroom
+  guidance: string
+  members: Array<{
+    id: string
+    name: string
+    description: string
+    capabilities: string[]
+  }>
+}): string {
+  return [
+    'Choose which chatroom members should receive the latest message.',
+    'Return JSON only.',
+    'Use only agent IDs from the provided member list.',
+    'Prefer the smallest relevant set. Return an empty array when no routing guidance clearly applies.',
+    'Respect explicit routing guidance over generic capability overlap.',
+    '',
+    'Output shape:',
+    '{"agentIds":["agent-id-1","agent-id-2"]}',
+    '',
+    `Chatroom description: ${JSON.stringify(params.chatroom.description || '')}`,
+    `Routing guidance: ${JSON.stringify(params.guidance)}`,
+    `Latest message: ${JSON.stringify(params.text)}`,
+    'Members:',
+    JSON.stringify(params.members),
+  ].join('\n')
+}
+
+export async function selectChatroomRecipients(
+  params: {
+    text: string
+    chatroom: Chatroom
+    agentsById: Record<string, Agent | undefined>
+  },
+  hooks?: {
+    generateText?: (prompt: string) => Promise<string>
+  },
+): Promise<string[]> {
+  const guidance = resolveChatroomRoutingGuidance(params.chatroom, params.agentsById)
+  if (!guidance) return []
+
+  const members = params.chatroom.agentIds
+    .map((agentId) => {
+      const agent = params.agentsById[agentId]
+      if (!agent) return null
+      return {
+        id: agent.id,
+        name: agent.name,
+        description: agent.description || '',
+        capabilities: Array.isArray(agent.capabilities) ? agent.capabilities.slice(0, 12) : [],
       }
-    }
-  }
+    })
+    .filter((member): member is NonNullable<typeof member> => member !== null)
+  if (members.length === 0) return []
+
+  const prompt = buildRecipientSelectionPrompt({
+    text: params.text,
+    chatroom: params.chatroom,
+    guidance,
+    members,
+  })
+  const allowedAgentIds = new Set(members.map((member) => member.id))
 
-  return []
+  try {
+    const responseText = await Promise.race([
+      hooks?.generateText
+        ? hooks.generateText(prompt)
+        : (async () => {
+            const { llm } = await buildLLM()
+            const response = await llm.invoke([new HumanMessage(prompt)])
+            return extractModelText(response.content)
+          })(),
+      new Promise<never>((_, reject) => {
+        setTimeout(() => reject(new Error('chatroom-recipient-selector-timeout')), SELECTOR_TIMEOUT_MS)
+      }),
+    ])
+    return parseRecipientSelection(responseText, allowedAgentIds)
+  } catch (error: unknown) {
+    log.warn(TAG, 'Failed to select chatroom recipients from routing guidance', {
+      error: error instanceof Error ? error.message : 'unknown',
+      chatroomId: params.chatroom.id,
+    })
+    return []
+  }
 }

package/src/lib/server/chatrooms/mailbox-utils.ts

@@ -3,8 +3,10 @@ import path from 'path'
 import { ImapFlow } from 'imapflow'
 import { createTransport } from 'nodemailer'
 import { simpleParser } from 'mailparser'
-import { UPLOAD_DIR, loadConnectors } from '@/lib/server/storage'
+import type { Connector } from '@/types'
+import { loadConnectors } from '@/lib/server/connectors/connector-repository'
 import { getExtensionManager } from '@/lib/server/extensions'
+import { UPLOAD_DIR } from '@/lib/server/upload-path'
 
 export interface MailboxConfig {
   imapHost: string
@@ -79,7 +81,7 @@ export function getMailboxConfig(): MailboxConfig {
   const emailSettings = extensionManager.getExtensionSettings('email') as Record<string, unknown>
   const connectors = loadConnectors()
   const emailConnector = Object.values(connectors)
-    .find((entry) => entry && typeof entry === 'object' && String((entry as Record<string, unknown>).platform || '').toLowerCase() === 'email') as Record<string, unknown> | undefined
+    .find((entry) => entry.platform === 'email') as Connector | undefined
   const connectorConfig = emailConnector && typeof emailConnector.config === 'object' && emailConnector.config
     ? emailConnector.config as Record<string, unknown>
     : {}

package/src/lib/server/chatrooms/session-mailbox.ts

@@ -1,6 +1,6 @@
 import { genId } from '@/lib/id'
 import type { MailboxEnvelope } from '@/types'
-import { loadSessions, saveSessions } from '@/lib/server/storage'
+import { loadSession, patchSession } from '@/lib/server/sessions/session-repository'
 import { requestMissionTicksForHumanReply } from '@/lib/server/missions/mission-service'
 
 interface MailboxOptions {
@@ -83,9 +83,8 @@ function normalizeMailbox(target: { mailbox?: MailboxEnvelope[] | null }, now =
 
 function findLatestPendingHumanRequestEnvelope(
   sessionId: string,
-  sessions = loadSessions(),
+  target = loadSession(sessionId),
 ): MailboxEnvelope | null {
-  const target = sessions[sessionId]
   if (!target) throw new Error(`Session not found: ${sessionId}`)
   const envelopes = normalizeMailbox(target)
   const repliedCorrelationIds = new Set(
@@ -108,8 +107,7 @@ export function findPendingHumanRequestEnvelope(params: {
   fromSessionId?: string | null
   fromAgentId?: string | null
 }): MailboxEnvelope | null {
-  const sessions = loadSessions()
-  const target = sessions[params.sessionId]
+  const target = loadSession(params.sessionId)
   if (!target) throw new Error(`Session not found: ${params.sessionId}`)
   const expectedSignature = normalizeHumanRequestSignature(params)
   const envelopes = normalizeMailbox(target)
@@ -139,8 +137,7 @@ export function sendMailboxEnvelope(input: {
   correlationId?: string | null
   ttlSec?: number | null
 }): MailboxEnvelope {
-  const sessions = loadSessions()
-  const target = sessions[input.toSessionId]
+  const target = loadSession(input.toSessionId)
   if (!target) throw new Error(`Target session not found: ${input.toSessionId}`)
 
   const now = Date.now()
@@ -162,12 +159,14 @@ export function sendMailboxEnvelope(input: {
     ackAt: null,
   }
 
-  const existing = normalizeMailbox(target, now)
-  existing.push(envelope)
-  target.mailbox = existing
-  target.lastActiveAt = now
-  sessions[input.toSessionId] = target
-  saveSessions(sessions)
+  patchSession(input.toSessionId, (current) => {
+    if (!current) return null
+    return {
+      ...current,
+      mailbox: [...normalizeMailbox(current, now), envelope],
+      lastActiveAt: now,
+    }
+  })
   if (envelope.type === 'human_reply') {
     requestMissionTicksForHumanReply({
       sessionId: input.toSessionId,
@@ -188,8 +187,7 @@ export function sendMailboxEnvelope(input: {
 }
 
 export function listMailbox(sessionId: string, opts: MailboxOptions = {}): MailboxEnvelope[] {
-  const sessions = loadSessions()
-  const target = sessions[sessionId]
+  const target = loadSession(sessionId)
   if (!target) throw new Error(`Session not found: ${sessionId}`)
   const list = pruneExpired(normalizeMailboxList(target.mailbox || []))
   const includeAcked = opts.includeAcked === true
@@ -201,36 +199,48 @@ export function listMailbox(sessionId: string, opts: MailboxOptions = {}): Mailb
 }
 
 export function ackMailboxEnvelope(sessionId: string, envelopeId: string): MailboxEnvelope | null {
-  const sessions = loadSessions()
-  const target = sessions[sessionId]
+  const target = loadSession(sessionId)
   if (!target) throw new Error(`Session not found: ${sessionId}`)
-  const list = normalizeMailbox(target)
-  const idx = list.findIndex((env) => env.id === envelopeId)
-  if (idx === -1) return null
-  list[idx] = {
-    ...list[idx],
-    status: 'ack',
-    ackAt: Date.now(),
-  }
-  target.mailbox = list
-  target.lastActiveAt = Date.now()
-  sessions[sessionId] = target
-  saveSessions(sessions)
-  return list[idx]
+  const ackAt = Date.now()
+  let acked: MailboxEnvelope | null = null
+  patchSession(sessionId, (current) => {
+    if (!current) return null
+    const list = normalizeMailbox(current)
+    const idx = list.findIndex((env) => env.id === envelopeId)
+    if (idx === -1) return current
+    list[idx] = {
+      ...list[idx],
+      status: 'ack',
+      ackAt,
+    }
+    acked = list[idx]
+    return {
+      ...current,
+      mailbox: list,
+      lastActiveAt: ackAt,
+    }
+  })
+  return acked
 }
 
 export function clearMailbox(sessionId: string, includeAcked = true): { before: number; after: number } {
-  const sessions = loadSessions()
-  const target = sessions[sessionId]
+  const target = loadSession(sessionId)
   if (!target) throw new Error(`Session not found: ${sessionId}`)
-  const list = normalizeMailbox(target)
-  const before = list.length
-  const afterList = includeAcked ? [] : list.filter((env) => env.status !== 'ack')
-  target.mailbox = afterList
-  target.lastActiveAt = Date.now()
-  sessions[sessionId] = target
-  saveSessions(sessions)
-  return { before, after: afterList.length }
+  let before = 0
+  let after = 0
+  patchSession(sessionId, (current) => {
+    if (!current) return null
+    const list = normalizeMailbox(current)
+    const afterList = includeAcked ? [] : list.filter((env) => env.status !== 'ack')
+    before = list.length
+    after = afterList.length
+    return {
+      ...current,
+      mailbox: afterList,
+      lastActiveAt: Date.now(),
+    }
+  })
+  return { before, after }
 }
 
 export function bridgeHumanReplyFromChat(input: {