feat: harden daemon startup, capability policy, and gateway protocol

Author: waydelyle

README.md

@@ -56,9 +56,12 @@ SwarmClaw can spawn **Claude Code CLI** processes with full shell access on your
 ## Quick Start
 
 ```bash
-curl -fsSL https://swarmclaw.ai/install.sh | bash
+curl -fsSL https://raw.githubusercontent.com/swarmclawai/swarmclaw/main/install.sh | bash
 ```
 
+The installer resolves the latest stable release tag and installs that version by default.
+To pin a version: `SWARMCLAW_VERSION=v0.1.0 curl ... | bash`
+
 Or run locally from the repo (friendly for non-technical users):
 
 ```bash
@@ -290,7 +293,7 @@ Token usage and estimated costs are tracked per message for API-based providers
 The daemon auto-processes queued tasks from the scheduler on a 30-second interval. It also runs recurring health checks that detect stale heartbeat sessions and can send proactive WhatsApp alerts when issues are detected. Toggle the daemon from the sidebar indicator or via API.
 
 - **API:** `GET /api/daemon` (status), `POST /api/daemon` with `{"action": "start"}` or `{"action": "stop"}`
-- Auto-starts on boot if queued tasks are found
+- Auto-starts on first authenticated runtime traffic (`/api/auth` or `/api/daemon`) unless `SWARMCLAW_DAEMON_AUTOSTART=0`
 
 ## Main Agent Loop
 
@@ -316,6 +319,17 @@ Configure loop behavior in **Settings → Runtime & Loop Controls**:
 
 You can also tune shell timeout, Claude Code delegation timeout, and CLI provider process timeout from the same settings panel.
 
+## Capability Policy
+
+Configure this in **Settings → Capability Policy** to centrally govern tool access:
+
+- **Mode:** `permissive`, `balanced`, or `strict`
+- **Blocked categories:** e.g. `execution`, `filesystem`, `platform`, `outbound`
+- **Blocked tools:** specific tool families or concrete tool names
+- **Allowed tools:** explicit overrides when running stricter modes
+
+Policy is enforced in both session tool construction and direct forced tool invocations, so auto-routing and explicit tool requests use the same guardrails.
+
 ## CLI Troubleshooting
 
 - **Claude delegate returns no output or fails quickly:** verify Claude auth on the host with:
@@ -419,6 +433,18 @@ docker compose up -d
 
 Data is persisted in `data/` and `.env.local` via volume mounts. Updates: `git pull && docker compose up -d --build`.
 
+For prebuilt images (recommended for non-technical users after releases):
+
+```bash
+docker pull ghcr.io/swarmclawai/swarmclaw:latest
+docker run -d \
+  --name swarmclaw \
+  -p 3456:3456 \
+  -v "$(pwd)/data:/app/data" \
+  -v "$(pwd)/.env.local:/app/.env.local" \
+  ghcr.io/swarmclawai/swarmclaw:latest
+```
+
 ### Updating
 
 SwarmClaw has a built-in update checker — a banner appears in the sidebar when new commits are available, with a one-click update button. Your data in `data/` and `.env.local` is never touched by updates.
@@ -429,7 +455,7 @@ For terminal users, run:
 npm run update:easy
 ```
 
-This command fetches/pulls `origin/main`, installs dependencies when needed, and runs a production build check before restart.
+This command updates to the latest stable release tag when available (fallback: `origin/main`), installs dependencies when needed, and runs a production build check before restart.
 
 ## Development
 
@@ -472,6 +498,21 @@ npm run quickstart:prod # setup + build + start production server
 npm run update:easy     # safe update helper for local installs
 ```
 
+### Release Process (Maintainers)
+
+SwarmClaw uses tag-based releases (`vX.Y.Z`) as the stable channel.
+
+```bash
+# example patch release
+npm version patch
+git push origin main --follow-tags
+```
+
+On `v*` tags, GitHub Actions will:
+1. Run CI checks
+2. Create a GitHub Release
+3. Build and publish Docker images to `ghcr.io/swarmclawai/swarmclaw` (`:vX.Y.Z`, `:latest`, `:sha-*`)
+
 ## CLI
 
 SwarmClaw ships a built-in CLI for core operational workflows:

package-lock.json

@@ -22,7 +22,7 @@
     "lint:baseline:update": "node ./scripts/lint-baseline.mjs update",
     "cli": "node ./bin/swarmclaw.js",
     "test:cli": "node --test src/cli/index.test.js",
-    "test:openclaw": "tsx --test src/lib/server/connectors/openclaw.test.ts src/lib/openclaw-endpoint.test.ts"
+    "test:openclaw": "tsx --test src/lib/server/connectors/openclaw.test.ts src/lib/openclaw-endpoint.test.ts src/lib/server/gateway/protocol.test.ts src/lib/server/tool-capability-policy.test.ts"
   },
   "dependencies": {
     "@huggingface/transformers": "^3.8.1",

package.json

@@ -1,5 +1,6 @@
 import { NextResponse } from 'next/server'
 import { validateAccessKey, getAccessKey, isFirstTimeSetup, markSetupComplete } from '@/lib/server/storage'
+import { ensureDaemonStarted } from '@/lib/server/daemon-state'
 
 /** GET /api/auth — check if this is a first-time setup (returns key for initial display) */
 export async function GET() {
@@ -19,5 +20,6 @@ export async function POST(req: Request) {
   if (isFirstTimeSetup()) {
     markSetupComplete()
   }
+  ensureDaemonStarted('api/auth:post')
   return NextResponse.json({ ok: true })
 }

src/app/api/auth/route.ts

@@ -1,7 +1,8 @@
 import { NextResponse } from 'next/server'
-import { getDaemonStatus, runDaemonHealthCheckNow } from '@/lib/server/daemon-state'
+import { ensureDaemonStarted, getDaemonStatus, runDaemonHealthCheckNow } from '@/lib/server/daemon-state'
 
 export async function POST() {
+  ensureDaemonStarted('api/daemon/health-check:post')
   await runDaemonHealthCheckNow()
   return NextResponse.json({
     ok: true,

src/app/api/daemon/health-check/route.ts

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

src/app/api/daemon/route.ts

@@ -422,6 +422,93 @@ export function SettingsSheet() {
         </div>
       </div>
 
+      {/* Capability Policy */}
+      <div className="mb-10">
+        <h3 className="font-display text-[12px] font-600 text-text-2 uppercase tracking-[0.08em] mb-2">
+          Capability Policy
+        </h3>
+        <p className="text-[12px] text-text-3 mb-5">
+          Centralized guardrails for agent tool families. Applies to direct tool calls and forced auto-routing.
+        </p>
+        <div className="p-6 rounded-[18px] bg-surface border border-white/[0.06]">
+          <label className="block font-display text-[11px] font-600 text-text-3 uppercase tracking-[0.08em] mb-3">Policy Mode</label>
+          <div className="grid grid-cols-3 gap-2 mb-5">
+            {([
+              { id: 'permissive', name: 'Permissive' },
+              { id: 'balanced', name: 'Balanced' },
+              { id: 'strict', name: 'Strict' },
+            ] as const).map((mode) => (
+              <button
+                key={mode.id}
+                onClick={() => updateSettings({ capabilityPolicyMode: mode.id })}
+                className={`py-3 px-3 rounded-[12px] text-center cursor-pointer transition-all text-[13px] font-600 border
+                  ${(appSettings.capabilityPolicyMode || 'permissive') === mode.id
+                    ? 'bg-accent-soft border-accent-bright/25 text-accent-bright'
+                    : 'bg-bg border-white/[0.06] text-text-2 hover:bg-surface-2'}`}
+                style={{ fontFamily: 'inherit' }}
+              >
+                {mode.name}
+              </button>
+            ))}
+          </div>
+
+          <div className="grid grid-cols-1 gap-4">
+            <div>
+              <label className="block font-display text-[11px] font-600 text-text-3 uppercase tracking-[0.08em] mb-2">Blocked Categories</label>
+              <input
+                type="text"
+                value={(appSettings.capabilityBlockedCategories || []).join(', ')}
+                onChange={(e) => updateSettings({
+                  capabilityBlockedCategories: e.target.value
+                    .split(',')
+                    .map((part) => part.trim())
+                    .filter(Boolean),
+                })}
+                placeholder="execution, filesystem, platform, outbound"
+                className={inputClass}
+                style={{ fontFamily: 'inherit' }}
+              />
+              <p className="text-[11px] text-text-3/60 mt-2">Supported categories: filesystem, execution, network, browser, memory, delegation, platform, outbound.</p>
+            </div>
+
+            <div>
+              <label className="block font-display text-[11px] font-600 text-text-3 uppercase tracking-[0.08em] mb-2">Blocked Tools</label>
+              <input
+                type="text"
+                value={(appSettings.capabilityBlockedTools || []).join(', ')}
+                onChange={(e) => updateSettings({
+                  capabilityBlockedTools: e.target.value
+                    .split(',')
+                    .map((part) => part.trim())
+                    .filter(Boolean),
+                })}
+                placeholder="delete_file, manage_connectors, delegate_to_codex_cli"
+                className={inputClass}
+                style={{ fontFamily: 'inherit' }}
+              />
+            </div>
+
+            <div>
+              <label className="block font-display text-[11px] font-600 text-text-3 uppercase tracking-[0.08em] mb-2">Allowed Tools (Override)</label>
+              <input
+                type="text"
+                value={(appSettings.capabilityAllowedTools || []).join(', ')}
+                onChange={(e) => updateSettings({
+                  capabilityAllowedTools: e.target.value
+                    .split(',')
+                    .map((part) => part.trim())
+                    .filter(Boolean),
+                })}
+                placeholder="shell, web_fetch, browser"
+                className={inputClass}
+                style={{ fontFamily: 'inherit' }}
+              />
+              <p className="text-[11px] text-text-3/60 mt-2">Use this to re-allow specific tool families when running in strict mode.</p>
+            </div>
+          </div>
+        </div>
+      </div>
+
       {/* Voice */}
       <div className="mb-10">
         <h3 className="font-display text-[12px] font-600 text-text-2 uppercase tracking-[0.08em] mb-2">

src/components/shared/settings-sheet.tsx

@@ -20,6 +20,7 @@ import { stripMainLoopMetaForPersistence } from './main-agent-loop'
 import { normalizeProviderEndpoint } from '@/lib/openclaw-endpoint'
 import { getMemoryDb } from './memory-db'
 import { routeTaskIntent } from './capability-router'
+import { resolveConcreteToolPolicyBlock, resolveSessionToolPolicy } from './tool-capability-policy'
 import type { MessageToolEvent, SSEEvent } from '@/types'
 import { markProviderFailure, markProviderSuccess, rankDelegatesByHealth } from './provider-health'
 
@@ -216,36 +217,6 @@ function hasToolEnabled(session: any, toolName: string): boolean {
   return Array.isArray(session?.tools) && session.tools.includes(toolName)
 }
 
-function buildSafetyBlockedSet(settings: Record<string, unknown>): Set<string> {
-  const raw = Array.isArray(settings?.safetyBlockedTools) ? settings.safetyBlockedTools : []
-  const set = new Set<string>()
-  for (const entry of raw) {
-    const name = typeof entry === 'string' ? entry.trim().toLowerCase() : ''
-    if (!name) continue
-    set.add(name)
-  }
-  return set
-}
-
-function filterSessionToolsBySafety(sessionTools: string[] | undefined, blocked: Set<string>): string[] {
-  const source = Array.isArray(sessionTools) ? sessionTools : []
-  if (!blocked.size) return [...source]
-  return source.filter((toolName) => {
-    const key = String(toolName || '').trim().toLowerCase()
-    if (!key) return false
-    if (blocked.has(key)) return false
-    if (key === 'memory' && blocked.has('memory_tool')) return false
-    if (key === 'manage_connectors' && blocked.has('connector_message_tool')) return false
-    if (key === 'manage_sessions' && (blocked.has('sessions_tool') || blocked.has('search_history_tool'))) return false
-    if (key === 'claude_code' && (
-      blocked.has('delegate_to_claude_code')
-      || blocked.has('delegate_to_codex_cli')
-      || blocked.has('delegate_to_opencode_cli')
-    )) return false
-    return true
-  })
-}
-
 function parseUsdLimit(value: unknown): number | null {
   const parsed = typeof value === 'number'
     ? value
@@ -434,17 +405,17 @@ export async function executeSessionChatTurn(input: ExecuteChatTurnInput): Promi
   if (!session) throw new Error(`Session not found: ${sessionId}`)
 
   const appSettings = loadSettings()
-  const safetyBlocked = buildSafetyBlockedSet(appSettings)
-  const toolsForRun = filterSessionToolsBySafety(session.tools, safetyBlocked)
+  const toolPolicy = resolveSessionToolPolicy(session.tools, appSettings)
+  const toolsForRun = toolPolicy.enabledTools
   const sessionForRun = toolsForRun === session.tools
     ? session
     : { ...session, tools: toolsForRun }
 
-  if (toolsForRun.length !== (session.tools || []).length) {
-    const removed = (session.tools || []).filter((tool: string) => !toolsForRun.includes(tool))
-    if (removed.length) {
-      onEvent?.({ t: 'err', text: `Safety policy blocked tool categories for this run: ${removed.join(', ')}` })
-    }
+  if (toolPolicy.blockedTools.length > 0) {
+    const blockedSummary = toolPolicy.blockedTools
+      .map((entry) => `${entry.tool} (${entry.reason})`)
+      .join(', ')
+    onEvent?.({ t: 'err', text: `Capability policy blocked tools for this run: ${blockedSummary}` })
   }
 
   const dailySpendLimitUsd = parseUsdLimit(appSettings.safetyMaxDailySpendUsd)
@@ -600,13 +571,14 @@ export async function executeSessionChatTurn(input: ExecuteChatTurnInput): Promi
     ? requestedToolNamesFromMessage(message)
     : []
   const routingDecision = (!internal && source === 'chat')
-    ? routeTaskIntent(message, session.tools || [], appSettings)
+    ? routeTaskIntent(message, toolsForRun, appSettings)
     : null
   const calledNames = new Set((toolEvents || []).map((t) => t.name))
 
   const invokeSessionTool = async (toolName: string, args: Record<string, unknown>, failurePrefix: string): Promise<boolean> => {
-    if (safetyBlocked.has(toolName.toLowerCase())) {
-      emit({ t: 'err', text: `Safety policy blocked tool invocation: ${toolName}` })
+    const blockedReason = resolveConcreteToolPolicyBlock(toolName, toolPolicy, appSettings)
+    if (blockedReason) {
+      emit({ t: 'err', text: `Capability policy blocked tool invocation "${toolName}": ${blockedReason}` })
       return false
     }
     if (