@swarmclawai/swarmclaw 0.8.4 → 0.8.7

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

@@ -2,7 +2,7 @@ import fs from 'fs'
 import path from 'path'
 import { DATA_DIR } from '../data-dir'
 import type { PlatformConnector, ConnectorInstance, InboundMessage } from './types'
-import { isNoMessage } from './manager'
+import { resolveConnectorIngressReply } from './ingress-delivery'
 
 const matrix: PlatformConnector = {
   async start(connector, botToken, onMessage): Promise<ConnectorInstance> {
@@ -48,9 +48,9 @@ const matrix: PlatformConnector = {
       }
 
       try {
-        const response = await onMessage(inbound)
-        if (isNoMessage(response)) return
-        await client.sendText(roomId, response)
+        const reply = await resolveConnectorIngressReply(onMessage, inbound)
+        if (!reply) return
+        await client.sendText(roomId, reply.visibleText)
       } catch (err: any) {
         console.error(`[matrix] Error handling message:`, err.message)
         try {

package/src/lib/server/connectors/message-sentinel.ts

@@ -0,0 +1,7 @@
+/** Sentinel value agents return when no outbound reply should be sent */
+export const NO_MESSAGE_SENTINEL = 'NO_MESSAGE'
+
+/** Check if an agent response is the NO_MESSAGE sentinel (case-insensitive, trimmed) */
+export function isNoMessage(text: string): boolean {
+  return text.trim().toUpperCase() === NO_MESSAGE_SENTINEL
+}

package/src/lib/server/connectors/openclaw.test.ts

@@ -3,7 +3,7 @@ import fs from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
 import { test } from 'node:test'
-import openclaw from './openclaw.ts'
+import openclaw from './openclaw'
 
 type WsFrame = Record<string, unknown>
 

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

@@ -1,8 +1,10 @@
 import crypto from 'node:crypto'
 import fs from 'node:fs'
 import path from 'node:path'
-import { DATA_DIR } from '../data-dir'
+import { OPENCLAW_DATA_DIR } from '../data-dir'
+import { safeJsonParse } from '../json-utils'
 import type { PlatformConnector, ConnectorInstance, InboundMessage } from './types'
+import { resolveConnectorIngressReply } from './ingress-delivery'
 import {
   createGatewayRequestFrame,
   parseGatewayFrame,
@@ -38,7 +40,6 @@ const DEFAULT_CHAT_HISTORY_LIMIT = 40
 const MIN_CHAT_HISTORY_LIMIT = 5
 const MAX_CHAT_HISTORY_LIMIT = 200
 const MAX_INLINE_ATTACHMENT_BYTES = 5_000_000
-const NO_MESSAGE_SENTINEL = 'NO_MESSAGE'
 const MAX_SEEN_HISTORY_MESSAGES = 4_096
 const RECENT_HISTORY_DUPLICATE_WINDOW_MS = 20_000
 const HISTORY_ERROR_LOG_INTERVAL_MS = 30_000
@@ -126,10 +127,6 @@ function isSecureWsUrl(url: string): boolean {
   return false
 }
 
-function isNoMessage(text: string): boolean {
-  return text.trim().toUpperCase() === NO_MESSAGE_SENTINEL
-}
-
 function base64UrlEncode(buf: Buffer): string {
   return buf.toString('base64').replaceAll('+', '-').replaceAll('/', '_').replace(/=+$/g, '')
 }
@@ -185,7 +182,7 @@ function signDevicePayload(privateKeyPem: string, payload: string): string {
 }
 
 function resolveIdentityPath(connectorId: string): string {
-  return path.join(DATA_DIR, 'openclaw', `${connectorId}-device.json`)
+  return path.join(OPENCLAW_DATA_DIR, `${connectorId}-device.json`)
 }
 
 function persistIdentity(filePath: string, identity: DeviceIdentity) {
@@ -205,7 +202,7 @@ function persistIdentity(filePath: string, identity: DeviceIdentity) {
 function loadOrCreateIdentity(filePath: string): DeviceIdentity {
   try {
     if (fs.existsSync(filePath)) {
-      const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8')) as StoredIdentity
+      const parsed = safeJsonParse<StoredIdentity | null>(fs.readFileSync(filePath, 'utf8'), null)
       if (
         parsed?.version === 1
         && typeof parsed.deviceId === 'string'
@@ -960,8 +957,9 @@ const openclaw: PlatformConnector = {
       markRecentInbound(inbound, now)
 
       try {
-        const response = await onMessage(inbound)
-        if (!isNoMessage(response)) await sendChat(inbound.channelId, response)
+        const reply = await resolveConnectorIngressReply(onMessage, inbound)
+        if (!reply) return
+        await sendChat(inbound.channelId, reply.visibleText)
       } catch (err: unknown) {
         const message = getErrorMessage(err)
         console.error('[openclaw] Error routing inbound chat event:', message)

package/src/lib/server/connectors/outbox.test.ts

@@ -0,0 +1,192 @@
+import assert from 'node:assert/strict'
+import { describe, it } from 'node:test'
+import { runWithTempDataDir } from '../test-utils/run-with-temp-data-dir'
+
+describe('connector outbox', () => {
+  it('delivers scheduled follow-ups through the durable outbox worker', () => {
+    const output = runWithTempDataDir(`
+      const storageMod = await import('./src/lib/server/storage')
+      const managerMod = await import('./src/lib/server/connectors/manager')
+      const outboxMod = await import('./src/lib/server/connectors/outbox')
+      const pluginsMod = await import('./src/lib/server/plugins')
+      const storage = storageMod.default || storageMod
+      const manager = managerMod.default || managerMod
+      const outbox = outboxMod.default || outboxMod
+      const plugins = pluginsMod.default || pluginsMod
+
+      const attempts = []
+      plugins.getPluginManager().registerBuiltin('test-outbox-plugin', {
+        name: 'Test Outbox Plugin',
+        connectors: [{
+          id: 'test-outbox',
+          name: 'Test Outbox',
+          description: 'Test connector for outbox delivery',
+          startListener: async () => async () => {},
+          sendMessage: async (channelId, text) => {
+            attempts.push({ channelId, text })
+            return { messageId: 'outbox-msg-1' }
+          },
+        }],
+      })
+
+      const now = Date.now()
+      storage.saveSettings({})
+      storage.saveConnectors({
+        conn_1: {
+          id: 'conn_1',
+          name: 'Outbox Connector',
+          platform: 'test-outbox',
+          agentId: 'agent_1',
+          credentialId: null,
+          config: { botToken: 'test-token' },
+          isEnabled: true,
+          status: 'stopped',
+          createdAt: now,
+          updatedAt: now,
+        },
+      })
+
+      await manager.startConnector('conn_1')
+      const scheduled = manager.scheduleConnectorFollowUp({
+        connectorId: 'conn_1',
+        channelId: '15550001111',
+        text: 'Follow up later',
+        delaySec: 1,
+      })
+      const before = storage.loadConnectorOutbox()[scheduled.followUpId]
+      await outbox.runConnectorOutboxNow({ now: scheduled.sendAt + 5 })
+      const after = storage.loadConnectorOutbox()[scheduled.followUpId]
+      console.log(JSON.stringify({ scheduled, before, after, attempts }))
+    `, { prefix: 'swarmclaw-outbox-test-' })
+
+    assert.equal(output.before.status, 'pending')
+    assert.equal(output.after.status, 'sent')
+    assert.equal(output.after.lastMessageId, 'outbox-msg-1')
+    assert.deepEqual(output.attempts, [{ channelId: '15550001111', text: 'Follow up later' }])
+  })
+
+  it('retries failed outbox sends with backoff and eventually marks them sent', () => {
+    const output = runWithTempDataDir(`
+      const storageMod = await import('./src/lib/server/storage')
+      const managerMod = await import('./src/lib/server/connectors/manager')
+      const outboxMod = await import('./src/lib/server/connectors/outbox')
+      const pluginsMod = await import('./src/lib/server/plugins')
+      const storage = storageMod.default || storageMod
+      const manager = managerMod.default || managerMod
+      const outbox = outboxMod.default || outboxMod
+      const plugins = pluginsMod.default || pluginsMod
+
+      let sendCount = 0
+      plugins.getPluginManager().registerBuiltin('test-outbox-retry-plugin', {
+        name: 'Test Outbox Retry Plugin',
+        connectors: [{
+          id: 'test-outbox-retry',
+          name: 'Test Outbox Retry',
+          description: 'Test connector for outbox retries',
+          startListener: async () => async () => {},
+          sendMessage: async (channelId, text) => {
+            sendCount += 1
+            if (sendCount === 1) throw new Error('temporary send failure')
+            return { messageId: 'retry-msg-2' }
+          },
+        }],
+      })
+
+      const now = Date.now()
+      storage.saveSettings({})
+      storage.saveConnectors({
+        conn_retry: {
+          id: 'conn_retry',
+          name: 'Retry Connector',
+          platform: 'test-outbox-retry',
+          agentId: 'agent_1',
+          credentialId: null,
+          config: { botToken: 'test-token' },
+          isEnabled: true,
+          status: 'stopped',
+          createdAt: now,
+          updatedAt: now,
+        },
+      })
+
+      await manager.startConnector('conn_retry')
+      const queued = outbox.enqueueConnectorOutbox({
+        connectorId: 'conn_retry',
+        channelId: 'retry-channel',
+        text: 'Retry me',
+        sendAt: now,
+        maxAttempts: 3,
+      })
+      await outbox.runConnectorOutboxNow({ now: queued.sendAt + 1 })
+      const afterFirst = storage.loadConnectorOutbox()[queued.outboxId]
+      await outbox.runConnectorOutboxNow({ now: afterFirst.sendAt + 1 })
+      const afterSecond = storage.loadConnectorOutbox()[queued.outboxId]
+      console.log(JSON.stringify({ afterFirst, afterSecond, sendCount }))
+    `, { prefix: 'swarmclaw-outbox-test-' })
+
+    assert.equal(output.afterFirst.status, 'pending')
+    assert.equal(output.afterFirst.attemptCount, 1)
+    assert.match(output.afterFirst.lastError, /temporary send failure/i)
+    assert.equal(output.afterSecond.status, 'sent')
+    assert.equal(output.afterSecond.attemptCount, 2)
+    assert.equal(output.afterSecond.lastMessageId, 'retry-msg-2')
+    assert.equal(output.sendCount, 2)
+  })
+
+  it('dedupes and replaces scheduled follow-ups durably', () => {
+    const output = runWithTempDataDir(`
+      const storageMod = await import('./src/lib/server/storage')
+      const managerMod = await import('./src/lib/server/connectors/manager')
+      const storage = storageMod.default || storageMod
+      const manager = managerMod.default || managerMod
+
+      const now = Date.now()
+      storage.saveSettings({})
+      storage.saveConnectors({
+        conn_1: {
+          id: 'conn_1',
+          name: 'Outbox Connector',
+          platform: 'whatsapp',
+          agentId: 'agent_1',
+          credentialId: null,
+          config: {},
+          isEnabled: true,
+          status: 'stopped',
+          createdAt: now,
+          updatedAt: now,
+        },
+      })
+
+      const first = manager.scheduleConnectorFollowUp({
+        connectorId: 'conn_1',
+        channelId: '15550001111@s.whatsapp.net',
+        text: 'First follow-up',
+        delaySec: 30,
+        dedupeKey: 'dup-1',
+      })
+      const second = manager.scheduleConnectorFollowUp({
+        connectorId: 'conn_1',
+        channelId: '15550001111@s.whatsapp.net',
+        text: 'Second follow-up same dedupe',
+        delaySec: 30,
+        dedupeKey: 'dup-1',
+      })
+      const third = manager.scheduleConnectorFollowUp({
+        connectorId: 'conn_1',
+        channelId: '15550001111@s.whatsapp.net',
+        text: 'Replacement follow-up',
+        delaySec: 30,
+        dedupeKey: 'dup-1',
+        replaceExisting: true,
+      })
+      const outbox = storage.loadConnectorOutbox()
+      console.log(JSON.stringify({ first, second, third, outbox }))
+    `, { prefix: 'swarmclaw-outbox-test-' })
+
+    assert.equal(output.first.followUpId, output.second.followUpId)
+    assert.notEqual(output.third.followUpId, output.first.followUpId)
+    assert.equal(output.outbox[output.first.followUpId].status, 'cancelled')
+    assert.equal(output.outbox[output.third.followUpId].status, 'pending')
+    assert.equal(output.outbox[output.third.followUpId].text, 'Replacement follow-up')
+  })
+})

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

@@ -0,0 +1,369 @@
+import { genId } from '@/lib/id'
+import {
+  loadConnectorOutbox,
+  patchStoredItem,
+  upsertConnectorOutboxItem,
+} from '../storage'
+import { notify } from '../ws-hub'
+import { errorMessage, hmrSingleton } from '@/lib/shared-utils'
+
+
+export type ConnectorOutboxStatus =
+  | 'pending'
+  | 'processing'
+  | 'sent'
+  | 'suppressed'
+  | 'failed'
+  | 'cancelled'
+
+export interface ConnectorOutboxEntry extends Record<string, unknown> {
+  id: string
+  status: ConnectorOutboxStatus
+  sendAt: number
+  createdAt: number
+  updatedAt: number
+  attemptCount: number
+  maxAttempts: number
+  /** Destination fields (set by enqueueConnectorOutbox) */
+  connectorId?: string
+  platform?: string
+  channelId?: string
+  text?: string
+  sessionId?: string | null
+  imageUrl?: string
+  fileUrl?: string
+  mediaPath?: string
+  mimeType?: string
+  fileName?: string
+  caption?: string
+  replyToMessageId?: string
+  threadId?: string
+  ptt?: boolean
+  dedupeKey?: string | null
+  lastError?: string | null
+  deliveredAt?: number | null
+  lastMessageId?: string | null
+  processingLeaseId?: string | null
+  processingStartedAt?: number | null
+}
+
+const RETRY_BASE_MS = 5_000
+const RETRY_MAX_MS = 5 * 60_000
+const DEFAULT_MAX_ATTEMPTS = 6
+const CLAIM_STALE_MS = 60_000
+const MAX_BATCH_SIZE = 10
+
+type OutboxState = {
+  timer: ReturnType<typeof setTimeout> | null
+  dueAt: number | null
+  running: boolean
+  pendingKick: boolean
+}
+
+const outboxState: OutboxState = hmrSingleton<OutboxState>('__swarmclaw_connector_outbox_state__', () => ({
+  timer: null,
+  dueAt: null,
+  running: false,
+  pendingKick: false,
+}))
+
+function normalizeEntry(value: unknown): ConnectorOutboxEntry | null {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null
+  const row = value as Record<string, unknown>
+  const id = typeof row.id === 'string' ? row.id.trim() : ''
+  const channelId = typeof row.channelId === 'string' ? row.channelId : ''
+  if (!id || !channelId) return null
+  return {
+    id,
+    
+    
+    channelId,
+    text: typeof row.text === 'string' ? row.text : '',
+    sessionId: typeof row.sessionId === 'string' ? row.sessionId : null,
+    imageUrl: typeof row.imageUrl === 'string' ? row.imageUrl : undefined,
+    fileUrl: typeof row.fileUrl === 'string' ? row.fileUrl : undefined,
+    mediaPath: typeof row.mediaPath === 'string' ? row.mediaPath : undefined,
+    mimeType: typeof row.mimeType === 'string' ? row.mimeType : undefined,
+    fileName: typeof row.fileName === 'string' ? row.fileName : undefined,
+    caption: typeof row.caption === 'string' ? row.caption : undefined,
+    replyToMessageId: typeof row.replyToMessageId === 'string' ? row.replyToMessageId : undefined,
+    threadId: typeof row.threadId === 'string' ? row.threadId : undefined,
+    ptt: row.ptt === true,
+    status: normalizeStatus(row.status),
+    sendAt: typeof row.sendAt === 'number' ? row.sendAt : 0,
+    createdAt: typeof row.createdAt === 'number' ? row.createdAt : 0,
+    updatedAt: typeof row.updatedAt === 'number' ? row.updatedAt : 0,
+    attemptCount: typeof row.attemptCount === 'number' ? row.attemptCount : 0,
+    maxAttempts: typeof row.maxAttempts === 'number' ? row.maxAttempts : DEFAULT_MAX_ATTEMPTS,
+    dedupeKey: typeof row.dedupeKey === 'string' ? row.dedupeKey : null,
+    lastError: typeof row.lastError === 'string' ? row.lastError : null,
+    deliveredAt: typeof row.deliveredAt === 'number' ? row.deliveredAt : null,
+    lastMessageId: typeof row.lastMessageId === 'string' ? row.lastMessageId : null,
+    processingLeaseId: typeof row.processingLeaseId === 'string' ? row.processingLeaseId : null,
+    processingStartedAt: typeof row.processingStartedAt === 'number' ? row.processingStartedAt : null,
+  }
+}
+
+function normalizeStatus(value: unknown): ConnectorOutboxStatus {
+  switch (value) {
+    case 'processing':
+    case 'sent':
+    case 'suppressed':
+    case 'failed':
+    case 'cancelled':
+      return value
+    default:
+      return 'pending'
+  }
+}
+
+function isTerminalStatus(status: ConnectorOutboxStatus): boolean {
+  return status === 'sent' || status === 'suppressed' || status === 'failed' || status === 'cancelled'
+}
+
+function isClaimEligible(entry: ConnectorOutboxEntry, now: number): boolean {
+  if (entry.status === 'pending') return entry.sendAt <= now
+  if (entry.status !== 'processing') return false
+  const startedAt = entry.processingStartedAt || entry.updatedAt || entry.sendAt || 0
+  return now - startedAt >= CLAIM_STALE_MS
+}
+
+function listEntries(): ConnectorOutboxEntry[] {
+  return Object.values(loadConnectorOutbox())
+    .map((value) => normalizeEntry(value))
+    .filter((value): value is ConnectorOutboxEntry => !!value)
+}
+
+function nextRetryAt(now: number, attemptCount: number): number {
+  const backoff = Math.min(RETRY_MAX_MS, RETRY_BASE_MS * (2 ** Math.max(0, attemptCount - 1)))
+  return now + backoff
+}
+
+function scheduleTimer(delayMs: number): void {
+  const nextDueAt = Date.now() + Math.max(0, delayMs)
+  if (outboxState.timer && outboxState.dueAt !== null && outboxState.dueAt <= nextDueAt) return
+  if (outboxState.timer) {
+    clearTimeout(outboxState.timer)
+    outboxState.timer = null
+  }
+  outboxState.dueAt = nextDueAt
+  outboxState.timer = setTimeout(() => {
+    outboxState.timer = null
+    outboxState.dueAt = null
+    void runConnectorOutboxNow().catch((err: unknown) => {
+      console.warn(`[connector-outbox] Worker tick failed: ${errorMessage(err)}`)
+    })
+  }, Math.max(0, delayMs))
+  outboxState.timer.unref?.()
+}
+
+function rescheduleFromStorage(now = Date.now()): void {
+  const active = listEntries()
+    .filter((entry) => !isTerminalStatus(entry.status))
+    .sort((a, b) => a.sendAt - b.sendAt || a.createdAt - b.createdAt)
+  if (!active.length) {
+    if (outboxState.timer) {
+      clearTimeout(outboxState.timer)
+      outboxState.timer = null
+    }
+    outboxState.dueAt = null
+    return
+  }
+  const nextDue = active[0].sendAt
+  scheduleTimer(Math.max(0, nextDue - now))
+}
+
+function claimEntry(id: string, now: number): ConnectorOutboxEntry | null {
+  const leaseId = `${now}:${Math.random().toString(16).slice(2, 10)}`
+  const claimed = patchStoredItem<ConnectorOutboxEntry>('connector_outbox', id, (current) => {
+    const entry = normalizeEntry(current)
+    if (!entry) return current
+    if (!isClaimEligible(entry, now)) return entry
+    return {
+      ...entry,
+      status: 'processing',
+      processingLeaseId: leaseId,
+      processingStartedAt: now,
+      updatedAt: now,
+    }
+  })
+  const normalized = normalizeEntry(claimed)
+  if (!normalized) return null
+  if (normalized.status !== 'processing' || normalized.processingLeaseId !== leaseId) return null
+  return normalized
+}
+
+async function processEntry(id: string, now: number): Promise<ConnectorOutboxEntry | null> {
+  const claimed = claimEntry(id, now)
+  if (!claimed) return null
+
+  try {
+    const { sendConnectorMessage } = await import('./manager')
+    // Outbox entries always have channelId+text from enqueueConnectorOutbox
+    const result = await sendConnectorMessage(claimed as ConnectorOutboxEntry & { channelId: string; text: string })
+    const deliveredAt = Date.now()
+    const next: ConnectorOutboxEntry = {
+      ...claimed,
+      connectorId: result.connectorId,
+      platform: result.platform,
+      channelId: result.channelId,
+      status: result.suppressed ? 'suppressed' : 'sent',
+      attemptCount: claimed.attemptCount + 1,
+      updatedAt: deliveredAt,
+      deliveredAt,
+      lastMessageId: result.messageId || null,
+      lastError: null,
+      processingLeaseId: null,
+      processingStartedAt: null,
+    }
+    upsertConnectorOutboxItem(next.id, next)
+    notify('connector_outbox')
+    return next
+  } catch (err: unknown) {
+    const failedAt = Date.now()
+    const nextAttemptCount = claimed.attemptCount + 1
+    const permanent = nextAttemptCount >= claimed.maxAttempts
+    const next: ConnectorOutboxEntry = {
+      ...claimed,
+      status: permanent ? 'failed' : 'pending',
+      attemptCount: nextAttemptCount,
+      updatedAt: failedAt,
+      sendAt: permanent ? claimed.sendAt : nextRetryAt(failedAt, nextAttemptCount),
+      lastError: errorMessage(err),
+      processingLeaseId: null,
+      processingStartedAt: null,
+    }
+    upsertConnectorOutboxItem(next.id, next)
+    notify('connector_outbox')
+    return next
+  }
+}
+
+export function enqueueConnectorOutbox(
+  input: Record<string, unknown> & {
+    sendAt?: number
+    maxAttempts?: number
+    dedupeKey?: string | null
+  },
+  options?: { replaceExisting?: boolean },
+): { outboxId: string; sendAt: number } {
+  const now = Date.now()
+  const requestedSendAt = typeof input.sendAt === 'number' ? input.sendAt : now
+  const sendAt = Math.max(now, requestedSendAt)
+  const dedupeKey = input.dedupeKey?.trim() || null
+
+  if (dedupeKey) {
+    const existing = findPendingConnectorOutboxByDedupe(dedupeKey, now)
+    if (existing && existing.sendAt > now && !options?.replaceExisting) {
+      return { outboxId: existing.id, sendAt: existing.sendAt }
+    }
+    if (existing && options?.replaceExisting) {
+      patchStoredItem<ConnectorOutboxEntry>('connector_outbox', existing.id, (current) => {
+        const entry = normalizeEntry(current)
+        if (!entry || isTerminalStatus(entry.status)) return entry
+        return {
+          ...entry,
+          status: 'cancelled',
+          updatedAt: now,
+          processingLeaseId: null,
+          processingStartedAt: null,
+        }
+      })
+    }
+  }
+
+  const entry: ConnectorOutboxEntry = {
+    ...input,
+    id: genId(),
+    status: 'pending',
+    sendAt,
+    createdAt: now,
+    updatedAt: now,
+    attemptCount: 0,
+    maxAttempts: Math.max(1, Math.trunc(input.maxAttempts || DEFAULT_MAX_ATTEMPTS)),
+    dedupeKey,
+    lastError: null,
+    deliveredAt: null,
+    lastMessageId: null,
+    processingLeaseId: null,
+    processingStartedAt: null,
+  }
+  upsertConnectorOutboxItem(entry.id, entry)
+  notify('connector_outbox')
+  rescheduleFromStorage(now)
+  return { outboxId: entry.id, sendAt: entry.sendAt }
+}
+
+export function findPendingConnectorOutboxByDedupe(dedupeKey: string, now = Date.now()): ConnectorOutboxEntry | null {
+  const normalizedKey = dedupeKey.trim()
+  if (!normalizedKey) return null
+  return listEntries()
+    .filter((entry) =>
+      entry.dedupeKey === normalizedKey
+      && !isTerminalStatus(entry.status)
+      && (entry.sendAt > now || entry.status === 'processing'),
+    )
+    .sort((a, b) => a.sendAt - b.sendAt || a.createdAt - b.createdAt)[0] || null
+}
+
+export async function runConnectorOutboxNow(options?: {
+  now?: number
+  maxItems?: number
+  onlyIds?: string[]
+}): Promise<ConnectorOutboxEntry[]> {
+  if (outboxState.running) {
+    outboxState.pendingKick = true
+    return []
+  }
+
+  outboxState.running = true
+  const now = options?.now ?? Date.now()
+  try {
+    const onlyIds = new Set((options?.onlyIds || []).filter(Boolean))
+    const candidates = listEntries()
+      .filter((entry) => (onlyIds.size === 0 || onlyIds.has(entry.id)) && isClaimEligible(entry, now))
+      .sort((a, b) => a.sendAt - b.sendAt || a.createdAt - b.createdAt)
+      .slice(0, Math.max(1, options?.maxItems || MAX_BATCH_SIZE))
+
+    const processed: ConnectorOutboxEntry[] = []
+    for (const entry of candidates) {
+      const next = await processEntry(entry.id, now)
+      if (next) processed.push(next)
+    }
+    return processed
+  } finally {
+    outboxState.running = false
+    if (outboxState.pendingKick) {
+      outboxState.pendingKick = false
+      scheduleTimer(0)
+    } else {
+      rescheduleFromStorage()
+    }
+  }
+}
+
+export function startConnectorOutboxWorker(): void {
+  rescheduleFromStorage()
+}
+
+export function stopConnectorOutboxWorker(): void {
+  if (outboxState.timer) {
+    clearTimeout(outboxState.timer)
+    outboxState.timer = null
+  }
+  outboxState.dueAt = null
+  outboxState.pendingKick = false
+}
+
+export function getConnectorOutboxStatus(): {
+  queued: number
+  running: boolean
+  nextDueAt: number | null
+} {
+  const queued = listEntries().filter((entry) => !isTerminalStatus(entry.status)).length
+  return {
+    queued,
+    running: outboxState.running,
+    nextDueAt: outboxState.dueAt,
+  }
+}

package/src/lib/server/connectors/pairing.test.ts

@@ -8,12 +8,14 @@ import {
   approvePairingCode,
   clearConnectorPairingState,
   createOrTouchPairingRequest,
+  getWhatsAppApprovedSenderIds,
   isSenderAllowed,
   listPendingPairingRequests,
   listStoredAllowedSenders,
+  normalizeWhatsAppApprovedContacts,
   parseAllowFromCsv,
   parsePairingPolicy,
-} from './pairing.ts'
+} from './pairing'
 
 function withTempDataDir<T>(fn: (dir: string) => T): T {
   const original = process.env.DATA_DIR
@@ -97,3 +99,18 @@ test('addAllowedSender deduplicates and normalizes sender ids', () => {
     assert.deepEqual(listStoredAllowedSenders(connectorId), ['test@example.com'])
   })
 })
+
+test('normalizeWhatsAppApprovedContacts trims entries and deduplicates equivalent phone identifiers', () => {
+  const contacts = normalizeWhatsAppApprovedContacts([
+    { id: 'one', label: ' Alice ', phone: ' +1 (555) 000-1111 ' },
+    { id: 'two', label: 'Alice JID', phone: '15550001111@s.whatsapp.net' },
+    { id: '', label: '', phone: '16660002222@s.whatsapp.net' },
+    { id: 'empty', label: 'Ignored', phone: '   ' },
+  ])
+
+  assert.deepEqual(contacts, [
+    { id: 'one', label: 'Alice', phone: '+1 (555) 000-1111' },
+    { id: 'wa-contact-2', label: '16660002222@s.whatsapp.net', phone: '16660002222@s.whatsapp.net' },
+  ])
+  assert.deepEqual(getWhatsAppApprovedSenderIds(contacts), ['+1 (555) 000-1111', '16660002222@s.whatsapp.net'])
+})