@swarmclawai/swarmclaw 0.8.4 → 0.8.7

package/src/lib/server/chat-streaming-utils.ts

@@ -0,0 +1,174 @@
+import type { MessageToolEvent } from '@/types'
+import { canonicalizePluginId } from './tool-aliases'
+import { extractSuggestions } from './suggestions'
+import { isDirectMemoryWriteRequest } from './memory-policy'
+import {
+  isBroadGoal,
+  looksLikeExternalWalletTask,
+  looksLikeOpenEndedDeliverableTask,
+} from './stream-continuation'
+
+export function getExplicitRequiredToolNames(userMessage: string, enabledPlugins: string[]): string[] {
+  const normalized = userMessage.toLowerCase()
+  const required: string[] = []
+  const hasEnabledTool = (toolId: string) => enabledPlugins.some((enabled) => (canonicalizePluginId(enabled) || enabled) === toolId)
+
+  if (hasEnabledTool('ask_human')
+    && (/\bask_human\b/.test(normalized) || /ask the human/.test(normalized) || /request_input/.test(normalized))) {
+    required.push('ask_human')
+  }
+
+  if (hasEnabledTool('email')
+    && (/\bemail\b/.test(normalized) || /send a welcome email/.test(normalized) || /send an email/.test(normalized))) {
+    required.push('email')
+  }
+
+  if (
+    hasEnabledTool('shell')
+    && (
+      /\bcurl request\b/.test(normalized)
+      || /\b(?:run|execute|do|use|try)\b[\s\S]{0,40}\bcurl\b/.test(normalized)
+      || /\brun (?:this )?command\b/.test(normalized)
+      || /\buse (?:the )?(?:shell|terminal)\b/.test(normalized)
+      || /\bin (?:the )?terminal\b/.test(normalized)
+    )
+  ) {
+    required.push('shell')
+  }
+
+  return required
+}
+
+export function shouldForceExternalServiceSummary(params: {
+  userMessage: string
+  finalResponse: string
+  hasToolCalls: boolean
+  toolEventCount: number
+}): boolean {
+  if (!looksLikeExternalWalletTask(params.userMessage)) return false
+  if (!params.hasToolCalls || params.toolEventCount === 0) return false
+  const trimmed = params.finalResponse.trim()
+  if (!trimmed) return true
+  if (/\b(blocker|blocked|cannot|can't|requires|need|missing|last reversible step|next step)\b/i.test(trimmed)) return false
+  if (trimmed.length >= 240 && !/(let me|i'll|i will|checking|verify|promising|look into|explore|access their interface)/i.test(trimmed)) return false
+  return /:$/.test(trimmed) || /(let me|i'll|i will|checking|verify|promising|look into|explore|access their interface)/i.test(trimmed) || trimmed.length < 240
+}
+
+export function resolveToolAction(input: unknown): string {
+  if (input && typeof input === 'object' && !Array.isArray(input)) {
+    const action = (input as Record<string, unknown>).action
+    return typeof action === 'string' ? action.trim().toLowerCase() : ''
+  }
+  if (typeof input !== 'string') return ''
+  const trimmed = input.trim()
+  if (!trimmed.startsWith('{')) return ''
+  try {
+    const parsed = JSON.parse(trimmed) as Record<string, unknown>
+    return typeof parsed.action === 'string' ? parsed.action.trim().toLowerCase() : ''
+  } catch {
+    return ''
+  }
+}
+
+export function shouldTerminateOnSuccessfulMemoryMutation(params: {
+  toolName: string
+  toolInput: unknown
+  toolOutput: string
+}): boolean {
+  const canonicalToolName = canonicalizePluginId(params.toolName) || params.toolName
+  if (canonicalToolName !== 'memory') return false
+  const exactToolName = String(params.toolName || '').trim().toLowerCase()
+  const action = exactToolName === 'memory_store'
+    ? 'store'
+    : exactToolName === 'memory_update'
+      ? 'update'
+      : resolveToolAction(params.toolInput)
+  if (action !== 'store' && action !== 'update') return false
+  const output = extractSuggestions(params.toolOutput || '').clean.trim()
+  if (!output || /^error[:\s]/i.test(output)) return false
+  if (!/^(stored|updated) memory\b/i.test(output)) return false
+  return /no further memory lookup is needed unless the user asked you to verify/i.test(output)
+}
+
+export function getWalletApprovalBoundaryAction(output: string): string | null {
+  if (!output.includes('plugin_wallet_')) return null
+  if (/"type":"plugin_wallet_transfer_request"/.test(output)) return 'send'
+  const actionMatch = output.match(/"action":"([^"]+)"/)
+  const action = actionMatch?.[1] || ''
+  if (!action) return null
+  const readOnlyActions = new Set([
+    'balance',
+    'address',
+    'transactions',
+    'encode_contract_call',
+    'simulate_transaction',
+  ])
+  return readOnlyActions.has(action) ? null : action
+}
+
+export function isWalletSimulationResult(toolName: string, output: string): boolean {
+  return toolName === 'wallet_tool' && /"status":"simulated"/.test(output)
+}
+
+export function updateStreamedToolEvents(
+  events: MessageToolEvent[],
+  event: { type: 'call' | 'result'; name: string; input?: string; output?: string; toolCallId?: string },
+) {
+  if (event.type === 'call') {
+    events.push({
+      name: event.name,
+      input: event.input || '',
+      toolCallId: event.toolCallId,
+    })
+    return
+  }
+  const index = event.toolCallId
+    ? events.findLastIndex((entry) => entry.toolCallId === event.toolCallId && !entry.output)
+    : events.findLastIndex((entry) => entry.name === event.name && !entry.output)
+  if (index === -1) return
+  events[index] = {
+    ...events[index],
+    output: event.output || '',
+  }
+}
+
+export function compactThreadRecallText(text: string, maxChars = 180): string {
+  const compact = extractSuggestions(text || '').clean.replace(/\s+/g, ' ').trim()
+  if (!compact) return ''
+  return compact.length > maxChars ? `${compact.slice(0, maxChars - 3)}...` : compact
+}
+
+const DIRECT_MEMORY_WRITE_CONFIRMATION_ONLY_RE = /\b(?:then|and then|after that)?\s*(?:confirm|recap|repeat|summarize|tell me|say)\b[\s\S]{0,120}\b(?:stored|saved|updated|remembered|wrote|write)\b/i
+const DIRECT_MEMORY_WRITE_EXTRA_ACTION_RE = /\b(?:then|and then|after that|also)\b[\s\S]{0,160}\b(?:write|create|send|email|message|delegate|research|search|browse|open|edit|build|schedule|plan|review|analy[sz]e)\b/i
+
+export function isNarrowDirectMemoryWriteTurn(message: string): boolean {
+  const trimmed = String(message || '').trim()
+  if (!trimmed || !isDirectMemoryWriteRequest(trimmed)) return false
+  if (looksLikeOpenEndedDeliverableTask(trimmed)) return false
+  if (DIRECT_MEMORY_WRITE_EXTRA_ACTION_RE.test(trimmed) && !DIRECT_MEMORY_WRITE_CONFIRMATION_ONLY_RE.test(trimmed)) {
+    return false
+  }
+  return !isBroadGoal(trimmed) || DIRECT_MEMORY_WRITE_CONFIRMATION_ONLY_RE.test(trimmed) || !/[?]$/.test(trimmed)
+}
+
+const CURRENT_THREAD_RECALL_BLOCKED_TOOL_IDS = new Set([
+  'memory',
+  'manage_sessions',
+  'web',
+  'context_mgmt',
+])
+
+export function shouldAllowToolForCurrentThreadRecall(toolName: string): boolean {
+  const canonicalToolName = canonicalizePluginId(toolName) || toolName.trim().toLowerCase()
+  return !CURRENT_THREAD_RECALL_BLOCKED_TOOL_IDS.has(canonicalToolName)
+}
+
+const DIRECT_MEMORY_WRITE_ALLOWED_TOOL_IDS = new Set([
+  'memory_store',
+  'memory_update',
+])
+
+export function shouldAllowToolForDirectMemoryWrite(toolName: string): boolean {
+  const rawToolName = toolName.trim().toLowerCase()
+  return DIRECT_MEMORY_WRITE_ALLOWED_TOOL_IDS.has(rawToolName)
+}

package/src/lib/server/chat-turn-tool-routing.ts

@@ -0,0 +1,310 @@
+/**
+ * Chat Turn — Post-LLM Tool Routing
+ *
+ * After the LLM produces a response, this module handles forced tool
+ * invocations (explicitly requested by the user), auto-delegation
+ * (routing coding tasks to CLI backends), and auto-routing (browsing,
+ * research, memory intents).
+ *
+ * Extracted from chat-execution.ts for testability and readability.
+ */
+
+import type { StructuredToolInterface } from '@langchain/core/tools'
+import type { MessageToolEvent, SSEEvent } from '@/types'
+import { loadAgents } from './storage'
+import { buildSessionTools } from './session-tools'
+import { resolveConcreteToolPolicyBlock, type PluginPolicyDecision } from './tool-capability-policy'
+import { resolveActiveProjectContext } from './project-context'
+import { genId } from '@/lib/id'
+import { rankDelegatesByHealth } from './provider-health'
+import { routeTaskIntent, type CapabilityRoutingDecision } from './capability-router'
+import {
+  type DelegateTool,
+  type SessionWithTools,
+  enabledDelegationTools,
+  extractConnectorMessageArgs,
+  extractDelegationTask,
+  findFirstUrl,
+  hasToolEnabled,
+  hasDirectLocalCodingTools,
+  isMemoryListIntent,
+  requestedToolNamesFromMessage,
+  translateRequestedToolInvocation,
+} from './chat-execution-utils'
+import { errorMessage } from '@/lib/shared-utils'
+
+interface ToolRoutingSession extends SessionWithTools {
+  agentId?: string | null
+  cwd: string
+  memoryScopeMode?: string | null
+}
+
+export interface ToolRoutingContext {
+  session: ToolRoutingSession
+  sessionId: string
+  message: string
+  effectiveMessage: string
+  enabledPlugins: string[]
+  toolPolicy: PluginPolicyDecision
+  appSettings: Record<string, unknown>
+  internal: boolean
+  source: string
+  toolEvents: MessageToolEvent[]
+  emit: (ev: SSEEvent) => void
+}
+
+export interface ToolRoutingResult {
+  /** Tool names that were actually invoked */
+  calledNames: Set<string>
+  /** Updated full response (may be modified by delegate output) */
+  fullResponse: string
+  /** Updated error message (may be cleared on failover success) */
+  errorMessage: string | undefined
+  /** Missed requested tools (for warning) */
+  missedRequestedTools: string[]
+}
+
+function extractDelegateResponse(outputText: string): string | null {
+  try {
+    const parsed = JSON.parse(outputText) as Record<string, unknown>
+    if (typeof parsed.response === 'string' && parsed.response.trim()) return parsed.response.trim()
+    if (typeof parsed.result === 'string' && parsed.result.trim()) return parsed.result.trim()
+    return null
+  } catch {
+    return null
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Core: Invoke a single session tool
+// ---------------------------------------------------------------------------
+
+async function invokeSessionTool(
+  ctx: ToolRoutingContext,
+  toolName: string,
+  args: Record<string, unknown>,
+  failurePrefix: string,
+  calledNames: Set<string>,
+): Promise<{ invoked: boolean; responseOverride: string | null }> {
+  const blockedReason = resolveConcreteToolPolicyBlock(toolName, ctx.toolPolicy, ctx.appSettings)
+  if (blockedReason) {
+    ctx.emit({ t: 'err', text: `Capability policy blocked tool invocation "${toolName}": ${blockedReason}` })
+    return { invoked: false, responseOverride: null }
+  }
+  if (
+    (ctx.appSettings as Record<string, unknown>).safetyRequireApprovalForOutbound === true
+    && toolName === 'connector_message_tool'
+    && ctx.source !== 'chat'
+  ) {
+    ctx.emit({ t: 'err', text: 'Outbound connector messaging requires explicit user approval.' })
+    return { invoked: false, responseOverride: null }
+  }
+
+  const agent = ctx.session.agentId ? loadAgents()[ctx.session.agentId] : null
+  const agentRecord = agent as Record<string, unknown> | null
+  const activeProjectContext = resolveActiveProjectContext(ctx.session as unknown as { agentId?: string | null; cwd?: string | null; projectId?: string | null })
+  const { tools, cleanup } = await buildSessionTools(ctx.session.cwd, ctx.enabledPlugins, {
+    agentId: ctx.session.agentId || null,
+    sessionId: ctx.sessionId,
+    platformAssignScope: (agentRecord?.platformAssignScope as 'self' | 'all') || 'self',
+    mcpServerIds: agentRecord?.mcpServerIds as string[] | undefined,
+    mcpDisabledTools: agentRecord?.mcpDisabledTools as string[] | undefined,
+    projectId: activeProjectContext.projectId,
+    projectRoot: activeProjectContext.projectRoot,
+    projectName: activeProjectContext.project?.name || null,
+    projectDescription: activeProjectContext.project?.description || null,
+    memoryScopeMode: (ctx.session.memoryScopeMode ?? agentRecord?.memoryScopeMode as string | null ?? null) as 'all' | 'auto' | 'global' | 'agent' | 'session' | 'project' | null,
+  })
+
+  try {
+    const directTool = tools.find((t) => t?.name === toolName) as StructuredToolInterface | undefined
+    const availableToolNames = tools.map((candidate) => candidate?.name).filter(Boolean)
+    const translated = directTool
+      ? { toolName, args }
+      : translateRequestedToolInvocation(toolName, args, ctx.message, availableToolNames)
+    const selectedTool = directTool || tools.find((t) => t?.name === translated.toolName) as StructuredToolInterface | undefined
+    if (!selectedTool?.invoke) return { invoked: false, responseOverride: null }
+
+    const toolCallId = genId()
+    ctx.emit({ t: 'tool_call', toolName, toolInput: JSON.stringify(translated.args), toolCallId })
+    const toolOutput = await selectedTool.invoke(translated.args)
+    const outputText = typeof toolOutput === 'string' ? toolOutput : JSON.stringify(toolOutput)
+    ctx.emit({ t: 'tool_result', toolName, toolOutput: outputText, toolCallId })
+
+    const delegateResponse = (
+      toolName === 'delegate'
+      || toolName.startsWith('delegate_to_')
+    ) ? extractDelegateResponse(outputText) : null
+
+    calledNames.add(toolName)
+
+    if (delegateResponse) {
+      return { invoked: true, responseOverride: delegateResponse }
+    }
+    return { invoked: true, responseOverride: null }
+  } catch (forceErr: unknown) {
+    ctx.emit({ t: 'err', text: `${failurePrefix}: ${errorMessage(forceErr)}` })
+    return { invoked: false, responseOverride: null }
+  } finally {
+    await cleanup()
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Main: Run all post-LLM tool routing
+// ---------------------------------------------------------------------------
+
+const FORCED_DELEGATION_TOOLS: DelegateTool[] = [
+  'delegate_to_claude_code',
+  'delegate_to_codex_cli',
+  'delegate_to_opencode_cli',
+  'delegate_to_gemini_cli',
+]
+
+export async function runPostLlmToolRouting(
+  ctx: ToolRoutingContext,
+  currentResponse: string,
+  currentError: string | undefined,
+): Promise<ToolRoutingResult> {
+  const calledNames = new Set((ctx.toolEvents || []).map((t) => t.name))
+  let fullResponse = currentResponse
+  let errorMessage = currentError
+
+  const requestedToolNames = (!ctx.internal && ctx.source === 'chat')
+    ? requestedToolNamesFromMessage(ctx.message)
+    : []
+  const routingDecision: CapabilityRoutingDecision | null = (!ctx.internal && ctx.source === 'chat')
+    ? routeTaskIntent(ctx.message, ctx.enabledPlugins, ctx.appSettings)
+    : null
+
+  // --- Forced connector_message_tool ---
+  if (requestedToolNames.includes('connector_message_tool') && !calledNames.has('connector_message_tool')) {
+    const forcedArgs = extractConnectorMessageArgs(ctx.message)
+    if (forcedArgs) {
+      const result = await invokeSessionTool(
+        ctx, 'connector_message_tool',
+        forcedArgs as unknown as Record<string, unknown>,
+        'Forced connector_message_tool invocation failed',
+        calledNames,
+      )
+      if (result.responseOverride) fullResponse = result.responseOverride
+    }
+  }
+
+  // --- Forced delegation tools ---
+  for (const toolName of FORCED_DELEGATION_TOOLS) {
+    if (!requestedToolNames.includes(toolName)) continue
+    if (calledNames.has(toolName)) continue
+    const task = extractDelegationTask(ctx.message, toolName)
+    if (!task) continue
+    const result = await invokeSessionTool(ctx, toolName, { task }, `Forced ${toolName} invocation failed`, calledNames)
+    if (result.responseOverride) fullResponse = result.responseOverride
+  }
+
+  // --- Auto-delegation for coding intent ---
+  const hasDelegationCall = FORCED_DELEGATION_TOOLS.some((t) => calledNames.has(t))
+  const enabledDelegates = enabledDelegationTools(ctx.session)
+  const shouldAutoDelegateCoding = (!ctx.internal && ctx.source === 'chat')
+    && enabledDelegates.length > 0
+    && !hasDelegationCall
+    && calledNames.size === 0
+    && !requestedToolNames.length
+    && !hasDirectLocalCodingTools(ctx.session)
+    && routingDecision?.intent === 'coding'
+
+  if (shouldAutoDelegateCoding) {
+    const baseDelegationOrder = routingDecision?.preferredDelegates?.length
+      ? routingDecision.preferredDelegates
+      : FORCED_DELEGATION_TOOLS
+    const delegationOrder = rankDelegatesByHealth(baseDelegationOrder as DelegateTool[])
+      .filter((tool) => enabledDelegates.includes(tool))
+    for (const delegateTool of delegationOrder) {
+      const result = await invokeSessionTool(ctx, delegateTool, { task: ctx.effectiveMessage.trim() }, 'Auto-delegation failed', calledNames)
+      if (result.invoked) {
+        if (result.responseOverride) fullResponse = result.responseOverride
+        break
+      }
+    }
+  }
+
+  // --- Provider failover via delegation ---
+  const shouldFailoverDelegate = (!ctx.internal && ctx.source === 'chat')
+    && !!errorMessage
+    && !(fullResponse || '').trim()
+    && enabledDelegates.length > 0
+    && !hasDelegationCall
+    && (routingDecision?.intent === 'coding' || routingDecision?.intent === 'general')
+  if (shouldFailoverDelegate) {
+    const preferred = routingDecision?.preferredDelegates?.length
+      ? routingDecision.preferredDelegates
+      : FORCED_DELEGATION_TOOLS
+    const fallbackOrder = rankDelegatesByHealth(preferred as DelegateTool[])
+      .filter((tool) => enabledDelegates.includes(tool))
+    for (const delegateTool of fallbackOrder) {
+      const result = await invokeSessionTool(
+        ctx, delegateTool,
+        { task: ctx.effectiveMessage.trim() },
+        `Provider failover via ${delegateTool} failed`,
+        calledNames,
+      )
+      if (result.invoked) {
+        if (result.responseOverride) fullResponse = result.responseOverride
+        errorMessage = undefined
+        break
+      }
+    }
+  }
+
+  // --- Auto-routing: browsing, research, memory ---
+  const canAutoRoute = (!ctx.internal && ctx.source === 'chat')
+    && !!routingDecision
+    && calledNames.size === 0
+    && requestedToolNames.length === 0
+
+  if (canAutoRoute && routingDecision?.intent === 'browsing' && routingDecision.primaryUrl && hasToolEnabled(ctx.session, 'browser')) {
+    const result = await invokeSessionTool(
+      ctx, 'browser',
+      { action: 'read_page', url: routingDecision.primaryUrl },
+      'Auto browser routing failed',
+      calledNames,
+    )
+    if (result.responseOverride) fullResponse = result.responseOverride
+  }
+
+  if (canAutoRoute && routingDecision?.intent === 'research') {
+    const routeUrl = routingDecision.primaryUrl || findFirstUrl(ctx.message)
+    if (routeUrl && hasToolEnabled(ctx.session, 'web_fetch')) {
+      const result = await invokeSessionTool(ctx, 'web_fetch', { url: routeUrl }, 'Auto web_fetch routing failed', calledNames)
+      if (result.responseOverride) fullResponse = result.responseOverride
+    } else if (hasToolEnabled(ctx.session, 'web_search')) {
+      const result = await invokeSessionTool(ctx, 'web_search', { query: ctx.effectiveMessage.trim(), maxResults: 5 }, 'Auto web_search routing failed', calledNames)
+      if (result.responseOverride) fullResponse = result.responseOverride
+    }
+  }
+
+  if (canAutoRoute && calledNames.size === 0 && hasToolEnabled(ctx.session, 'memory') && isMemoryListIntent(ctx.message)) {
+    const result = await invokeSessionTool(
+      ctx, 'memory_tool',
+      { action: 'list', key: '', scope: 'auto' },
+      'Auto memory listing failed',
+      calledNames,
+    )
+    if (result.responseOverride) fullResponse = result.responseOverride
+  }
+
+  // --- Missed requested tools ---
+  const missed = requestedToolNames.filter((name) => !calledNames.has(name))
+
+  // When tool output is the only content and LLM produced nothing, provide a brief notice
+  if (calledNames.size > 0 && !fullResponse.trim()) {
+    const toolLabel = Array.from(calledNames).pop()?.replace(/_/g, ' ') || 'tool'
+    fullResponse = `Used **${toolLabel}** — see tool output above for details.`
+  }
+
+  return {
+    calledNames,
+    fullResponse,
+    errorMessage,
+    missedRequestedTools: missed,
+  }
+}

package/src/lib/server/chatroom-session-persistence.test.ts

@@ -35,9 +35,9 @@ function runWithTempDataDir(script: string) {
 describe('chatroom synthetic session persistence', () => {
   it('reuses stored synthetic sessions and preserves delegate resume state', () => {
     const output = runWithTempDataDir(`
-      const helpersMod = await import('./src/lib/server/chatroom-helpers.ts')
+      const helpersMod = await import('./src/lib/server/chatroom-helpers')
       const helpers = helpersMod.default || helpersMod
-      const storageMod = await import('./src/lib/server/storage.ts')
+      const storageMod = await import('./src/lib/server/storage')
       const storage = storageMod.default || storageMod
       const now = Date.now()
       const agent = {

package/src/lib/server/clawhub-client.ts

@@ -1,4 +1,5 @@
 import type { ClawHubSkill } from '@/types'
+import { errorMessage } from '@/lib/shared-utils'
 
 export interface ClawHubSearchResult {
   skills: ClawHubSkill[]
@@ -71,7 +72,7 @@ export async function searchClawHub(query: string, page = 1, limit = 20): Promis
 
     return { skills, total, page, nextCursor: data.nextCursor }
   } catch (err: unknown) {
-    console.warn('[clawhub] search failed:', err instanceof Error ? err.message : String(err))
+    console.warn('[clawhub] search failed:', errorMessage(err))
     return { skills: [], total: 0, page }
   }
 }

package/src/lib/server/collection-helpers.test.ts

@@ -0,0 +1,92 @@
+import assert from 'node:assert/strict'
+import { describe, it } from 'node:test'
+
+import { mutateItem, deleteItem, type CollectionOps } from './collection-helpers'
+
+/**
+ * Tests for collection-helpers reliability fixes:
+ * - mutateItem uses atomic patchStoredItem when ops.table is set
+ * - deleteItem uses row-level deleteStoredItem when ops.table is set
+ *
+ * Since patchStoredItem requires a real SQLite connection, we test the
+ * logic branching by verifying that the table-based path is taken when
+ * ops.table is set, and the legacy path when it is not.
+ */
+
+function makeInMemoryOps<T>(initial: Record<string, T>): CollectionOps<T> & { data: Record<string, T>; saveCount: number } {
+  const data = { ...initial }
+  const ops = {
+    data,
+    saveCount: 0,
+    load: () => ({ ...data }),
+    save: (next: Record<string, T>) => {
+      Object.keys(data).forEach((k) => delete data[k])
+      Object.assign(data, next)
+      ops.saveCount++
+    },
+    topic: 'test',
+  }
+  return ops
+}
+
+describe('collection-helpers', () => {
+  describe('mutateItem (legacy path — no table)', () => {
+    it('mutates an existing item via load-all/save-all', () => {
+      const ops = makeInMemoryOps({ a: { name: 'Alice', score: 10 } })
+      const result = mutateItem(ops, 'a', (item) => ({ ...item, score: 20 }))
+
+      assert.ok(result)
+      assert.equal((result as Record<string, unknown>).score, 20)
+      assert.equal(ops.saveCount, 1)
+      assert.equal(ops.data.a.score, 20)
+    })
+
+    it('returns null for missing item', () => {
+      const ops = makeInMemoryOps<Record<string, unknown>>({})
+      const result = mutateItem(ops, 'missing', (item) => item)
+
+      assert.equal(result, null)
+      assert.equal(ops.saveCount, 0)
+    })
+
+    it('passes full collection to the mutation function', () => {
+      const ops = makeInMemoryOps({ a: { v: 1 }, b: { v: 2 } })
+      let capturedAll: Record<string, unknown> | null = null
+      mutateItem(ops, 'a', (item, all) => {
+        capturedAll = all as Record<string, unknown>
+        return item
+      })
+
+      assert.ok(capturedAll)
+      assert.ok('a' in capturedAll!)
+      assert.ok('b' in capturedAll!)
+    })
+  })
+
+  describe('deleteItem (legacy path — no table)', () => {
+    it('deletes an existing item', () => {
+      const ops = makeInMemoryOps({ a: { v: 1 }, b: { v: 2 } })
+      const result = deleteItem(ops, 'a')
+
+      assert.equal(result, true)
+      assert.equal(ops.data.a, undefined)
+      assert.equal(ops.data.b.v, 2)
+    })
+
+    it('returns false for missing item', () => {
+      const ops = makeInMemoryOps<Record<string, unknown>>({})
+      const result = deleteItem(ops, 'missing')
+      assert.equal(result, false)
+    })
+
+    it('uses custom deleteFn when provided', () => {
+      let deletedId: string | null = null
+      const ops = makeInMemoryOps({ a: { v: 1 } })
+      ops.deleteFn = (id: string) => { deletedId = id }
+
+      const result = deleteItem(ops, 'a')
+      assert.equal(result, true)
+      assert.equal(deletedId, 'a')
+    })
+  })
+})

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

@@ -1,22 +1,41 @@
 import { NextResponse } from 'next/server'
 import { notify } from './ws-hub'
+import { deleteStoredItem, patchStoredItem, type StorageCollection } from './storage'
 
 export interface CollectionOps<T> {
   load: () => Record<string, T>
   save: (data: Record<string, T>) => void
   deleteFn?: (id: string) => void
   topic?: string
+  /** When set, mutateItem/deleteItem use row-level upsert/delete instead of save-all. */
+  table?: StorageCollection
 }
 
 /**
- * Load → 404 check → mutate → save → notify.
+ * Load → 404 check → mutate → upsert single row → notify.
  * `fn` receives the item and the full collection, returns the updated item.
+ *
+ * When `ops.table` is set, uses an atomic read-modify-write transaction via
+ * patchStoredItem to prevent concurrent writers from losing each other's updates.
  */
 export function mutateItem<T>(
   ops: CollectionOps<T>,
   id: string,
   fn: (item: T, all: Record<string, T>) => T,
 ): T | null {
+  if (ops.table) {
+    // Atomic path: read + mutate + write inside a single SQLite transaction
+    const result = patchStoredItem<T>(ops.table, id, (current) => {
+      if (current === null) return null
+      // Load full collection for the fn callback (rare code paths need it)
+      const all = ops.load()
+      all[id] = current
+      return fn(current, all)
+    })
+    if (result !== null && ops.topic) notify(ops.topic)
+    return result
+  }
+  // Legacy path: load-all → mutate → save-all (no table set)
   const all = ops.load()
   if (!all[id]) return null
   all[id] = fn(all[id], all)
@@ -26,8 +45,9 @@ export function mutateItem<T>(
 }
 
 /**
- * Load → 404 check → delete → notify.
- * Uses `ops.deleteFn` if provided, otherwise inline `delete` + `save`.
+ * Load → 404 check → delete single row → notify.
+ * Uses `ops.deleteFn` if provided, then `ops.table` for row-level delete,
+ * otherwise inline `delete` + `save`.
  */
 export function deleteItem<T>(
   ops: CollectionOps<T>,
@@ -37,6 +57,8 @@ export function deleteItem<T>(
   if (!all[id]) return false
   if (ops.deleteFn) {
     ops.deleteFn(id)
+  } else if (ops.table) {
+    deleteStoredItem(ops.table, id)
   } else {
     delete all[id]
     ops.save(all)