@swarmclawai/swarmclaw 0.3.1 → 0.4.5

package/src/app/api/connectors/[id]/webhook/route.ts

@@ -0,0 +1,99 @@
+import { NextResponse } from 'next/server'
+import { loadConnectors } from '@/lib/server/storage'
+
+export const dynamic = 'force-dynamic'
+
+function readSecret(req: Request): string {
+  const url = new URL(req.url)
+  return (
+    req.headers.get('x-connector-secret')
+    || url.searchParams.get('secret')
+    || ''
+  ).trim()
+}
+
+function parseWebhookBody(rawBody: string): Record<string, unknown> {
+  const trimmed = rawBody.trim()
+  if (!trimmed) return {}
+
+  try {
+    const parsed = JSON.parse(trimmed)
+    if (Array.isArray(parsed)) return { data: parsed }
+    return parsed && typeof parsed === 'object' ? parsed as Record<string, unknown> : {}
+  } catch {
+    // Fall back to URL-encoded payloads used by some webhook providers.
+    const params = new URLSearchParams(rawBody)
+    const nested = params.get('payload') || params.get('data') || params.get('message') || ''
+    if (nested) {
+      try {
+        const parsedNested = JSON.parse(nested)
+        if (Array.isArray(parsedNested)) return { data: parsedNested }
+        return parsedNested && typeof parsedNested === 'object'
+          ? parsedNested as Record<string, unknown>
+          : {}
+      } catch {
+        // Ignore malformed nested JSON and return flat map below.
+      }
+    }
+    const out: Record<string, unknown> = {}
+    for (const [key, value] of params.entries()) out[key] = value
+    return out
+  }
+}
+
+export async function POST(req: Request, { params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params
+  const connectors = loadConnectors()
+  const connector = connectors[id]
+  if (!connector) return NextResponse.json({ error: 'Connector not found' }, { status: 404 })
+
+  const requiredSecret = String(connector.config?.webhookSecret || '').trim()
+  if (requiredSecret && readSecret(req) !== requiredSecret) {
+    return NextResponse.json({ error: 'Invalid connector webhook secret' }, { status: 401 })
+  }
+
+  const rawBody = await req.text().catch(() => '')
+  const payload = parseWebhookBody(rawBody)
+
+  try {
+    if (connector.platform === 'teams') {
+      const handlerKey = `__swarmclaw_teams_handler_${connector.id}__`
+      const handler = (globalThis as any)[handlerKey]
+      if (typeof handler !== 'function') {
+        return NextResponse.json({ error: 'Teams connector is not running or not ready' }, { status: 409 })
+      }
+      await handler(payload)
+      return NextResponse.json({ ok: true })
+    }
+
+    if (connector.platform === 'googlechat') {
+      const handlerKey = `__swarmclaw_googlechat_handler_${connector.id}__`
+      const handler = (globalThis as any)[handlerKey]
+      if (typeof handler !== 'function') {
+        return NextResponse.json({ error: 'Google Chat connector is not running or not ready' }, { status: 409 })
+      }
+      const result = await handler(payload)
+      if (result && typeof result === 'object' && Object.keys(result).length > 0) {
+        return NextResponse.json(result)
+      }
+      return NextResponse.json({})
+    }
+
+    if (connector.platform === 'bluebubbles') {
+      const handlerKey = `__swarmclaw_bluebubbles_handler_${connector.id}__`
+      const handler = (globalThis as any)[handlerKey]
+      if (typeof handler !== 'function') {
+        return NextResponse.json({ error: 'BlueBubbles connector is not running or not ready' }, { status: 409 })
+      }
+      const result = await handler(payload)
+      if (result && typeof result === 'object' && Object.keys(result).length > 0) {
+        return NextResponse.json(result)
+      }
+      return NextResponse.json({})
+    }
+
+    return NextResponse.json({ error: `Platform "${connector.platform}" does not support connector webhook ingress.` }, { status: 400 })
+  } catch (err: any) {
+    return NextResponse.json({ error: err?.message || 'Webhook processing failed' }, { status: 500 })
+  }
+}

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

@@ -1,9 +1,12 @@
 import { NextResponse } from 'next/server'
-import crypto from 'crypto'
+import { genId } from '@/lib/id'
 import { loadConnectors, saveConnectors } from '@/lib/server/storage'
+import { notify } from '@/lib/server/ws-hub'
 import type { Connector } from '@/types'
+export const dynamic = 'force-dynamic'
 
-export async function GET() {
+
+export async function GET(_req: Request) {
   const connectors = loadConnectors()
   // Merge runtime status from manager
   try {
@@ -24,7 +27,7 @@ export async function GET() {
 export async function POST(req: Request) {
   const body = await req.json()
   const connectors = loadConnectors()
-  const id = crypto.randomBytes(4).toString('hex')
+  const id = genId()
 
   const connector: Connector = {
     id,
@@ -42,9 +45,13 @@ export async function POST(req: Request) {
 
   connectors[id] = connector
   saveConnectors(connectors)
+  notify('connectors')
 
   // Auto-start if connector has credentials (or is WhatsApp which uses QR)
-  const hasCredentials = connector.platform === 'whatsapp' || connector.platform === 'openclaw' || !!connector.credentialId
+  const hasCredentials = connector.platform === 'whatsapp'
+    || connector.platform === 'openclaw'
+    || (connector.platform === 'bluebubbles' && (!!connector.credentialId || !!connector.config.password))
+    || !!connector.credentialId
   if (hasCredentials && body.autoStart !== false) {
     try {
       const { startConnector } = await import('@/lib/server/connectors/manager')
@@ -53,6 +60,7 @@ export async function POST(req: Request) {
       connector.status = 'running'
       connectors[id] = connector
       saveConnectors(connectors)
+      notify('connectors')
     } catch { /* auto-start is best-effort */ }
   }
 

package/src/app/api/credentials/[id]/route.ts

@@ -1,11 +1,12 @@
 import { NextResponse } from 'next/server'
 import { loadCredentials, saveCredentials } from '@/lib/server/storage'
+import { notFound } from '@/lib/server/collection-helpers'
 
 export async function DELETE(_req: Request, { params }: { params: Promise<{ id: string }> }) {
   const { id: credId } = await params
   const creds = loadCredentials()
   if (!creds[credId]) {
-    return new NextResponse(null, { status: 404 })
+    return notFound()
   }
   delete creds[credId]
   saveCredentials(creds)

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

@@ -1,8 +1,10 @@
 import { NextResponse } from 'next/server'
-import crypto from 'crypto'
+import { genId } from '@/lib/id'
 import { loadCredentials, saveCredentials, encryptKey } from '@/lib/server/storage'
+export const dynamic = 'force-dynamic'
 
-export async function GET() {
+
+export async function GET(_req: Request) {
   const creds = loadCredentials()
   const safe: Record<string, any> = {}
   for (const [id, c] of Object.entries(creds) as [string, any][]) {
@@ -16,7 +18,7 @@ export async function POST(req: Request) {
   if (!provider || !apiKey) {
     return NextResponse.json({ error: 'provider and apiKey are required' }, { status: 400 })
   }
-  const id = 'cred_' + crypto.randomBytes(6).toString('hex')
+  const id = 'cred_' + genId(6)
   const creds = loadCredentials()
   creds[id] = {
     id,

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

@@ -1,7 +1,10 @@
 import { NextResponse } from 'next/server'
 import { ensureDaemonStarted, getDaemonStatus, startDaemon, stopDaemon } from '@/lib/server/daemon-state'
+import { notify } from '@/lib/server/ws-hub'
+export const dynamic = 'force-dynamic'
 
-export async function GET() {
+
+export async function GET(_req: Request) {
   ensureDaemonStarted('api/daemon:get')
   return NextResponse.json(getDaemonStatus())
 }
@@ -12,9 +15,11 @@ export async function POST(req: Request) {
 
   if (action === 'start') {
     startDaemon({ source: 'api/daemon:post:start', manualStart: true })
+    notify('daemon')
     return NextResponse.json({ ok: true, status: 'running' })
   } else if (action === 'stop') {
     stopDaemon({ source: 'api/daemon:post:stop', manualStop: true })
+    notify('daemon')
     return NextResponse.json({ ok: true, status: 'stopped' })
   }
 

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

@@ -1,4 +1,4 @@
-import crypto from 'crypto'
+import { genId } from '@/lib/id'
 import { NextResponse } from 'next/server'
 import { loadDocuments, saveDocuments } from '@/lib/server/storage'
 
@@ -69,7 +69,7 @@ export async function POST(req: Request) {
   const body = await req.json().catch(() => ({}))
   const now = Date.now()
   const docs = loadDocuments()
-  const id = body.id || crypto.randomBytes(6).toString('hex')
+  const id = body.id || genId(6)
   const fileName = body.fileName || body.filename || ''
   const title = body.title || fileName || 'Untitled Document'
   const content = typeof body.content === 'string' ? body.content : ''

package/src/app/api/files/serve/route.ts

@@ -21,6 +21,14 @@ const MIME_MAP: Record<string, string> = {
   '.jsx': 'text/plain',
   '.py': 'text/plain',
   '.sh': 'text/plain',
+  '.pdf': 'application/pdf',
+  '.csv': 'text/csv',
+  '.xml': 'application/xml',
+  '.zip': 'application/zip',
+  '.doc': 'application/msword',
+  '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  '.xls': 'application/vnd.ms-excel',
+  '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
 }
 
 const MAX_SIZE = 10 * 1024 * 1024 // 10MB

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

@@ -1,6 +1,8 @@
 import { NextResponse } from 'next/server'
 import { localIP } from '@/lib/server/storage'
+export const dynamic = 'force-dynamic'
 
-export async function GET() {
+
+export async function GET(_req: Request) {
   return NextResponse.json({ ip: localIP(), port: parseInt(process.env.PORT || '3000') })
 }

package/src/app/api/knowledge/[id]/route.ts

@@ -1,4 +1,5 @@
 import { NextResponse } from 'next/server'
+import { notFound } from '@/lib/server/collection-helpers'
 import { getMemoryDb } from '@/lib/server/memory-db'
 
 export async function GET(_req: Request, { params }: { params: Promise<{ id: string }> }) {
@@ -6,7 +7,7 @@ export async function GET(_req: Request, { params }: { params: Promise<{ id: str
   const db = getMemoryDb()
   const entry = db.get(id)
   if (!entry || entry.category !== 'knowledge') {
-    return new NextResponse(null, { status: 404 })
+    return notFound()
   }
   return NextResponse.json(entry)
 }
@@ -16,7 +17,7 @@ export async function PUT(req: Request, { params }: { params: Promise<{ id: stri
   const db = getMemoryDb()
   const existing = db.get(id)
   if (!existing || existing.category !== 'knowledge') {
-    return new NextResponse(null, { status: 404 })
+    return notFound()
   }
 
   const body = await req.json().catch(() => null)
@@ -44,7 +45,7 @@ export async function PUT(req: Request, { params }: { params: Promise<{ id: stri
 
   const updated = db.update(id, updates)
   if (!updated) {
-    return new NextResponse(null, { status: 404 })
+    return notFound()
   }
   return NextResponse.json(updated)
 }
@@ -54,7 +55,7 @@ export async function DELETE(_req: Request, { params }: { params: Promise<{ id:
   const db = getMemoryDb()
   const existing = db.get(id)
   if (!existing || existing.category !== 'knowledge') {
-    return new NextResponse(null, { status: 404 })
+    return notFound()
   }
   db.delete(id)
   return NextResponse.json({ deleted: id })

package/src/app/api/knowledge/upload/route.ts

@@ -1,7 +1,7 @@
 import { NextResponse } from 'next/server'
 import fs from 'fs'
 import path from 'path'
-import crypto from 'crypto'
+import { genId } from '@/lib/id'
 import { UPLOAD_DIR } from '@/lib/server/storage'
 
 const TEXT_EXTS = new Set([
@@ -40,7 +40,7 @@ export async function POST(req: Request) {
 
   // Save file to uploads
   if (!fs.existsSync(UPLOAD_DIR)) fs.mkdirSync(UPLOAD_DIR, { recursive: true })
-  const safeName = crypto.randomBytes(4).toString('hex') + '-' + filename.replace(/[^a-zA-Z0-9._-]/g, '_')
+  const safeName = genId() + '-' + filename.replace(/[^a-zA-Z0-9._-]/g, '_')
   const filePath = path.join(UPLOAD_DIR, safeName)
   fs.writeFileSync(filePath, buf)
 

package/src/app/api/mcp-servers/[id]/route.ts

@@ -1,32 +1,29 @@
 import { NextResponse } from 'next/server'
 import { loadMcpServers, saveMcpServers, deleteMcpServer } from '@/lib/server/storage'
+import { mutateItem, deleteItem, notFound, type CollectionOps } from '@/lib/server/collection-helpers'
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const ops: CollectionOps<any> = { load: loadMcpServers, save: saveMcpServers, deleteFn: deleteMcpServer }
 
 export async function GET(_req: Request, { params }: { params: Promise<{ id: string }> }) {
   const { id } = await params
   const servers = loadMcpServers()
-  if (!servers[id]) return new NextResponse(null, { status: 404 })
+  if (!servers[id]) return notFound()
   return NextResponse.json(servers[id])
 }
 
 export async function PUT(req: Request, { params }: { params: Promise<{ id: string }> }) {
   const { id } = await params
   const body = await req.json()
-  const servers = loadMcpServers()
-  if (!servers[id]) return new NextResponse(null, { status: 404 })
-  servers[id] = {
-    ...servers[id],
-    ...body,
-    id,
-    updatedAt: Date.now(),
-  }
-  saveMcpServers(servers)
-  return NextResponse.json(servers[id])
+  const result = mutateItem(ops, id, (server) => ({
+    ...server, ...body, id, updatedAt: Date.now(),
+  }))
+  if (!result) return notFound()
+  return NextResponse.json(result)
 }
 
 export async function DELETE(_req: Request, { params }: { params: Promise<{ id: string }> }) {
   const { id } = await params
-  const servers = loadMcpServers()
-  if (!servers[id]) return new NextResponse(null, { status: 404 })
-  deleteMcpServer(id)
+  if (!deleteItem(ops, id)) return notFound()
   return NextResponse.json({ deleted: id })
 }

package/src/app/api/mcp-servers/[id]/test/route.ts

@@ -1,12 +1,13 @@
 import { NextResponse } from 'next/server'
 import { loadMcpServers } from '@/lib/server/storage'
+import { notFound } from '@/lib/server/collection-helpers'
 import { connectMcpServer, mcpToolsToLangChain, disconnectMcpServer } from '@/lib/server/mcp-client'
 
 export async function POST(_req: Request, { params }: { params: Promise<{ id: string }> }) {
   const { id } = await params
   const servers = loadMcpServers()
   const server = servers[id]
-  if (!server) return new NextResponse(null, { status: 404 })
+  if (!server) return notFound()
 
   try {
     const { client, transport } = await connectMcpServer(server)

package/src/app/api/mcp-servers/[id]/tools/route.ts

@@ -1,12 +1,13 @@
 import { NextResponse } from 'next/server'
 import { loadMcpServers } from '@/lib/server/storage'
+import { notFound } from '@/lib/server/collection-helpers'
 import { connectMcpServer, disconnectMcpServer } from '@/lib/server/mcp-client'
 
 export async function GET(_req: Request, { params }: { params: Promise<{ id: string }> }) {
   const { id } = await params
   const servers = loadMcpServers()
   const config = servers[id]
-  if (!config) return new NextResponse(null, { status: 404 })
+  if (!config) return notFound()
 
   let client: any
   let transport: any

package/src/app/api/mcp-servers/route.ts

@@ -1,15 +1,17 @@
 import { NextResponse } from 'next/server'
-import crypto from 'crypto'
+import { genId } from '@/lib/id'
 import { loadMcpServers, saveMcpServers } from '@/lib/server/storage'
+export const dynamic = 'force-dynamic'
 
-export async function GET() {
+
+export async function GET(_req: Request) {
   return NextResponse.json(loadMcpServers())
 }
 
 export async function POST(req: Request) {
   const body = await req.json()
   const servers = loadMcpServers()
-  const id = crypto.randomBytes(4).toString('hex')
+  const id = genId()
   servers[id] = {
     id,
     name: body.name,

package/src/app/api/memory/[id]/route.ts

@@ -1,6 +1,7 @@
-import crypto from 'crypto'
+import { genId } from '@/lib/id'
 import fs from 'fs'
 import { NextResponse } from 'next/server'
+import { notFound } from '@/lib/server/collection-helpers'
 import { getMemoryDb, getMemoryLookupLimits, storeMemoryImageAsset, storeMemoryImageFromDataUrl } from '@/lib/server/memory-db'
 import { resolveLookupRequest } from '@/lib/server/memory-graph'
 import type { MemoryImage } from '@/types'
@@ -42,7 +43,7 @@ export async function GET(req: Request, { params }: { params: Promise<{ id: stri
 
   if (limits.maxDepth <= 0) {
     const entry = db.get(id)
-    if (!entry) return new NextResponse(null, { status: 404 })
+    if (!entry) return notFound()
     if (envelope) {
       return NextResponse.json({
         entries: [entry],
@@ -55,7 +56,7 @@ export async function GET(req: Request, { params }: { params: Promise<{ id: stri
   }
 
   const result = db.getWithLinked(id, limits.maxDepth, limits.maxPerLookup, limits.maxLinkedExpansion)
-  if (!result) return new NextResponse(null, { status: 404 })
+  if (!result) return notFound()
   if (envelope) return NextResponse.json(result)
   return NextResponse.json(result.entries)
 }
@@ -78,7 +79,7 @@ export async function PUT(req: Request, { params }: { params: Promise<{ id: stri
     const updated = linkAction === 'link'
       ? db.link(id, targetIds, true)
       : db.unlink(id, targetIds, true)
-    if (!updated) return new NextResponse(null, { status: 404 })
+    if (!updated) return notFound()
     return NextResponse.json(updated)
   }
 
@@ -90,7 +91,7 @@ export async function PUT(req: Request, { params }: { params: Promise<{ id: stri
     image = null
   } else if (inputImageDataUrl) {
     try {
-      image = await storeMemoryImageFromDataUrl(inputImageDataUrl, `${id}-${crypto.randomBytes(2).toString('hex')}`)
+      image = await storeMemoryImageFromDataUrl(inputImageDataUrl, `${id}-${genId(2)}`)
     } catch (err) {
       return NextResponse.json({ error: err instanceof Error ? err.message : 'Invalid image data URL' }, { status: 400 })
     }
@@ -99,7 +100,7 @@ export async function PUT(req: Request, { params }: { params: Promise<{ id: stri
       return NextResponse.json({ error: `Image file not found: ${inputImagePath}` }, { status: 400 })
     }
     try {
-      image = await storeMemoryImageAsset(inputImagePath, `${id}-${crypto.randomBytes(2).toString('hex')}`)
+      image = await storeMemoryImageAsset(inputImagePath, `${id}-${genId(2)}`)
     } catch (err) {
       return NextResponse.json({ error: err instanceof Error ? err.message : 'Failed to store memory image' }, { status: 400 })
     }
@@ -114,7 +115,7 @@ export async function PUT(req: Request, { params }: { params: Promise<{ id: stri
         ? String((image as { path: string }).path)
         : (typeof body.imagePath === 'string' ? body.imagePath : undefined),
   })
-  if (!entry) return new NextResponse(null, { status: 404 })
+  if (!entry) return notFound()
   return NextResponse.json(entry)
 }
 
@@ -122,5 +123,5 @@ export async function DELETE(_req: Request, { params }: { params: Promise<{ id:
   const { id } = await params
   const db = getMemoryDb()
   db.delete(id)
-  return NextResponse.json('ok')
+  return NextResponse.json({ ok: true })
 }

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

@@ -1,4 +1,4 @@
-import crypto from 'crypto'
+import { genId } from '@/lib/id'
 import fs from 'fs'
 import { NextResponse } from 'next/server'
 import { getMemoryDb, getMemoryLookupLimits, storeMemoryImageAsset, storeMemoryImageFromDataUrl } from '@/lib/server/memory-db'
@@ -72,7 +72,7 @@ export async function POST(req: Request) {
   }
 
   const db = getMemoryDb()
-  const draftId = crypto.randomBytes(6).toString('hex')
+  const draftId = genId(6)
 
   let image = body.image
   const inputImagePath = typeof body.imagePath === 'string' ? body.imagePath.trim() : ''

package/src/app/api/memory-images/[filename]/route.ts

@@ -1,4 +1,5 @@
 import { NextResponse } from 'next/server'
+import { notFound } from '@/lib/server/collection-helpers'
 import fs from 'fs'
 import path from 'path'
 
@@ -20,7 +21,7 @@ export async function GET(_req: Request, { params }: { params: Promise<{ filenam
   const filePath = path.join(IMAGES_DIR, safeName)
 
   if (!fs.existsSync(filePath)) {
-    return new NextResponse(null, { status: 404 })
+    return notFound()
   }
 
   const ext = path.extname(safeName).toLowerCase()

package/src/app/api/openclaw/directory/route.ts

@@ -0,0 +1,26 @@
+import { NextResponse } from 'next/server'
+export const dynamic = 'force-dynamic'
+
+export async function GET() {
+  try {
+    const { listRunningConnectors, getRunningInstance } = await import('@/lib/server/connectors/manager')
+    const openclawConnectors = listRunningConnectors('openclaw')
+
+    if (!openclawConnectors.length) {
+      return NextResponse.json({ devices: [], note: 'No running OpenClaw connector.' })
+    }
+
+    // The directory.list RPC requires gateway support — degrade gracefully
+    return NextResponse.json({
+      devices: [],
+      connectors: openclawConnectors.map((c) => ({
+        id: c.id,
+        name: c.name,
+        platform: c.platform,
+      })),
+      note: 'Directory listing requires OpenClaw gateway directory.list RPC support.',
+    })
+  } catch (err: any) {
+    return NextResponse.json({ error: err.message || 'Directory listing failed' }, { status: 500 })
+  }
+}

package/src/app/api/openclaw/discover/route.ts

@@ -0,0 +1,61 @@
+import { NextResponse } from 'next/server'
+import os from 'node:os'
+import { probeOpenClawHealth } from '@/lib/server/openclaw-health'
+export const dynamic = 'force-dynamic'
+
+const DEFAULT_PORTS = [18789, 18790]
+const PROBE_TIMEOUT_MS = 4000
+
+function getLanIps(): string[] {
+  const interfaces = os.networkInterfaces()
+  const ips: string[] = []
+  for (const iface of Object.values(interfaces)) {
+    if (!iface) continue
+    for (const info of iface) {
+      if (info.family === 'IPv4' && !info.internal) {
+        ips.push(info.address)
+      }
+    }
+  }
+  return ips
+}
+
+export async function GET() {
+  try {
+    const hosts = ['127.0.0.1', ...getLanIps()]
+    const probes: Array<Promise<{
+      host: string
+      port: number
+      healthy: boolean
+      models?: string[]
+      error?: string
+    }>> = []
+
+    for (const host of hosts) {
+      for (const port of DEFAULT_PORTS) {
+        probes.push(
+          probeOpenClawHealth({
+            endpoint: `http://${host}:${port}`,
+            timeoutMs: PROBE_TIMEOUT_MS,
+          }).then((result) => ({
+            host,
+            port,
+            healthy: result.ok,
+            models: result.models.length > 0 ? result.models : undefined,
+            error: result.error || undefined,
+          })).catch(() => ({
+            host,
+            port,
+            healthy: false,
+            error: 'unreachable',
+          })),
+        )
+      }
+    }
+
+    const results = await Promise.all(probes)
+    return NextResponse.json({ gateways: results })
+  } catch (err: any) {
+    return NextResponse.json({ error: err.message || 'Discovery failed' }, { status: 500 })
+  }
+}

package/src/app/api/openclaw/sync/route.ts

@@ -0,0 +1,30 @@
+import { NextResponse } from 'next/server'
+import { runSync, type SyncType } from '@/lib/server/openclaw-sync'
+export const dynamic = 'force-dynamic'
+
+const VALID_ACTIONS = new Set(['push', 'pull', 'both'])
+const VALID_TYPES: SyncType[] = ['memory', 'workspace', 'schedules', 'credentials', 'plugins']
+
+export async function POST(req: Request) {
+  try {
+    const body = await req.json()
+    const action = body.action
+    const types = body.types
+
+    if (!action || !VALID_ACTIONS.has(action)) {
+      return NextResponse.json({ error: 'Invalid action. Use push, pull, or both.' }, { status: 400 })
+    }
+    if (!Array.isArray(types) || types.length === 0) {
+      return NextResponse.json({ error: 'types must be a non-empty array.' }, { status: 400 })
+    }
+    const validTypes = types.filter((t: string) => VALID_TYPES.includes(t as SyncType)) as SyncType[]
+    if (validTypes.length === 0) {
+      return NextResponse.json({ error: `No valid types. Use: ${VALID_TYPES.join(', ')}` }, { status: 400 })
+    }
+
+    const results = await runSync({ action, types: validTypes })
+    return NextResponse.json({ ok: true, results })
+  } catch (err: any) {
+    return NextResponse.json({ error: err.message || 'Sync failed' }, { status: 500 })
+  }
+}

package/src/app/api/orchestrator/graph/route.ts

@@ -0,0 +1,25 @@
+import { NextResponse } from 'next/server'
+export const dynamic = 'force-dynamic'
+
+
+export async function GET(_req: Request) {
+  return NextResponse.json({
+    nodes: [
+      { id: 'agent', description: 'LLM reasoning node — calls the model with tools bound' },
+      { id: 'tools', description: 'Tool execution node — runs tool calls from the agent' },
+      { id: 'router', description: 'Routing node — inspects tool results, handles fallback on delegate failures' },
+    ],
+    edges: [
+      { from: '__start__', to: 'agent', type: 'direct' },
+      { from: 'agent', to: 'tools', type: 'conditional', condition: 'has_tool_calls' },
+      { from: 'agent', to: '__end__', type: 'conditional', condition: 'no_tool_calls' },
+      { from: 'tools', to: 'router', type: 'direct' },
+      { from: 'router', to: 'agent', type: 'conditional', condition: 'fallback_or_continue' },
+    ],
+    features: {
+      checkpointing: true,
+      interruptBefore: 'tools (when capability policy is strict)',
+      fallbackRouting: 'Max 2 attempts when delegate_to_agent fails',
+    },
+  })
+}