@swarmclawai/swarmclaw 0.2.0

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

@@ -0,0 +1,28 @@
+import { NextResponse } from 'next/server'
+import { loadSchedules, saveSchedules, deleteSchedule } from '@/lib/server/storage'
+import { resolveScheduleName } from '@/lib/schedule-name'
+
+export async function PUT(req: Request, { params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params
+  const body = await req.json()
+  const schedules = loadSchedules()
+  if (!schedules[id]) return new NextResponse(null, { status: 404 })
+
+  const origId = id
+  Object.assign(schedules[id], body)
+  schedules[id].id = origId
+  schedules[id].name = resolveScheduleName({
+    name: schedules[id].name,
+    taskPrompt: schedules[id].taskPrompt,
+  })
+  saveSchedules(schedules)
+  return NextResponse.json(schedules[id])
+}
+
+export async function DELETE(_req: Request, { params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params
+  const schedules = loadSchedules()
+  if (!schedules[id]) return new NextResponse(null, { status: 404 })
+  deleteSchedule(id)
+  return NextResponse.json('ok')
+}

package/src/app/api/schedules/[id]/run/route.ts

@@ -0,0 +1,104 @@
+import { NextResponse } from 'next/server'
+import crypto from 'crypto'
+import { loadSchedules, saveSchedules, loadAgents, loadTasks, saveTasks } from '@/lib/server/storage'
+import { enqueueTask } from '@/lib/server/queue'
+import { pushMainLoopEventToMainSessions } from '@/lib/server/main-agent-loop'
+import { getScheduleSignatureKey } from '@/lib/schedule-dedupe'
+
+type InFlightTask = {
+  status?: string
+  sourceScheduleKey?: string | null
+}
+
+export async function POST(_req: Request, { params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params
+  const schedules = loadSchedules()
+  const schedule = schedules[id]
+  if (!schedule) return new NextResponse(null, { status: 404 })
+
+  const agents = loadAgents()
+  const agent = agents[schedule.agentId]
+  if (!agent) return NextResponse.json({ error: 'Agent not found' }, { status: 400 })
+
+  const tasks = loadTasks()
+  const scheduleSignature = getScheduleSignatureKey(schedule)
+  if (scheduleSignature) {
+    const inFlight = Object.values(tasks as Record<string, InFlightTask>).some((task) =>
+      task
+      && (task.status === 'queued' || task.status === 'running')
+      && task.sourceScheduleKey === scheduleSignature,
+    )
+    if (inFlight) {
+      return NextResponse.json({ ok: true, queued: false, reason: 'in_flight' })
+    }
+  }
+
+  const now = Date.now()
+  schedule.runNumber = (schedule.runNumber || 0) + 1
+
+  // Reuse linked task if it exists and is not in-flight
+  let taskId = ''
+  const existingTaskId = typeof schedule.linkedTaskId === 'string' ? schedule.linkedTaskId : ''
+  const existingTask = existingTaskId ? tasks[existingTaskId] : null
+
+  if (existingTask && existingTask.status !== 'queued' && existingTask.status !== 'running') {
+    taskId = existingTaskId
+    const prev = existingTask as Record<string, unknown>
+    prev.totalRuns = ((prev.totalRuns as number) || 0) + 1
+    if (existingTask.status === 'completed') prev.totalCompleted = ((prev.totalCompleted as number) || 0) + 1
+    if (existingTask.status === 'failed') prev.totalFailed = ((prev.totalFailed as number) || 0) + 1
+
+    existingTask.status = 'backlog'
+    existingTask.title = `[Sched] ${schedule.name} (run #${schedule.runNumber})`
+    existingTask.result = null
+    existingTask.error = null
+    existingTask.sessionId = null
+    existingTask.updatedAt = now
+    existingTask.queuedAt = null
+    existingTask.startedAt = null
+    existingTask.completedAt = null
+    existingTask.archivedAt = null
+    existingTask.attempts = 0
+    existingTask.retryScheduledAt = null
+    existingTask.deadLetteredAt = null
+    existingTask.validation = null
+    prev.runNumber = schedule.runNumber
+  } else {
+    taskId = crypto.randomBytes(4).toString('hex')
+    tasks[taskId] = {
+      id: taskId,
+      title: `[Sched] ${schedule.name} (run #${schedule.runNumber})`,
+      description: schedule.taskPrompt || '',
+      status: 'backlog',
+      agentId: schedule.agentId,
+      sessionId: null,
+      result: null,
+      error: null,
+      createdAt: now,
+      updatedAt: now,
+      queuedAt: null,
+      startedAt: null,
+      completedAt: null,
+      sourceType: 'schedule',
+      sourceScheduleId: schedule.id,
+      sourceScheduleName: schedule.name,
+      sourceScheduleKey: scheduleSignature || null,
+      createdInSessionId: schedule.createdInSessionId || null,
+      createdByAgentId: schedule.createdByAgentId || null,
+      runNumber: schedule.runNumber,
+    }
+    schedule.linkedTaskId = taskId
+  }
+
+  saveTasks(tasks)
+  enqueueTask(taskId)
+  pushMainLoopEventToMainSessions({
+    type: 'schedule_fired',
+    text: `Schedule fired manually: "${schedule.name}" (${schedule.id}) run #${schedule.runNumber} — task ${taskId}`,
+  })
+
+  schedule.lastRunAt = now
+  saveSchedules(schedules)
+
+  return NextResponse.json({ ok: true, queued: true, taskId, runNumber: schedule.runNumber })
+}

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

@@ -0,0 +1,78 @@
+import { NextResponse } from 'next/server'
+import crypto from 'crypto'
+import { loadSchedules, saveSchedules } from '@/lib/server/storage'
+import { resolveScheduleName } from '@/lib/schedule-name'
+import { findDuplicateSchedule } from '@/lib/schedule-dedupe'
+
+export async function GET() {
+  return NextResponse.json(loadSchedules())
+}
+
+export async function POST(req: Request) {
+  const body = await req.json()
+  const now = Date.now()
+  const schedules = loadSchedules()
+  const scheduleType = body.scheduleType || 'cron'
+
+  const duplicate = findDuplicateSchedule(schedules, {
+    agentId: body.agentId || null,
+    taskPrompt: body.taskPrompt || '',
+    scheduleType,
+    cron: body.cron,
+    intervalMs: body.intervalMs,
+    runAt: body.runAt,
+  })
+  if (duplicate) {
+    const duplicateId = duplicate.id || ''
+    let changed = false
+    const nextName = resolveScheduleName({
+      name: body.name ?? duplicate.name,
+      taskPrompt: body.taskPrompt ?? duplicate.taskPrompt,
+    })
+    if (nextName && nextName !== duplicate.name) {
+      duplicate.name = nextName
+      changed = true
+    }
+    const normalizedStatus = typeof body.status === 'string' ? body.status.trim().toLowerCase() : ''
+    if ((normalizedStatus === 'active' || normalizedStatus === 'paused') && duplicate.status !== normalizedStatus) {
+      duplicate.status = normalizedStatus as 'active' | 'paused'
+      changed = true
+    }
+    if (changed) {
+      const mutableDuplicate = duplicate as Record<string, unknown>
+      mutableDuplicate.updatedAt = now
+      if (duplicateId) schedules[duplicateId] = duplicate
+      saveSchedules(schedules)
+    }
+    return NextResponse.json(duplicate)
+  }
+
+  const id = crypto.randomBytes(4).toString('hex')
+
+  let nextRunAt: number | undefined
+  if (scheduleType === 'once' && body.runAt) {
+    nextRunAt = body.runAt
+  } else if (scheduleType === 'interval' && body.intervalMs) {
+    nextRunAt = now + body.intervalMs
+  } else if (scheduleType === 'cron') {
+    // nextRunAt will be computed by the scheduler engine
+    nextRunAt = undefined
+  }
+
+  schedules[id] = {
+    id,
+    name: resolveScheduleName({ name: body.name, taskPrompt: body.taskPrompt }),
+    agentId: body.agentId,
+    taskPrompt: body.taskPrompt || '',
+    scheduleType,
+    cron: body.cron,
+    intervalMs: body.intervalMs,
+    runAt: body.runAt,
+    lastRunAt: undefined,
+    nextRunAt,
+    status: body.status || 'active',
+    createdAt: now,
+  }
+  saveSchedules(schedules)
+  return NextResponse.json(schedules[id])
+}

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

@@ -0,0 +1,29 @@
+import { NextResponse } from 'next/server'
+import { loadSecrets, saveSecrets } from '@/lib/server/storage'
+
+export async function DELETE(_req: Request, { params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params
+  const secrets = loadSecrets()
+  if (!secrets[id]) return new NextResponse(null, { status: 404 })
+  delete secrets[id]
+  saveSecrets(secrets)
+  return NextResponse.json('ok')
+}
+
+export async function PUT(req: Request, { params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params
+  const body = await req.json()
+  const secrets = loadSecrets()
+  if (!secrets[id]) return new NextResponse(null, { status: 404 })
+
+  // Update metadata only (not the encrypted value unless a new value is provided)
+  if (body.name !== undefined) secrets[id].name = body.name
+  if (body.service !== undefined) secrets[id].service = body.service
+  if (body.scope !== undefined) secrets[id].scope = body.scope
+  if (body.agentIds !== undefined) secrets[id].agentIds = body.agentIds
+  secrets[id].updatedAt = Date.now()
+  saveSecrets(secrets)
+
+  const { encryptedValue, ...safe } = secrets[id]
+  return NextResponse.json(safe)
+}

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

@@ -0,0 +1,42 @@
+import { NextResponse } from 'next/server'
+import crypto from 'crypto'
+import { loadSecrets, saveSecrets, encryptKey } from '@/lib/server/storage'
+
+export async function GET() {
+  // Return secrets WITHOUT the encrypted values (just metadata)
+  const secrets = loadSecrets()
+  const safe = Object.fromEntries(
+    Object.entries(secrets).map(([id, s]: [string, any]) => [
+      id,
+      { id: s.id, name: s.name, service: s.service, scope: s.scope, agentIds: s.agentIds, createdAt: s.createdAt, updatedAt: s.updatedAt },
+    ])
+  )
+  return NextResponse.json(safe)
+}
+
+export async function POST(req: Request) {
+  const body = await req.json()
+  const id = crypto.randomBytes(4).toString('hex')
+  const now = Date.now()
+  const secrets = loadSecrets()
+
+  if (!body.value?.trim()) {
+    return NextResponse.json({ error: 'value is required' }, { status: 400 })
+  }
+
+  secrets[id] = {
+    id,
+    name: body.name || 'Unnamed Secret',
+    service: body.service || 'custom',
+    encryptedValue: encryptKey(body.value),
+    scope: body.scope || 'global',
+    agentIds: body.agentIds || [],
+    createdAt: now,
+    updatedAt: now,
+  }
+  saveSecrets(secrets)
+
+  // Return without encrypted value
+  const { encryptedValue, ...safe } = secrets[id]
+  return NextResponse.json(safe)
+}

package/src/app/api/sessions/[id]/browser/route.ts

@@ -0,0 +1,13 @@
+import { NextResponse } from 'next/server'
+import { hasActiveBrowser, cleanupSessionBrowser } from '@/lib/server/session-tools'
+
+export async function GET(_req: Request, { params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params
+  return NextResponse.json({ active: hasActiveBrowser(id) })
+}
+
+export async function DELETE(_req: Request, { params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params
+  cleanupSessionBrowser(id)
+  return new NextResponse('OK')
+}

package/src/app/api/sessions/[id]/chat/route.ts

@@ -0,0 +1,96 @@
+import { NextResponse } from 'next/server'
+import { enqueueSessionRun, type SessionQueueMode } from '@/lib/server/session-run-manager'
+import { log } from '@/lib/server/logger'
+
+function normalizeQueueMode(raw: unknown, internal: boolean): SessionQueueMode {
+  if (raw === 'steer' || raw === 'collect' || raw === 'followup') return raw
+  return internal ? 'collect' : 'followup'
+}
+
+export async function POST(req: Request, { params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params
+  const body = await req.json().catch(() => ({}))
+
+  const message = typeof body.message === 'string' ? body.message : ''
+  const imagePath = typeof body.imagePath === 'string' ? body.imagePath : undefined
+  const imageUrl = typeof body.imageUrl === 'string' ? body.imageUrl : undefined
+  const internal = body.internal === true
+  const queueMode = normalizeQueueMode(body.queueMode, internal)
+
+  if (!message.trim()) {
+    return NextResponse.json({ error: 'message is required' }, { status: 400 })
+  }
+
+  const encoder = new TextEncoder()
+  const stream = new ReadableStream({
+    start(controller) {
+      let closed = false
+      const writeEvent = (event: Record<string, unknown>) => {
+        if (closed) return
+        try {
+          controller.enqueue(encoder.encode(`data: ${JSON.stringify(event)}\n\n`))
+        } catch {
+          closed = true
+        }
+      }
+
+      const run = enqueueSessionRun({
+        sessionId: id,
+        message,
+        imagePath,
+        imageUrl,
+        internal,
+        source: internal ? 'heartbeat' : 'chat',
+        mode: queueMode,
+        onEvent: (ev) => writeEvent(ev as unknown as Record<string, unknown>),
+      })
+
+      log.info('chat', `Enqueued session run ${run.runId}`, {
+        sessionId: id,
+        internal,
+        mode: queueMode,
+        position: run.position,
+        deduped: run.deduped || false,
+        coalesced: run.coalesced || false,
+      })
+
+      writeEvent({
+        t: 'md',
+        text: JSON.stringify({
+          run: {
+            id: run.runId,
+            status: run.deduped ? 'deduped' : run.coalesced ? 'coalesced' : 'queued',
+            position: run.position,
+            internal,
+            mode: queueMode,
+          },
+        }),
+      })
+
+      run.promise
+        .catch((err) => {
+          const msg = err?.message || String(err)
+          writeEvent({ t: 'err', text: msg })
+        })
+        .finally(() => {
+          writeEvent({ t: 'done' })
+          if (!closed) {
+            try { controller.close() } catch { /* stream already closed */ }
+            closed = true
+          }
+        })
+    },
+    cancel() {
+      // Client disconnected; subsequent writes should be ignored.
+    },
+  })
+
+  return new NextResponse(stream, {
+    headers: {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      'Connection': 'keep-alive',
+      'X-Accel-Buffering': 'no',
+    },
+  })
+}

package/src/app/api/sessions/[id]/clear/route.ts

@@ -0,0 +1,19 @@
+import { NextResponse } from 'next/server'
+import { loadSessions, saveSessions } from '@/lib/server/storage'
+
+export async function POST(_req: Request, { params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params
+  const sessions = loadSessions()
+  if (!sessions[id]) return new NextResponse(null, { status: 404 })
+  sessions[id].messages = []
+  sessions[id].claudeSessionId = null
+  sessions[id].codexThreadId = null
+  sessions[id].opencodeSessionId = null
+  sessions[id].delegateResumeIds = {
+    claudeCode: null,
+    codex: null,
+    opencode: null,
+  }
+  saveSessions(sessions)
+  return new NextResponse('OK')
+}

package/src/app/api/sessions/[id]/deploy/route.ts

@@ -0,0 +1,34 @@
+import { NextResponse } from 'next/server'
+import { execSync } from 'child_process'
+import { loadSessions } from '@/lib/server/storage'
+
+export async function POST(req: Request, { params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params
+  const sessions = loadSessions()
+  const session = sessions[id]
+  if (!session) return new NextResponse(null, { status: 404 })
+
+  const body = await req.json()
+  const msg = body.message || 'Deploy from SwarmClaw'
+
+  try {
+    const opts = { cwd: session.cwd, encoding: 'utf8' as const, timeout: 30000 }
+    execSync('git add -A', opts)
+    let committed = false
+    try {
+      execSync(`git commit -m "${msg.replace(/"/g, '\\"')}"`, opts)
+      committed = true
+    } catch (ce: any) {
+      if (!(ce.stdout || ce.stderr || '').includes('nothing to commit')) throw ce
+    }
+    execSync('git push 2>&1', opts)
+    console.log(`[${id}] deployed: ${msg}`)
+    return NextResponse.json({ ok: true, output: committed ? 'Committed and pushed!' : 'Already committed — pushed to remote!' })
+  } catch (e: any) {
+    console.error(`[${id}] deploy error:`, e.message)
+    return NextResponse.json(
+      { ok: false, error: (e.stderr || e.stdout || e.message).toString().slice(0, 300) },
+      { status: 500 },
+    )
+  }
+}

package/src/app/api/sessions/[id]/devserver/route.ts

@@ -0,0 +1,69 @@
+import { NextResponse } from 'next/server'
+import { spawn } from 'child_process'
+import { loadSessions, devServers, localIP } from '@/lib/server/storage'
+
+export async function POST(req: Request, { params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params
+  const sessions = loadSessions()
+  const session = sessions[id]
+  if (!session) return new NextResponse(null, { status: 404 })
+
+  const { action } = await req.json()
+
+  if (action === 'start') {
+    if (devServers.has(id)) {
+      const ds = devServers.get(id)!
+      return NextResponse.json({ running: true, url: ds.url })
+    }
+
+    const proc = spawn('npm', ['run', 'dev', '--', '--host', '0.0.0.0'], {
+      cwd: session.cwd,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: { ...process.env, FORCE_COLOR: '0' },
+    })
+
+    let output = ''
+    let detectedUrl: string | null = null
+    const urlRe = /https?:\/\/(?:localhost|0\.0\.0\.0|[\d.]+):(\d+)/
+
+    function onData(chunk: Buffer) {
+      output += chunk.toString()
+      if (!detectedUrl) {
+        const match = output.match(urlRe)
+        if (match) {
+          const port = match[1]
+          detectedUrl = `http://${localIP()}:${port}`
+          const ds = devServers.get(id)
+          if (ds) ds.url = detectedUrl
+        }
+      }
+    }
+
+    proc.stdout!.on('data', onData)
+    proc.stderr!.on('data', onData)
+    proc.on('close', () => { devServers.delete(id); console.log(`[${id}] dev server stopped`) })
+    proc.on('error', () => devServers.delete(id))
+
+    devServers.set(id, { proc, url: `http://${localIP()}:4321` })
+    console.log(`[${id}] starting dev server in ${session.cwd}`)
+
+    // Wait for URL detection
+    await new Promise(resolve => setTimeout(resolve, 4000))
+    const ds = devServers.get(id)
+    return NextResponse.json({ running: !!ds, url: ds?.url || `http://${localIP()}:4321` })
+
+  } else if (action === 'stop') {
+    if (devServers.has(id)) {
+      const ds = devServers.get(id)!
+      try { ds.proc.kill('SIGTERM') } catch {}
+      try { process.kill(-ds.proc.pid, 'SIGTERM') } catch {}
+      devServers.delete(id)
+    }
+    return NextResponse.json({ running: false })
+
+  } else if (action === 'status') {
+    return NextResponse.json({ running: devServers.has(id), url: devServers.get(id)?.url })
+  }
+
+  return NextResponse.json({ running: false })
+}

package/src/app/api/sessions/[id]/mailbox/route.ts

@@ -0,0 +1,70 @@
+import { NextResponse } from 'next/server'
+import { ackMailboxEnvelope, clearMailbox, listMailbox, sendMailboxEnvelope } from '@/lib/server/session-mailbox'
+import { loadSessions } from '@/lib/server/storage'
+
+function parseIntParam(value: string | null, fallback: number, min: number, max: number): number {
+  const parsed = value ? Number.parseInt(value, 10) : Number.NaN
+  if (!Number.isFinite(parsed)) return fallback
+  return Math.max(min, Math.min(max, Math.trunc(parsed)))
+}
+
+export async function GET(req: Request, { params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params
+  const { searchParams } = new URL(req.url)
+  const limit = parseIntParam(searchParams.get('limit'), 50, 1, 500)
+  const includeAcked = searchParams.get('includeAcked') === 'true'
+  try {
+    const envelopes = listMailbox(id, { limit, includeAcked })
+    return NextResponse.json({ sessionId: id, count: envelopes.length, envelopes })
+  } catch (err: any) {
+    return NextResponse.json({ error: err?.message || 'Failed to load mailbox.' }, { status: 404 })
+  }
+}
+
+export async function POST(req: Request, { params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params
+  const body = await req.json().catch(() => ({}))
+  const action = typeof body?.action === 'string' ? body.action : 'send'
+  const sessions = loadSessions()
+  const current = sessions[id]
+  if (!current) return NextResponse.json({ error: `Session not found: ${id}` }, { status: 404 })
+
+  try {
+    if (action === 'send') {
+      const toSessionId = typeof body?.toSessionId === 'string' ? body.toSessionId : ''
+      const payload = typeof body?.payload === 'string' ? body.payload : ''
+      const type = typeof body?.type === 'string' ? body.type : 'message'
+      if (!toSessionId) return NextResponse.json({ error: 'toSessionId is required for send.' }, { status: 400 })
+      if (!payload.trim()) return NextResponse.json({ error: 'payload is required for send.' }, { status: 400 })
+      const envelope = sendMailboxEnvelope({
+        toSessionId,
+        type,
+        payload,
+        fromSessionId: id,
+        fromAgentId: current.agentId || null,
+        correlationId: typeof body?.correlationId === 'string' ? body.correlationId : null,
+        ttlSec: typeof body?.ttlSec === 'number' ? body.ttlSec : null,
+      })
+      return NextResponse.json({ ok: true, envelope })
+    }
+
+    if (action === 'ack') {
+      const envelopeId = typeof body?.envelopeId === 'string' ? body.envelopeId : ''
+      if (!envelopeId) return NextResponse.json({ error: 'envelopeId is required for ack.' }, { status: 400 })
+      const envelope = ackMailboxEnvelope(id, envelopeId)
+      if (!envelope) return NextResponse.json({ error: `Envelope not found: ${envelopeId}` }, { status: 404 })
+      return NextResponse.json({ ok: true, envelope })
+    }
+
+    if (action === 'clear') {
+      const includeAcked = body?.includeAcked !== false
+      const result = clearMailbox(id, includeAcked)
+      return NextResponse.json({ ok: true, ...result })
+    }
+
+    return NextResponse.json({ error: `Unsupported action: ${action}` }, { status: 400 })
+  } catch (err: any) {
+    return NextResponse.json({ error: err?.message || 'Mailbox operation failed.' }, { status: 500 })
+  }
+}
+

package/src/app/api/sessions/[id]/main-loop/route.ts

@@ -0,0 +1,94 @@
+import { NextResponse } from 'next/server'
+import { enqueueSessionRun } from '@/lib/server/session-run-manager'
+import { loadSessions } from '@/lib/server/storage'
+import {
+  buildMainLoopHeartbeatPrompt,
+  getMainLoopStateForSession,
+  isMainSession,
+  pushMainLoopEventToMainSessions,
+  setMainLoopStateForSession,
+} from '@/lib/server/main-agent-loop'
+
+export async function GET(_req: Request, { params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params
+  const sessions = loadSessions()
+  const session = sessions[id]
+  if (!session) return new NextResponse('Session not found', { status: 404 })
+  if (!isMainSession(session)) return new NextResponse('Main-loop controls only apply to __main__ sessions', { status: 400 })
+  const state = getMainLoopStateForSession(id)
+  return NextResponse.json({ sessionId: id, state })
+}
+
+export async function POST(req: Request, { params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params
+  const body = await req.json().catch(() => ({}))
+  const action = typeof body.action === 'string' ? body.action.trim() : ''
+
+  const sessions = loadSessions()
+  const session = sessions[id]
+  if (!session) return new NextResponse('Session not found', { status: 404 })
+  if (!isMainSession(session)) return new NextResponse('Main-loop controls only apply to __main__ sessions', { status: 400 })
+
+  if (action === 'pause') {
+    const state = setMainLoopStateForSession(id, { paused: true })
+    return NextResponse.json({ ok: true, action, state })
+  }
+
+  if (action === 'resume') {
+    const state = setMainLoopStateForSession(id, { paused: false })
+    return NextResponse.json({ ok: true, action, state })
+  }
+
+  if (action === 'set_goal') {
+    const goal = typeof body.goal === 'string' ? body.goal.trim() : ''
+    if (!goal) return new NextResponse('goal is required for set_goal', { status: 400 })
+    const state = setMainLoopStateForSession(id, {
+      goal,
+      status: 'progress',
+      paused: false,
+      followupChainCount: 0,
+    })
+    pushMainLoopEventToMainSessions({
+      type: 'operator_goal',
+      text: `Operator set mission goal: ${goal}`,
+      user: session.user || null,
+    })
+    return NextResponse.json({ ok: true, action, state })
+  }
+
+  if (action === 'set_mode') {
+    const mode = body.mode === 'assist' ? 'assist' : body.mode === 'autonomous' ? 'autonomous' : null
+    if (!mode) return new NextResponse('mode must be "assist" or "autonomous"', { status: 400 })
+    const state = setMainLoopStateForSession(id, { autonomyMode: mode })
+    return NextResponse.json({ ok: true, action, state })
+  }
+
+  if (action === 'clear_events') {
+    const state = setMainLoopStateForSession(id, { pendingEvents: [] })
+    return NextResponse.json({ ok: true, action, state })
+  }
+
+  if (action === 'nudge') {
+    const state = getMainLoopStateForSession(id)
+    if (state?.paused) {
+      return new NextResponse('Mission loop is paused; resume first', { status: 409 })
+    }
+    const note = typeof body.note === 'string' ? body.note.trim() : ''
+    const prompt = buildMainLoopHeartbeatPrompt(
+      session,
+      'Operator requested manual nudge: execute one concrete next step now and report concise progress.',
+    )
+    const message = note ? `${prompt}\nOperator note: ${note.slice(0, 500)}` : prompt
+    const run = enqueueSessionRun({
+      sessionId: id,
+      message,
+      internal: true,
+      source: 'mission-control',
+      mode: 'collect',
+      dedupeKey: `mission-control:nudge:${id}`,
+    })
+    return NextResponse.json({ ok: true, action, runId: run.runId, position: run.position, deduped: run.deduped || false, state })
+  }
+
+  return new NextResponse('Unknown action. Use pause, resume, set_goal, set_mode, clear_events, or nudge.', { status: 400 })
+}