@swarmclawai/swarmclaw 1.9.11 → 1.9.12

package/README.md

@@ -183,7 +183,7 @@ Full hosted deployment guides live at https://swarmclaw.ai/docs/deployment
 - **Structured Sessions**: reusable bounded runs with templates, facilitators, participants, hidden live rooms, chatroom `/breakout`, durable transcripts, outputs, operator controls, and a visible protocols template gallery plus visual builder.
 - **Memory**: hybrid recall, graph traversal, journaling, durable documents, project-scoped context, automatic reflection memory, communication preferences, profile and boundary memory, significant events, and open follow-up loops.
 - **Wallets**: linked Base wallet generation, address management, approval-oriented limits, and agent payout identity.
-- **Connectors**: Discord, Slack, Telegram, WhatsApp, Teams, Matrix, OpenClaw, SwarmDock, SwarmFeed, and more.
+- **Connectors**: Discord, Slack, Telegram, WhatsApp, Teams, Matrix, email, local file queues, OpenClaw, SwarmDock, SwarmFeed, and more.
 - **MCP Servers**: connect any Model Context Protocol server (stdio, SSE, or streamable HTTP) and inject its tools into agents alongside built-ins. Configure, test, and assign per-agent from the MCP Servers panel.
 - **Extensions**: external tool extensions, UI modules, hooks, install/update flows, and managed resource manifests for extension-owned agents, routines, local folders, gateways, and setup checks.
 
@@ -399,6 +399,15 @@ Operational docs: https://swarmclaw.ai/docs/observability
 
 ## Releases
 
+### v1.9.12 Highlights
+
+Local file-queue connector release: operators can bridge SwarmClaw to filesystem inbox, outbox, archive, and error folders without a hosted message bus.
+
+- **File Queue connector.** Configure root, inbox, outbox, archive, and error folders from the connector sheet or CLI.
+- **JSON command ingress.** External tools can drop command envelopes into the inbox, then SwarmClaw normalizes them into connector messages for the selected agent or chatroom.
+- **Durable file handling.** Processed commands move to archive, malformed commands move to errors with diagnostic sidecars, and replies are written to outbox as structured JSON.
+- **Connector runtime parity.** Queue traffic uses the existing connector session, policy, health, readiness, CLI, and follow-up delivery paths.
+
 ### v1.9.11 Highlights
 
 Task execution policy release: operators can attach ordered review, approval, and verification stages to board tasks, record decisions, and block premature completion until required stages clear.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmclawai/swarmclaw",
-  "version": "1.9.11",
+  "version": "1.9.12",
   "description": "Build and run autonomous AI agents with OpenClaw, Hermes, multiple model providers, orchestration, delegation, memory, skills, schedules, and chat connectors.",
   "main": "electron-dist/main.js",
   "license": "MIT",
@@ -29,6 +29,7 @@
     "clawd",
     "clawdbot",
     "moltbot",
+    "file-queue",
     "openclaw-skill",
     "openclaw-dashboard",
     "openclaw-gateway",

package/src/app/home/page.tsx

@@ -429,7 +429,7 @@ export default function HomePage() {
             <StatCard label="Agents" value={String(agentCount)} hint="Total active agents configured in your dashboard" index={0} />
             <StatCard label="Active Tasks" value={String(activeTaskCount)} accent={activeTaskCount > 0} hint="Tasks currently running or queued for execution" index={1} />
             <StatCard label="Today's Cost" value={`$${todayCost.toFixed(2)}`} hint="Estimated API cost for today across all providers" index={2} />
-            <StatCard label="Connectors" value={`${activeConnectorCount}/${allConnectors.length}`} accent={activeConnectorCount > 0} hint="Active bridges to chat platforms (Discord, Slack, etc.)" index={3} />
+            <StatCard label="Connectors" value={`${activeConnectorCount}/${allConnectors.length}`} accent={activeConnectorCount > 0} hint="Active bridges to chat platforms, local queues, and agent channels." index={3} />
           </div>
 
           {/* Cost trend sparkline */}

package/src/cli/index.ts

@@ -1177,7 +1177,7 @@ export function buildProgram(): Command {
   connectors
     .command('create')
     .description('Create connector')
-    .requiredOption('--platform <platform>', 'Connector platform (discord|telegram|slack|whatsapp|openclaw|bluebubbles|signal|teams|googlechat|matrix)')
+    .requiredOption('--platform <platform>', 'Connector platform (discord|telegram|slack|whatsapp|openclaw|bluebubbles|signal|teams|googlechat|matrix|email|filequeue|swarmdock)')
     .requiredOption('--agent-id <agentId>', 'Agent id')
     .option('--name <name>', 'Connector name')
     .option('--credential-id <credentialId>', 'Credential id')

package/src/components/connectors/connector-sheet.tsx

@@ -86,6 +86,12 @@ interface ConnectorConfigField {
 }
 
 const FIELD_HINTS: Record<string, string> = {
+  rootDir: 'Root folder for the queue. Defaults to a managed folder under SwarmClaw data.',
+  inboxDir: 'Folder where external tools drop inbound JSON commands. Relative paths are resolved under Root Directory.',
+  outboxDir: 'Folder where SwarmClaw writes outbound JSON replies. Relative paths are resolved under Root Directory.',
+  archiveDir: 'Processed inbound JSON commands are moved here after routing.',
+  errorDir: 'Malformed or failed inbound JSON commands are moved here with an error sidecar.',
+  pollIntervalMs: 'How often SwarmClaw checks the inbox folder. Minimum 250 ms.',
   channelIds: "Find these in your platform's developer settings. Leave empty to allow all channels",
   chatIds: "Find these in your platform's developer settings. Leave empty to allow all chats",
   roomIds: 'Leave empty to allow all rooms visible to the bot',
@@ -366,6 +372,30 @@ const PLATFORMS: {
       { key: 'maxBudget', label: 'Max Budget (USDC micro-units)', placeholder: '5000000', help: '$1 = 1000000, $5 = 5000000' },
     ],
   },
+  {
+    id: 'filequeue',
+    label: 'File Queue',
+    color: '#22C55E',
+    setupSteps: [
+      'Choose a root directory or let SwarmClaw create a managed one',
+      'External tools write JSON commands into the inbox folder',
+      'SwarmClaw archives processed commands and writes JSON replies into the outbox folder',
+      'Use an agent or chatroom route to decide who handles inbound commands',
+    ],
+    tokenLabel: '',
+    tokenHelp: '',
+    configFields: [
+      { key: 'rootDir', label: 'Root Directory', placeholder: '~/swarmclaw-command-queue', help: 'Optional. Defaults to data/connectors/<id>/filequeue.', section: 'basic' },
+      { key: 'inboxDir', label: 'Inbox Directory', placeholder: 'inbox', help: 'Inbound JSON command directory. Relative paths resolve under Root Directory.', section: 'basic' },
+      { key: 'outboxDir', label: 'Outbox Directory', placeholder: 'outbox', help: 'Outbound JSON reply directory. Relative paths resolve under Root Directory.', section: 'basic' },
+      { key: 'archiveDir', label: 'Archive Directory', placeholder: 'archive', help: 'Processed command archive directory.', section: 'advanced' },
+      { key: 'errorDir', label: 'Error Directory', placeholder: 'errors', help: 'Malformed command quarantine directory.', section: 'advanced' },
+      { key: 'pollIntervalMs', label: 'Poll Interval (ms)', placeholder: '1000', help: 'How often to scan the inbox. Minimum 250 ms.', section: 'advanced' },
+      { key: 'defaultChannelId', label: 'Default Channel ID', placeholder: 'ops', help: 'Used when an inbound command omits channelId.', section: 'advanced' },
+      { key: 'defaultSenderId', label: 'Default Sender ID', placeholder: 'queue', help: 'Used when an inbound command omits senderId.', section: 'advanced' },
+      { key: 'defaultSenderName', label: 'Default Sender Name', placeholder: 'Queue', help: 'Used when an inbound command omits senderName.', section: 'advanced' },
+    ],
+  },
 ]
 
 const COMMON_CONFIG_FIELDS: ConnectorConfigField[] = [
@@ -780,10 +810,10 @@ export function ConnectorSheet() {
       await saveConnectorMutation.mutateAsync({
         id: editing?.id,
         payload: {
-          name: name || `${platformConfig?.label} Bot`,
+          name: name || (platform === 'filequeue' ? `${platformConfig?.label} Connector` : `${platformConfig?.label} Bot`),
           platform,
           ...routePayload,
-          credentialId: credentialId || null,
+          credentialId: showCredentialSection ? (credentialId || null) : null,
           config,
         },
       })
@@ -848,6 +878,7 @@ export function ConnectorSheet() {
   const credList = Object.values(credentials)
   const basicPlatformFields = platformConfig.configFields.filter((field) => field.section !== 'advanced')
   const advancedPlatformFields = platformConfig.configFields.filter((field) => field.section === 'advanced')
+  const showCredentialSection = Boolean(platformConfig.tokenLabel.trim())
   const basicAccessFields = ACCESS_CONTROL_FIELDS.filter((field) => field.section !== 'advanced')
   const advancedAccessFields = ACCESS_CONTROL_FIELDS.filter((field) => field.section === 'advanced')
   const hasConfiguredValue = useCallback((key: string) => Boolean(config[key]?.trim()), [config])
@@ -1014,7 +1045,7 @@ export function ConnectorSheet() {
                 <div>
                   <div className={`text-[14px] font-600 ${platform === p.id ? 'text-text' : 'text-text-2'}`}>{p.label}</div>
                   <div className="text-[11px] text-text-3 mt-0.5">
-                    {p.id === 'whatsapp' ? 'QR code pairing' : p.id === 'openclaw' ? 'WebSocket gateway' : p.id === 'bluebubbles' ? 'iMessage bridge' : p.id === 'signal' ? 'signal-cli binary' : p.id === 'matrix' ? 'Access token' : p.id === 'googlechat' ? 'Service account' : p.id === 'teams' ? 'Bot Framework' : 'Bot token'}
+                    {p.id === 'whatsapp' ? 'QR code pairing' : p.id === 'openclaw' ? 'WebSocket gateway' : p.id === 'bluebubbles' ? 'iMessage bridge' : p.id === 'signal' ? 'signal-cli binary' : p.id === 'matrix' ? 'Access token' : p.id === 'googlechat' ? 'Service account' : p.id === 'teams' ? 'Bot Framework' : p.id === 'filequeue' ? 'Local queue' : 'Bot token'}
                   </div>
                 </div>
               </button>
@@ -1074,7 +1105,7 @@ export function ConnectorSheet() {
         <input
           value={name}
           onChange={(e) => setName(e.target.value)}
-          placeholder={`My ${platformConfig.label} Bot`}
+          placeholder={`My ${platformConfig.label} ${platform === 'filequeue' ? 'Connector' : 'Bot'}`}
           className={inputClass}
           style={{ fontFamily: 'inherit' }}
         />
@@ -1128,7 +1159,7 @@ export function ConnectorSheet() {
       </div>
 
       {/* Bot token credential */}
-      {platform !== 'whatsapp' && (
+      {showCredentialSection && (
         <div className="mb-6">
           <label className="block font-display text-[12px] font-600 text-text-2 uppercase tracking-[0.08em] mb-2">{platformConfig.tokenLabel}</label>
           <p className="text-[12px] text-text-3/60 mb-2">{platformConfig.tokenHelp}</p>

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

@@ -92,7 +92,7 @@ function CommandPaletteInner({ setOpen }: { setOpen: (v: boolean) => void }) {
       { id: 'projects', label: 'Projects', description: 'Scoped workspaces for agents and tasks', keywords: ['workspace', 'scope'] },
       { id: 'chatrooms', label: 'Chatrooms', description: 'Shared multi-agent conversations', keywords: ['group', 'room', 'mentions'] },
       { id: 'schedules', label: 'Schedules', description: 'Recurring and timed automations', keywords: ['cron', 'automation', 'interval'] },
-      { id: 'connectors', label: 'Connectors', description: 'Bridges to Slack, Discord, Telegram, and more', keywords: ['discord', 'slack', 'telegram', 'whatsapp'] },
+      { id: 'connectors', label: 'Connectors', description: 'Bridges to Slack, Discord, Telegram, file queues, and more', keywords: ['discord', 'slack', 'telegram', 'whatsapp', 'file queue'] },
       { id: 'memory', label: 'Memory', description: 'Stored agent memory and retrieval', keywords: ['knowledge', 'vector', 'retrieval'] },
       { id: 'knowledge', label: 'Knowledge', description: 'Shared knowledge base', keywords: ['docs', 'entries', 'facts'] },
       { id: 'providers', label: 'Providers', description: 'Model providers and endpoints', keywords: ['openai', 'anthropic', 'ollama', 'endpoint'] },

package/src/components/shared/connector-platform-icon.test.ts

@@ -8,6 +8,10 @@ import {
 
 describe('connector platform metadata', () => {
   it('resolves legacy connector platforms used by stored runtime data', () => {
+    assert.deepEqual(resolveConnectorPlatformMeta('filequeue'), {
+      label: 'File Queue',
+      color: '#22C55E',
+    })
     assert.deepEqual(resolveConnectorPlatformMeta('webchat'), {
       label: 'Web Chat',
       color: '#0EA5E9',

package/src/components/shared/connector-platform-icon.tsx

@@ -26,6 +26,7 @@ export const CONNECTOR_PLATFORM_META: Record<ConnectorPlatform, { label: string;
   email: { label: 'Email', color: '#EA4335' },
   webchat: { label: 'Web Chat', color: '#0EA5E9' },
   mockmail: { label: 'MockMail', color: '#7C3AED' },
+  filequeue: { label: 'File Queue', color: '#22C55E' },
   swarmdock: { label: 'SwarmDock', color: '#F59E0B' },
 }
 

package/src/lib/connectors/connector-readiness.ts

@@ -4,7 +4,7 @@ export type ConnectorReadinessState = 'needs_setup' | 'attention' | 'healthy'
 export type ConnectorReadinessCheckStatus = 'ready' | 'warning' | 'error'
 
 export interface ConnectorReadinessCheck {
-  id: 'credentials' | 'route' | 'pairing' | 'connection' | 'gateway'
+  id: 'credentials' | 'route' | 'pairing' | 'connection' | 'gateway' | 'queue'
   label: string
   status: ConnectorReadinessCheckStatus
   detail: string
@@ -26,6 +26,7 @@ export function hasConnectorCredentials(connector: Connector): boolean {
     || connector.platform === 'openclaw'
     || connector.platform === 'signal'
     || connector.platform === 'email'
+    || connector.platform === 'filequeue'
     || connector.platform === 'swarmdock'
     || (connector.platform === 'bluebubbles' && (!!connector.credentialId || !!connector.config?.password))
     || !!connector.credentialId
@@ -53,12 +54,21 @@ export function getConnectorReadiness(connector: Connector): ConnectorReadiness
   const credentialsReady = hasConnectorCredentials(connector)
   const routeReady = hasRoute(connector)
   const checks: ConnectorReadinessCheck[] = [
-    {
-      id: 'credentials',
-      label: 'Credentials',
-      status: credentialsReady ? 'ready' : 'error',
-      detail: credentialsReady ? 'Credential path is configured.' : 'Add the token, password, or pairing credential.',
-    },
+    connector.platform === 'filequeue'
+      ? {
+          id: 'queue',
+          label: 'Queue folders',
+          status: 'ready',
+          detail: connector.config?.rootDir
+            ? `Watching ${connector.config.rootDir}`
+            : 'Using the managed local queue folder.',
+        }
+      : {
+          id: 'credentials',
+          label: 'Credentials',
+          status: credentialsReady ? 'ready' : 'error',
+          detail: credentialsReady ? 'Credential path is configured.' : 'Add the token, password, or pairing credential.',
+        },
     {
       id: 'route',
       label: 'Route target',

package/src/lib/server/connectors/connector-lifecycle.ts

@@ -71,6 +71,7 @@ export async function getPlatform(platform: string) {
     case 'googlechat': return (await import('./googlechat')).default
     case 'matrix':    return (await import('./matrix')).default
     case 'email':     return (await import('./email')).default
+    case 'filequeue': return (await import('./filequeue')).default
     case 'swarmdock': return (await import('./swarmdock')).default
   }
 
@@ -181,7 +182,7 @@ async function _startConnectorImpl(connectorId: string): Promise<void> {
       botToken = swarmdockFallbackPrivateKey
     }
 
-    if (!botToken && connector.platform !== 'whatsapp' && connector.platform !== 'openclaw' && connector.platform !== 'signal' && connector.platform !== 'email' && connector.platform !== 'swarmdock') {
+    if (!botToken && connector.platform !== 'whatsapp' && connector.platform !== 'openclaw' && connector.platform !== 'signal' && connector.platform !== 'email' && connector.platform !== 'filequeue' && connector.platform !== 'swarmdock') {
       throw new Error('No bot token configured')
     }
 

package/src/lib/server/connectors/connector-routing.test.ts

@@ -14,7 +14,7 @@ import { resolveImagePath } from '../resolve-image'
 // 1. Connector module resolution (getPlatform)
 // ---------------------------------------------------------------------------
 describe('getPlatform — connector module resolution', () => {
-  const newPlatforms = ['matrix', 'googlechat', 'teams', 'signal', 'bluebubbles'] as const
+  const newPlatforms = ['matrix', 'googlechat', 'teams', 'signal', 'bluebubbles', 'filequeue'] as const
 
   for (const name of newPlatforms) {
     it(`returns a valid module for "${name}"`, async () => {

package/src/lib/server/connectors/connector-service.ts

@@ -192,6 +192,7 @@ export async function autoStartConnectorIfNeeded(connector: Connector, body: Rec
   const hasCredentials = connector.platform === 'whatsapp'
     || connector.platform === 'openclaw'
     || (connector.platform === 'bluebubbles' && (!!connector.credentialId || !!connector.config.password))
+    || connector.platform === 'filequeue'
     || !!connector.credentialId
   if (!hasCredentials || body.autoStart === false) return
   try {

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

@@ -14,6 +14,7 @@ describe('connectorSupportsBinaryMedia — email', () => {
   it('still returns false for platforms that do not support outbound binary', () => {
     assert.equal(connectorSupportsBinaryMedia('signal'), false)
     assert.equal(connectorSupportsBinaryMedia('matrix'), false)
+    assert.equal(connectorSupportsBinaryMedia('filequeue'), false)
   })
 })
 

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

@@ -0,0 +1,141 @@
+import assert from 'node:assert/strict'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import test from 'node:test'
+
+import type { Connector } from '@/types'
+import {
+  drainFileQueueOnce,
+  normalizeFileQueueEnvelope,
+  resolveFileQueuePaths,
+  writeFileQueueOutbound,
+} from './filequeue'
+
+function makeConnector(rootDir: string): Connector {
+  return {
+    id: 'filequeue-1',
+    name: 'Local Queue',
+    platform: 'filequeue',
+    agentId: 'agent-1',
+    chatroomId: null,
+    credentialId: null,
+    config: {
+      rootDir,
+      defaultSenderId: 'queue',
+      defaultSenderName: 'Queue',
+      defaultChannelId: 'ops',
+    },
+    isEnabled: true,
+    status: 'running',
+    createdAt: 1,
+    updatedAt: 1,
+  }
+}
+
+test('normalizeFileQueueEnvelope maps command JSON into an inbound connector message', () => {
+  const rootDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-filequeue-'))
+  try {
+    const connector = makeConnector(rootDir)
+    const inbound = normalizeFileQueueEnvelope(connector, {
+      id: 'cmd-1',
+      channelId: 'ops',
+      senderId: 'jarvis',
+      senderName: 'JARVIS',
+      text: 'Summarize current status',
+      threadId: 'status-thread',
+    })
+
+    assert.equal(inbound.platform, 'filequeue')
+    assert.equal(inbound.channelId, 'ops')
+    assert.equal(inbound.senderId, 'jarvis')
+    assert.equal(inbound.senderName, 'JARVIS')
+    assert.equal(inbound.messageId, 'cmd-1')
+    assert.equal(inbound.threadId, 'status-thread')
+    assert.equal(inbound.text, 'Summarize current status')
+  } finally {
+    fs.rmSync(rootDir, { recursive: true, force: true })
+  }
+})
+
+test('drainFileQueueOnce archives processed commands and writes replies to outbox', async () => {
+  const rootDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-filequeue-'))
+  try {
+    const connector = makeConnector(rootDir)
+    const paths = resolveFileQueuePaths(connector)
+    fs.mkdirSync(paths.inboxDir, { recursive: true })
+    fs.writeFileSync(path.join(paths.inboxDir, '001.json'), JSON.stringify({
+      id: 'cmd-1',
+      senderId: 'jarvis',
+      senderName: 'JARVIS',
+      text: 'Run the release check',
+    }))
+
+    const result = await drainFileQueueOnce(connector, async (msg) => {
+      assert.equal(msg.channelId, 'ops')
+      assert.equal(msg.senderId, 'jarvis')
+      assert.equal(msg.text, 'Run the release check')
+      return 'Release check queued.'
+    })
+
+    assert.equal(result.processed, 1)
+    assert.equal(result.failed, 0)
+    assert.equal(fs.existsSync(path.join(paths.inboxDir, '001.json')), false)
+    assert.equal(fs.existsSync(path.join(paths.archiveDir, '001.json')), true)
+
+    const outboxFiles = fs.readdirSync(paths.outboxDir).filter((file) => file.endsWith('.json'))
+    assert.equal(outboxFiles.length, 1)
+    const outbound = JSON.parse(fs.readFileSync(path.join(paths.outboxDir, outboxFiles[0]), 'utf8')) as Record<string, unknown>
+    assert.equal(outbound.connectorId, connector.id)
+    assert.equal(outbound.channelId, 'ops')
+    assert.equal(outbound.text, 'Release check queued.')
+    assert.equal(outbound.replyToMessageId, 'cmd-1')
+  } finally {
+    fs.rmSync(rootDir, { recursive: true, force: true })
+  }
+})
+
+test('drainFileQueueOnce moves malformed JSON into the error directory', async () => {
+  const rootDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-filequeue-'))
+  try {
+    const connector = makeConnector(rootDir)
+    const paths = resolveFileQueuePaths(connector)
+    fs.mkdirSync(paths.inboxDir, { recursive: true })
+    fs.writeFileSync(path.join(paths.inboxDir, 'broken.json'), '{bad-json')
+
+    const result = await drainFileQueueOnce(connector, async () => {
+      throw new Error('should not route malformed envelopes')
+    })
+
+    assert.equal(result.processed, 0)
+    assert.equal(result.failed, 1)
+    assert.equal(fs.existsSync(path.join(paths.inboxDir, 'broken.json')), false)
+    assert.equal(fs.existsSync(path.join(paths.errorDir, 'broken.json')), true)
+    assert.equal(fs.existsSync(path.join(paths.errorDir, 'broken.json.error.txt')), true)
+  } finally {
+    fs.rmSync(rootDir, { recursive: true, force: true })
+  }
+})
+
+test('writeFileQueueOutbound stores structured command output in the outbox', async () => {
+  const rootDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-filequeue-'))
+  try {
+    const connector = makeConnector(rootDir)
+    const written = await writeFileQueueOutbound(connector, {
+      channelId: 'ops',
+      text: 'Done',
+      threadId: 'status-thread',
+      replyToMessageId: 'cmd-1',
+    })
+
+    const payload = JSON.parse(fs.readFileSync(written.path, 'utf8')) as Record<string, unknown>
+    assert.equal(payload.kind, 'swarmclaw.filequeue.outbound')
+    assert.equal(payload.connectorId, connector.id)
+    assert.equal(payload.channelId, 'ops')
+    assert.equal(payload.text, 'Done')
+    assert.equal(payload.threadId, 'status-thread')
+    assert.equal(payload.replyToMessageId, 'cmd-1')
+  } finally {
+    fs.rmSync(rootDir, { recursive: true, force: true })
+  }
+})

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

@@ -0,0 +1,324 @@
+import fs from 'node:fs'
+import fsp from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+
+import { genId } from '@/lib/id'
+import { CONNECTORS_DATA_DIR } from '@/lib/server/data-dir'
+import { log } from '@/lib/server/logger'
+import { errorMessage } from '@/lib/shared-utils'
+import type { Connector } from '@/types'
+import type {
+  ConnectorIngressResult,
+  ConnectorInstance,
+  InboundMessage,
+  OutboundSendOptions,
+  PlatformConnector,
+} from './types'
+import { resolveConnectorIngressReply } from './ingress-delivery'
+
+const TAG = 'filequeue'
+const DEFAULT_POLL_INTERVAL_MS = 1_000
+const MIN_POLL_INTERVAL_MS = 250
+
+export interface FileQueuePaths {
+  rootDir: string
+  inboxDir: string
+  outboxDir: string
+  archiveDir: string
+  errorDir: string
+}
+
+export interface FileQueueDrainResult {
+  processed: number
+  failed: number
+}
+
+export interface FileQueueOutboundInput {
+  channelId: string
+  text: string
+  threadId?: string
+  replyToMessageId?: string
+  options?: OutboundSendOptions
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : null
+}
+
+function clean(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : ''
+}
+
+function expandHome(input: string): string {
+  if (input === '~') return os.homedir()
+  if (input.startsWith('~/') || input.startsWith('~\\')) {
+    return path.join(os.homedir(), input.slice(2))
+  }
+  return input
+}
+
+function resolveConfiguredPath(rootDir: string, configured: unknown, fallback: string): string {
+  const value = clean(configured)
+  if (!value) return path.join(rootDir, fallback)
+  const expanded = expandHome(value)
+  return path.isAbsolute(expanded) ? path.resolve(expanded) : path.resolve(rootDir, expanded)
+}
+
+function parsePollIntervalMs(value: unknown): number {
+  const parsed = typeof value === 'number'
+    ? value
+    : (typeof value === 'string' && value.trim() ? Number.parseInt(value.trim(), 10) : DEFAULT_POLL_INTERVAL_MS)
+  if (!Number.isFinite(parsed)) return DEFAULT_POLL_INTERVAL_MS
+  return Math.max(MIN_POLL_INTERVAL_MS, parsed)
+}
+
+function ensureFileQueueDirs(paths: FileQueuePaths): void {
+  for (const dir of [paths.rootDir, paths.inboxDir, paths.outboxDir, paths.archiveDir, paths.errorDir]) {
+    fs.mkdirSync(dir, { recursive: true })
+  }
+}
+
+export function resolveFileQueuePaths(connector: Connector): FileQueuePaths {
+  const config = connector.config || {}
+  const configuredRoot = clean(config.rootDir)
+  const rootDir = configuredRoot
+    ? path.resolve(expandHome(configuredRoot))
+    : path.join(CONNECTORS_DATA_DIR, connector.id, 'filequeue')
+  return {
+    rootDir,
+    inboxDir: resolveConfiguredPath(rootDir, config.inboxDir, 'inbox'),
+    outboxDir: resolveConfiguredPath(rootDir, config.outboxDir, 'outbox'),
+    archiveDir: resolveConfiguredPath(rootDir, config.archiveDir, 'archive'),
+    errorDir: resolveConfiguredPath(rootDir, config.errorDir, 'errors'),
+  }
+}
+
+function firstText(...values: unknown[]): string {
+  for (const value of values) {
+    const text = clean(value)
+    if (text) return text
+  }
+  return ''
+}
+
+function fileNameSafe(value: string): string {
+  return value
+    .split('')
+    .map((char) => {
+      const code = char.charCodeAt(0)
+      const isDigit = code >= 48 && code <= 57
+      const isUpper = code >= 65 && code <= 90
+      const isLower = code >= 97 && code <= 122
+      return isDigit || isUpper || isLower || char === '-' || char === '_' ? char : '_'
+    })
+    .join('')
+    .slice(0, 96) || 'item'
+}
+
+function resolveUniquePath(dir: string, basename: string): string {
+  const ext = path.extname(basename)
+  const stem = path.basename(basename, ext)
+  let candidate = path.join(dir, basename)
+  if (!fs.existsSync(candidate)) return candidate
+  for (let i = 1; i < 1_000; i += 1) {
+    candidate = path.join(dir, `${stem}-${i}${ext}`)
+    if (!fs.existsSync(candidate)) return candidate
+  }
+  return path.join(dir, `${stem}-${Date.now()}-${genId()}${ext}`)
+}
+
+async function moveFile(source: string, targetDir: string): Promise<string> {
+  await fsp.mkdir(targetDir, { recursive: true })
+  const target = resolveUniquePath(targetDir, path.basename(source))
+  try {
+    await fsp.rename(source, target)
+  } catch (err: unknown) {
+    const code = typeof err === 'object' && err && 'code' in err ? String((err as { code?: unknown }).code) : ''
+    if (code !== 'EXDEV') throw err
+    await fsp.copyFile(source, target)
+    await fsp.unlink(source)
+  }
+  return target
+}
+
+function readNestedEnvelope(record: Record<string, unknown>): Record<string, unknown> | null {
+  return asRecord(record.payload)
+    || asRecord(record.command)
+    || asRecord(record.message)
+    || asRecord(record.data)
+}
+
+export function normalizeFileQueueEnvelope(connector: Connector, envelope: unknown): InboundMessage {
+  const record = asRecord(envelope)
+  if (!record) throw new Error('File queue envelope must be a JSON object')
+  const nested = readNestedEnvelope(record)
+  const sender = asRecord(record.sender) || asRecord(nested?.sender)
+  const config = connector.config || {}
+  const id = firstText(record.id, record.messageId, record.commandId, nested?.id, nested?.messageId, genId())
+  const text = firstText(
+    record.text,
+    record.body,
+    record.prompt,
+    typeof record.command === 'string' ? record.command : '',
+    nested?.text,
+    nested?.body,
+    nested?.prompt,
+    typeof nested?.command === 'string' ? nested.command : '',
+  )
+  if (!text) throw new Error('File queue envelope requires text, body, prompt, or command')
+
+  const channelId = firstText(record.channelId, record.channel, nested?.channelId, nested?.channel, config.defaultChannelId, 'filequeue')
+  const senderId = firstText(record.senderId, sender?.id, sender?.senderId, nested?.senderId, config.defaultSenderId, 'filequeue')
+  const senderName = firstText(record.senderName, sender?.name, sender?.senderName, nested?.senderName, config.defaultSenderName, senderId)
+
+  return {
+    platform: 'filequeue',
+    channelId,
+    channelName: firstText(record.channelName, nested?.channelName, channelId),
+    senderId,
+    senderName,
+    text,
+    messageId: id,
+    replyToMessageId: firstText(record.replyToMessageId, nested?.replyToMessageId) || undefined,
+    threadId: firstText(record.threadId, nested?.threadId) || undefined,
+    isGroup: record.isGroup === true || nested?.isGroup === true,
+  }
+}
+
+export async function writeFileQueueOutbound(
+  connector: Connector,
+  input: FileQueueOutboundInput,
+): Promise<{ id: string; path: string; payload: Record<string, unknown> }> {
+  const paths = resolveFileQueuePaths(connector)
+  ensureFileQueueDirs(paths)
+  const id = genId()
+  const payload: Record<string, unknown> = {
+    id,
+    kind: 'swarmclaw.filequeue.outbound',
+    connectorId: connector.id,
+    connectorName: connector.name,
+    platform: 'filequeue',
+    channelId: input.channelId,
+    text: input.text,
+    createdAt: new Date().toISOString(),
+  }
+  if (input.threadId) payload.threadId = input.threadId
+  if (input.replyToMessageId) payload.replyToMessageId = input.replyToMessageId
+  if (input.options?.imageUrl) payload.imageUrl = input.options.imageUrl
+  if (input.options?.fileUrl) payload.fileUrl = input.options.fileUrl
+  if (input.options?.mediaPath) payload.mediaPath = input.options.mediaPath
+  if (input.options?.mimeType) payload.mimeType = input.options.mimeType
+  if (input.options?.fileName) payload.fileName = input.options.fileName
+  if (input.options?.caption) payload.caption = input.options.caption
+
+  const filename = `${Date.now()}-${fileNameSafe(id)}.json`
+  const outputPath = resolveUniquePath(paths.outboxDir, filename)
+  await fsp.writeFile(outputPath, `${JSON.stringify(payload, null, 2)}\n`, 'utf8')
+  return { id, path: outputPath, payload }
+}
+
+export async function drainFileQueueOnce(
+  connector: Connector,
+  onMessage: (msg: InboundMessage) => Promise<ConnectorIngressResult>,
+): Promise<FileQueueDrainResult> {
+  const paths = resolveFileQueuePaths(connector)
+  ensureFileQueueDirs(paths)
+  const entries = await fsp.readdir(paths.inboxDir, { withFileTypes: true })
+  const files = entries
+    .filter((entry) => entry.isFile() && path.extname(entry.name).toLowerCase() === '.json')
+    .map((entry) => entry.name)
+    .sort((a, b) => a.localeCompare(b))
+  let processed = 0
+  let failed = 0
+
+  for (const file of files) {
+    const source = path.join(paths.inboxDir, file)
+    try {
+      const raw = await fsp.readFile(source, 'utf8')
+      const envelope = JSON.parse(raw) as unknown
+      const inbound = normalizeFileQueueEnvelope(connector, envelope)
+      const reply = await resolveConnectorIngressReply(onMessage, inbound)
+      if (reply) {
+        await writeFileQueueOutbound(connector, {
+          channelId: inbound.channelId,
+          text: reply.visibleText,
+          threadId: inbound.threadId,
+          replyToMessageId: inbound.messageId,
+        })
+      }
+      await moveFile(source, paths.archiveDir)
+      processed += 1
+    } catch (err: unknown) {
+      failed += 1
+      const message = errorMessage(err)
+      log.warn(TAG, `Failed to process file queue command ${file}: ${message}`)
+      try {
+        const moved = fs.existsSync(source)
+          ? await moveFile(source, paths.errorDir)
+          : path.join(paths.errorDir, file)
+        await fsp.writeFile(`${moved}.error.txt`, `${message}\n`, 'utf8')
+      } catch (moveErr: unknown) {
+        log.warn(TAG, `Failed to move malformed file queue command ${file}: ${errorMessage(moveErr)}`)
+      }
+    }
+  }
+
+  return { processed, failed }
+}
+
+const fileQueue: PlatformConnector = {
+  async start(connector, _botToken, onMessage): Promise<ConnectorInstance> {
+    const paths = resolveFileQueuePaths(connector)
+    ensureFileQueueDirs(paths)
+    let stopped = false
+    let draining = false
+    const pollIntervalMs = parsePollIntervalMs(connector.config?.pollIntervalMs)
+
+    const drain = async () => {
+      if (stopped || draining) return
+      draining = true
+      try {
+        const result = await drainFileQueueOnce(connector, onMessage)
+        if (result.processed || result.failed) {
+          log.info(TAG, `File queue drain for ${connector.name}: ${result.processed} processed, ${result.failed} failed`)
+        }
+      } catch (err: unknown) {
+        log.warn(TAG, `File queue drain failed for ${connector.name}: ${errorMessage(err)}`)
+      } finally {
+        draining = false
+      }
+    }
+
+    void drain()
+    const timer = setInterval(() => {
+      void drain()
+    }, pollIntervalMs)
+    timer.unref?.()
+
+    return {
+      connector,
+      authenticated: true,
+      supportsBinaryMedia: false,
+      stop: async () => {
+        stopped = true
+        clearInterval(timer)
+      },
+      isAlive: () => !stopped,
+      sendMessage: async (channelId: string, text: string, options?: OutboundSendOptions) => {
+        const written = await writeFileQueueOutbound(connector, {
+          channelId,
+          text,
+          threadId: options?.threadId,
+          replyToMessageId: options?.replyToMessageId,
+          options,
+        })
+        return { messageId: written.id }
+      },
+    }
+  },
+}
+
+export default fileQueue

package/src/lib/server/session-tools/crud.ts

@@ -210,6 +210,7 @@ const VALID_CONNECTOR_PLATFORMS = new Set([
   'googlechat',
   'matrix',
   'email',
+  'filequeue',
   'webchat',
   'mockmail',
 ])

package/src/lib/server/storage.ts

@@ -698,7 +698,7 @@ if (!IS_BUILD_BOOTSTRAP) {
 - **Tasks** — The Task Board tracks work items. Assign agents and they'll execute autonomously.
 - **Schedules** — Cron-based recurring jobs that run agents or tasks automatically.
 - **Skills** — Reusable markdown instruction files agents can discover and use by default; pin them to keep favorite workflows always-on.
-- **Connectors** — Bridge agents to Discord, Slack, Telegram, or WhatsApp.
+- **Connectors** — Bridge agents to chat platforms, local file queues, and agent channels.
 - **Secrets** — Encrypted vault for API keys (Settings → Secrets).
 
 ## Tools

package/src/lib/validation/schemas.ts

@@ -161,7 +161,7 @@ export const ConnectorCreateSchema = z.object({
   name: z.string().min(1, 'Connector name is required').optional(),
   platform: z.enum([
     'discord', 'telegram', 'slack', 'whatsapp', 'openclaw',
-    'bluebubbles', 'signal', 'teams', 'googlechat', 'matrix', 'email', 'swarmdock',
+    'bluebubbles', 'signal', 'teams', 'googlechat', 'matrix', 'email', 'filequeue', 'swarmdock',
   ]),
   agentId: z.string().nullable().optional().default(null),
   chatroomId: z.string().nullable().optional().default(null),

package/src/types/connector.ts

@@ -28,6 +28,7 @@ export type ConnectorPlatform =
   | 'email'
   | 'webchat'
   | 'mockmail'
+  | 'filequeue'
   | 'swarmdock'
 export type ConnectorStatus = 'stopped' | 'running' | 'error' | 'starting'