feat: add gateway fleet topology

Author: waydelyle

README.md

@@ -399,6 +399,14 @@ Operational docs: https://swarmclaw.ai/docs/observability
 
 ## Releases
 
+### v1.8.12 Highlights
+
+Gateway Fleet Command release: SwarmClaw now treats OpenClaw gateways as an operator surface instead of a background provider detail.
+
+- **Fleet topology API.** Added gateway topology endpoints that collect OpenClaw nodes, node pairings, device pairings, sessions, presence, and best-effort RPC errors in one server-side snapshot.
+- **Provider console controls.** The Providers screen can refresh a whole gateway fleet or a single gateway topology, showing sessions, presence, pending pairings, and topology warnings alongside deploy and runtime health.
+- **Operations Pulse coverage.** Degraded gateways, stale topology, failed topology refreshes, and pending OpenClaw pairings now appear in the shared operator triage queue.
+
 ### v1.8.11 Highlights
 
 DeepSeek tool-use hotfix for issue [#67](https://github.com/swarmclawai/swarmclaw/issues/67).

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmclawai/swarmclaw",
-  "version": "1.8.11",
+  "version": "1.8.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",
@@ -86,7 +86,7 @@
     "cli": "node ./bin/swarmclaw.js",
     "test:cli": "node --test src/cli/*.test.js bin/*.test.js scripts/electron-after-pack.test.mjs scripts/postinstall.test.mjs scripts/run-next-build.test.mjs scripts/run-next-typegen.test.mjs",
     "test:setup": "tsx --test src/app/api/setup/check-provider/route.test.ts src/lib/server/provider-model-discovery.test.ts src/components/auth/setup-wizard/utils.test.ts src/components/auth/setup-wizard/types.test.ts src/hooks/setup-done-detection.test.ts src/lib/setup-defaults.test.ts src/lib/server/storage-auth.test.ts src/lib/server/storage-auth-docker.test.ts",
-    "test:openclaw": "tsx --test src/lib/openclaw/openclaw-agent-id.test.ts src/lib/openclaw/openclaw-endpoint.test.ts src/lib/server/agents/agent-runtime-config.test.ts src/lib/server/build-llm.test.ts src/lib/server/connectors/connector-routing.test.ts src/lib/server/connectors/openclaw.test.ts src/lib/server/connectors/swarmdock.test.ts src/lib/server/gateway/protocol.test.ts src/lib/server/llm-response-cache.test.ts src/lib/server/mcp-conformance.test.ts src/lib/server/openclaw/agent-resolver.test.ts src/lib/server/openclaw/deploy.test.ts src/lib/server/openclaw/skills-normalize.test.ts src/lib/server/session-tools/openclaw-nodes.test.ts src/lib/server/session-tools/swarmdock.test.ts src/lib/server/tasks/task-quality-gate.test.ts src/lib/server/tasks/task-validation.test.ts src/lib/server/tool-capability-policy.test.ts src/lib/providers/openai.test.ts src/lib/providers/openclaw-exports.test.ts src/app/api/openclaw/dashboard-url/route.test.ts",
+    "test:openclaw": "tsx --test src/lib/openclaw/openclaw-agent-id.test.ts src/lib/openclaw/openclaw-endpoint.test.ts src/lib/server/agents/agent-runtime-config.test.ts src/lib/server/build-llm.test.ts src/lib/server/connectors/connector-routing.test.ts src/lib/server/connectors/openclaw.test.ts src/lib/server/connectors/swarmdock.test.ts src/lib/server/gateway/protocol.test.ts src/lib/server/gateways/gateway-topology.test.ts src/lib/server/llm-response-cache.test.ts src/lib/server/mcp-conformance.test.ts src/lib/server/openclaw/agent-resolver.test.ts src/lib/server/openclaw/deploy.test.ts src/lib/server/openclaw/skills-normalize.test.ts src/lib/server/session-tools/openclaw-nodes.test.ts src/lib/server/session-tools/swarmdock.test.ts src/lib/server/tasks/task-quality-gate.test.ts src/lib/server/tasks/task-validation.test.ts src/lib/server/tool-capability-policy.test.ts src/lib/providers/openai.test.ts src/lib/providers/openclaw-exports.test.ts src/app/api/gateways/topology-route.test.ts src/app/api/openclaw/dashboard-url/route.test.ts",
     "test:runtime": "tsx --test src/lib/a2a/agent-card.test.ts src/lib/strip-internal-metadata.test.ts src/lib/provider-sets.test.ts src/lib/providers/opencode-cli.test.ts src/lib/providers/cli-provider-metadata.test.ts src/lib/providers/cli-utils.test.ts src/lib/providers/generic-cli.test.ts src/lib/server/cli-provider-readiness.test.ts src/lib/server/provider-health.test.ts src/lib/server/mcp-gateway-runtime.test.ts src/lib/server/mcp-connection-pool.test.ts src/lib/server/knowledge-sources.test.ts src/lib/server/chat-execution/chat-execution-grounding.test.ts src/lib/server/chat-execution/chat-turn-preparation.test.ts src/lib/server/chat-execution/iteration-timers.test.ts src/lib/server/chat-execution/post-stream-finalization.test.ts src/lib/server/chats/clear-undo-snapshots.test.ts src/lib/server/connectors/email.test.ts src/lib/server/protocols/protocol-service.test.ts src/lib/server/runtime/run-ledger.test.ts src/lib/server/runs/run-brief.test.ts src/lib/server/operations/operation-pulse.test.ts src/lib/server/artifacts/artifact-resolver.test.ts src/lib/server/observability/otel-config.test.ts src/lib/server/safe-parse-body.test.ts src/lib/server/missions/mission-templates.test.ts src/lib/server/sharing/share-link-repository.test.ts src/lib/server/sharing/share-resolver.test.ts src/lib/app/view-constants.test.ts src/lib/quality/quality-summary.test.ts src/app/api/approvals/route.test.ts src/app/api/agents/agents-route.test.ts src/app/api/tasks/tasks-route.test.ts src/app/api/chats/chat-route.test.ts src/app/api/chats/clear-route.test.ts src/app/api/chats/compact-route.test.ts src/app/api/chats/context-status-route.test.ts src/app/api/connectors/connector-doctor-route.test.ts src/app/api/healthz/route.test.ts src/app/api/logs/route.test.ts src/app/api/providers/[id]/route.test.ts src/app/api/tts/route.test.ts",
     "test:builder": "tsx --test src/features/protocols/builder/utils/nodes-to-template.test.ts src/features/protocols/builder/utils/template-to-nodes.test.ts src/features/protocols/builder/validators/dag-validator.test.ts",
     "test:e2e": "node --import tsx scripts/browser-e2e-smoke.ts",

package.json

@@ -0,0 +1,13 @@
+import { NextResponse } from 'next/server'
+
+import { notFound } from '@/lib/server/collection-helpers'
+import { getOpenClawGatewayTopology } from '@/lib/server/gateways/gateway-topology'
+
+export const dynamic = 'force-dynamic'
+
+export async function GET(_req: Request, { params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params
+  const topology = await getOpenClawGatewayTopology(id)
+  if (!topology) return notFound()
+  return NextResponse.json(topology)
+}

src/app/api/gateways/[id]/topology/route.ts

@@ -0,0 +1,9 @@
+import { NextResponse } from 'next/server'
+
+import { getOpenClawGatewayFleetTopology } from '@/lib/server/gateways/gateway-topology'
+
+export const dynamic = 'force-dynamic'
+
+export async function GET() {
+  return NextResponse.json(await getOpenClawGatewayFleetTopology())
+}

src/app/api/gateways/fleet/route.ts

@@ -0,0 +1,37 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+
+import { runWithTempDataDir } from '@/lib/server/test-utils/run-with-temp-data-dir'
+
+test('gateway topology route returns 404 for unknown profiles', () => {
+  const output = runWithTempDataDir<{ status: number; body: { error: string } }>(`
+    const routeMod = await import('./src/app/api/gateways/[id]/topology/route')
+    const route = routeMod.default || routeMod
+    const response = await route.GET(
+      new Request('http://local/api/gateways/missing/topology'),
+      { params: Promise.resolve({ id: 'missing' }) },
+    )
+    console.log(JSON.stringify({ status: response.status, body: await response.json() }))
+  `, { prefix: 'swarmclaw-gateway-topology-route-test-' })
+
+  assert.equal(output.status, 404)
+  assert.equal(output.body.error, 'Not found')
+})
+
+test('gateway fleet route reports empty totals when no OpenClaw profiles exist', () => {
+  const output = runWithTempDataDir<{
+    status: number
+    body: { gateways: unknown[]; totals: { gatewayCount: number; nodeCount: number; hasErrors: boolean } }
+  }>(`
+    const routeMod = await import('./src/app/api/gateways/fleet/route')
+    const route = routeMod.default || routeMod
+    const response = await route.GET(new Request('http://local/api/gateways/fleet'))
+    console.log(JSON.stringify({ status: response.status, body: await response.json() }))
+  `, { prefix: 'swarmclaw-gateway-fleet-route-test-' })
+
+  assert.equal(output.status, 200)
+  assert.equal(output.body.gateways.length, 0)
+  assert.equal(output.body.totals.gatewayCount, 0)
+  assert.equal(output.body.totals.nodeCount, 0)
+  assert.equal(output.body.totals.hasErrors, false)
+})

src/app/api/gateways/topology-route.test.ts

@@ -272,6 +272,8 @@ const COMMAND_GROUPS = [
       cmd('update', 'PUT', '/gateways/:id', 'Update a gateway profile', { expectsJsonBody: true }),
       cmd('delete', 'DELETE', '/gateways/:id', 'Delete a gateway profile'),
       cmd('health', 'GET', '/gateways/:id/health', 'Run a gateway health check'),
+      cmd('topology', 'GET', '/gateways/:id/topology', 'Refresh and return one gateway topology snapshot'),
+      cmd('fleet', 'GET', '/gateways/fleet', 'Refresh and return fleet-wide gateway topology'),
     ],
   },
   {

src/cli/index.js

@@ -220,6 +220,8 @@ const COMMAND_GROUPS = {
       update: { description: 'Update a gateway profile', method: 'PUT', path: '/gateways/:id', params: ['id'] },
       delete: { description: 'Delete a gateway profile', method: 'DELETE', path: '/gateways/:id', params: ['id'] },
       health: { description: 'Run a gateway health check', method: 'GET', path: '/gateways/:id/health', params: ['id'] },
+      topology: { description: 'Refresh and return one gateway topology snapshot', method: 'GET', path: '/gateways/:id/topology', params: ['id'] },
+      fleet: { description: 'Refresh and return fleet-wide gateway topology', method: 'GET', path: '/gateways/fleet' },
     },
   },
   logs: {

src/cli/spec.js

@@ -7,6 +7,9 @@ import { useAppStore } from '@/stores/use-app-store'
 import { toast } from 'sonner'
 import type {
   OpenClawDevicePairRequest,
+  OpenClawGatewayPresenceEntry,
+  OpenClawGatewayRpcError,
+  OpenClawGatewaySession,
   OpenClawNode,
   OpenClawNodePairRequest,
   OpenClawPairedDevice,
@@ -76,6 +79,9 @@ export function GatewaySheet() {
   const [nodePairings, setNodePairings] = useState<OpenClawNodePairRequest[]>([])
   const [devicePairings, setDevicePairings] = useState<OpenClawDevicePairRequest[]>([])
   const [pairedDevices, setPairedDevices] = useState<OpenClawPairedDevice[]>([])
+  const [gatewaySessions, setGatewaySessions] = useState<OpenClawGatewaySession[]>([])
+  const [gatewayPresence, setGatewayPresence] = useState<OpenClawGatewayPresenceEntry[]>([])
+  const [gatewayTopologyErrors, setGatewayTopologyErrors] = useState<OpenClawGatewayRpcError[]>([])
   const [invokeNodeId, setInvokeNodeId] = useState('')
   const [invokeCommand, setInvokeCommand] = useState('')
   const [invokeParamsText, setInvokeParamsText] = useState('{}')
@@ -113,6 +119,9 @@ export function GatewaySheet() {
     setNodePairings([])
     setDevicePairings([])
     setPairedDevices([])
+    setGatewaySessions([])
+    setGatewayPresence([])
+    setGatewayTopologyErrors([])
     setInvokeNodeId('')
     setInvokeCommand('')
     setInvokeParamsText('{}')
@@ -130,6 +139,9 @@ export function GatewaySheet() {
       setNodePairings(result.nodePairings)
       setDevicePairings(result.devicePairings)
       setPairedDevices(result.pairedDevices)
+      setGatewaySessions(result.sessions)
+      setGatewayPresence(result.presence)
+      setGatewayTopologyErrors(result.errors)
       if (result.nodes[0]) {
         setInvokeNodeId((current) => current || result.nodes[0].nodeId)
         setInvokeCommand((current) => current || result.nodes[0].commands?.[0] || '')
@@ -532,6 +544,37 @@ export function GatewaySheet() {
             </div>
           )}
 
+          <div className="mb-4 grid grid-cols-2 gap-2 md:grid-cols-4">
+            <div className="rounded-[12px] border border-white/[0.06] bg-white/[0.025] px-3 py-2">
+              <div className="text-[10px] font-700 uppercase tracking-[0.1em] text-text-3/55">Nodes</div>
+              <div className="mt-1 font-display text-[18px] font-700 text-text">{nodes.filter((node) => node.connected).length}/{nodes.length}</div>
+            </div>
+            <div className="rounded-[12px] border border-white/[0.06] bg-white/[0.025] px-3 py-2">
+              <div className="text-[10px] font-700 uppercase tracking-[0.1em] text-text-3/55">Pairings</div>
+              <div className="mt-1 font-display text-[18px] font-700 text-amber-300">{nodePairings.length + devicePairings.length}</div>
+            </div>
+            <div className="rounded-[12px] border border-white/[0.06] bg-white/[0.025] px-3 py-2">
+              <div className="text-[10px] font-700 uppercase tracking-[0.1em] text-text-3/55">Sessions</div>
+              <div className="mt-1 font-display text-[18px] font-700 text-text">{gatewaySessions.length}</div>
+            </div>
+            <div className={`rounded-[12px] border px-3 py-2 ${
+              gatewayTopologyErrors.length > 0
+                ? 'border-rose-400/20 bg-rose-400/[0.06]'
+                : 'border-white/[0.06] bg-white/[0.025]'
+            }`}>
+              <div className="text-[10px] font-700 uppercase tracking-[0.1em] text-text-3/55">Presence</div>
+              <div className={gatewayTopologyErrors.length > 0 ? 'mt-1 font-display text-[18px] font-700 text-rose-200' : 'mt-1 font-display text-[18px] font-700 text-text'}>
+                {gatewayPresence.length}
+              </div>
+            </div>
+          </div>
+
+          {gatewayTopologyErrors.length > 0 && (
+            <div className="mb-4 rounded-[12px] border border-rose-400/20 bg-rose-400/[0.06] px-3 py-2 text-[12px] text-rose-200">
+              {gatewayTopologyErrors[0]?.method}: {gatewayTopologyErrors[0]?.message}
+            </div>
+          )}
+
           <div className="grid grid-cols-1 xl:grid-cols-2 gap-4">
             <div className="space-y-4">
               <div className="rounded-[14px] border border-white/[0.06] bg-surface p-4">

src/components/gateways/gateway-sheet.tsx

@@ -2,7 +2,7 @@
 
 import { useCallback, useEffect, useMemo, useState } from 'react'
 import { useRouter } from 'next/navigation'
-import { AlertTriangle, CheckCircle2, Clock, PlugZap, RefreshCw } from 'lucide-react'
+import { AlertTriangle, CheckCircle2, Clock, PlugZap, RadioTower, RefreshCw } from 'lucide-react'
 import { api } from '@/lib/app/api-client'
 import { cn } from '@/lib/utils'
 import type { OperationPulse, OperationPulseAction, OperationPulseRange, OperationPulseSeverity } from '@/types'
@@ -39,6 +39,7 @@ function Kpi({ label, value, danger = false }: { label: string; value: number; d
 function actionIcon(action: OperationPulseAction) {
   if (action.severity === 'high') return <AlertTriangle size={15} />
   if (action.kind === 'connector') return <PlugZap size={15} />
+  if (action.kind === 'gateway') return <RadioTower size={15} />
   if (action.kind === 'mission') return <Clock size={15} />
   return <CheckCircle2 size={15} />
 }
@@ -82,6 +83,7 @@ export function OperationsPulsePanel({
     return pulse.kpis.failedRuns === 0
       && pulse.kpis.pendingApprovals === 0
       && pulse.kpis.connectorAttention === 0
+      && pulse.kpis.gatewayAttention === 0
       && pulse.kpis.budgetWarnings === 0
   }, [pulse])
 
@@ -92,7 +94,7 @@ export function OperationsPulsePanel({
           <div className="text-[10px] font-700 uppercase tracking-[0.16em] text-accent-bright/70">Operations Pulse</div>
           <h2 className="mt-1 font-display text-[16px] font-700 tracking-normal text-text">What needs operator attention next</h2>
           <p className="mt-1 max-w-[680px] text-[12px] leading-relaxed text-text-3/68">
-            Missions, runs, approvals, connector readiness, and budget pressure rolled into one triage queue.
+            Missions, runs, approvals, connector readiness, OpenClaw gateways, and budget pressure rolled into one triage queue.
           </p>
         </div>
         <div className="flex flex-wrap items-center gap-2">
@@ -130,12 +132,13 @@ export function OperationsPulsePanel({
         </div>
       ) : (
         <>
-          <div className={cn('mt-4 grid gap-2', compact ? 'grid-cols-2 md:grid-cols-3 xl:grid-cols-6' : 'grid-cols-2 sm:grid-cols-3 xl:grid-cols-6')}>
+          <div className={cn('mt-4 grid gap-2', compact ? 'grid-cols-2 md:grid-cols-4 xl:grid-cols-7' : 'grid-cols-2 sm:grid-cols-3 xl:grid-cols-7')}>
             <Kpi label="Missions" value={pulse.kpis.activeMissions} />
             <Kpi label="Running" value={pulse.kpis.runningRuns} />
             <Kpi label="Failed" value={pulse.kpis.failedRuns} danger />
             <Kpi label="Approvals" value={pulse.kpis.pendingApprovals} />
             <Kpi label="Connectors" value={pulse.kpis.connectorAttention} danger />
+            <Kpi label="Gateways" value={pulse.kpis.gatewayAttention} danger />
             <Kpi label="Budgets" value={pulse.kpis.budgetWarnings} />
           </div>