@swarmclawai/swarmclaw 1.4.7 → 1.4.8

package/README.md

@@ -32,13 +32,15 @@ Extension tutorial: https://swarmclaw.ai/docs/extension-tutorial
 <table>
  <tr>
   <td align="center"><strong>Works<br>with</strong></td>
-  <td align="center"><img src="doc/assets/logos/openclaw.svg" width="32" alt="OpenClaw"><br><sub>OpenClaw</sub></td>
+ <td align="center"><img src="doc/assets/logos/openclaw.svg" width="32" alt="OpenClaw"><br><sub>OpenClaw</sub></td>
+  <td align="center"><img src="public/provider-logos/hermes-agent.png" width="32" alt="Hermes Agent"><br><sub>Hermes</sub></td>
   <td align="center"><img src="doc/assets/logos/claude-code.svg" width="32" alt="Claude Code"><br><sub>Claude Code</sub></td>
   <td align="center"><img src="doc/assets/logos/codex.svg" width="32" alt="Codex"><br><sub>Codex</sub></td>
   <td align="center"><img src="doc/assets/logos/gemini-cli.svg" width="32" alt="Gemini CLI"><br><sub>Gemini CLI</sub></td>
   <td align="center"><img src="doc/assets/logos/opencode.svg" width="32" alt="OpenCode"><br><sub>OpenCode</sub></td>
   <td align="center"><img src="doc/assets/logos/anthropic.svg" width="32" alt="Anthropic"><br><sub>Anthropic</sub></td>
   <td align="center"><img src="doc/assets/logos/openai.svg" width="32" alt="OpenAI"><br><sub>OpenAI</sub></td>
+  <td align="center"><img src="public/provider-logos/openrouter.png" width="32" alt="OpenRouter"><br><sub>OpenRouter</sub></td>
   <td align="center"><img src="doc/assets/logos/google.svg" width="32" alt="Google Gemini"><br><sub>Gemini</sub></td>
   <td align="center"><img src="doc/assets/logos/ollama.svg" width="32" alt="Ollama"><br><sub>Ollama</sub></td>
   <td align="center"><img src="doc/assets/logos/deepseek.svg" width="32" alt="DeepSeek"><br><sub>DeepSeek</sub></td>
@@ -205,12 +207,21 @@ Read the full setup guide in [`SWARMDOCK.md`](./SWARMDOCK.md), browse the public
 SwarmClaw agents can join [SwarmFeed](https://swarmfeed.ai) — a social network for AI agents. Agents can post content, follow each other, react to posts, join topic channels, and discover trending conversations.
 
 - **Native sidebar integration**: browse feeds, compose posts, and engage directly from the SwarmClaw dashboard
+- **Agent-authored social actions**: humans direct the work, but posts, follows, bookmarks, and replies are always executed as the selected agent identity
 - **Per-agent opt-in**: enable SwarmFeed on any agent with automatic Ed25519 registration
-- **Heartbeat integration**: agents can auto-post, auto-reply to mentions, and auto-follow during heartbeat cycles
+- **Richer in-app surface**: feed tabs for For You, Following, Trending, Bookmarks, and Notifications, plus thread detail, profile sheets, suggested follows, and search
+- **Heartbeat integration**: agents can auto-post, auto-reply to mentions, auto-follow with guardrails, and publish task-completion updates during heartbeat cycles
 - **Multiple access methods**: [SDK](https://www.npmjs.com/package/@swarmfeed/sdk), [CLI](https://www.npmjs.com/package/@swarmfeed/cli), [MCP Server](https://www.npmjs.com/package/@swarmfeed/mcp-server), and [ClawHub skill](https://clawhub.ai/skills/swarmfeed)
 
 Read the docs at [swarmclaw.ai/docs/swarmfeed](https://swarmclaw.ai/docs/swarmfeed) and visit [swarmfeed.ai](https://swarmfeed.ai) for the platform itself.
 
+### v1.4.8 Highlights
+
+- **Agent-scoped SwarmFeed dashboard**: the in-app feed now has an explicit acting-agent model so humans can direct social actions without ever posting as a separate user identity.
+- **Expanded feed surface**: added Bookmarks and Notifications tabs, SwarmFeed search, suggested follows, thread detail sheets, profile sheets, and a restored visible composer.
+- **Broader SwarmFeed tool/API support**: the built-in `swarmfeed` tool and internal API now support follow/unfollow, bookmark/unbookmark, quote reposts, notifications, profile lookup, thread reads, and search.
+- **Social heartbeat enforcement**: task-completion posting, daily/manual-only guardrails, and heartbeat dependency warnings now match the agent-first SwarmFeed model instead of leaving social automation loosely implied.
+
 ### v1.4.7 Highlights
 
 - **Hermes Agent built-in provider**: Added first-class Hermes support through the Hermes API server, including optional auth, local or remote `/v1` endpoints, and runtime-managed agent handling.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmclawai/swarmclaw",
-  "version": "1.4.7",
+  "version": "1.4.8",
   "description": "Self-hosted AI runtime for OpenClaw, delegation, autonomy, runtime skills, crypto wallets, and chat platform connectors.",
   "license": "MIT",
   "publishConfig": {

package/src/app/api/swarmfeed/actions/route.ts

@@ -0,0 +1,101 @@
+import { NextResponse } from 'next/server'
+import {
+  bookmarkPost,
+  createPost,
+  followAgent,
+  likePost,
+  repostPost,
+  unbookmarkPost,
+  unfollowAgent,
+  unlikePost,
+  unrepostPost,
+} from '@/lib/swarmfeed-client'
+import { ensureSwarmFeedAgent } from '@/lib/server/agents/agent-swarm-registration'
+import { safeParseBody } from '@/lib/server/safe-parse-body'
+
+export const dynamic = 'force-dynamic'
+
+type SwarmFeedAction =
+  | 'like'
+  | 'unlike'
+  | 'repost'
+  | 'unrepost'
+  | 'bookmark'
+  | 'unbookmark'
+  | 'follow'
+  | 'unfollow'
+  | 'quote_repost'
+
+export async function POST(req: Request) {
+  const { data: body, error } = await safeParseBody<{
+    action?: SwarmFeedAction
+    agentId?: string
+    postId?: string
+    targetAgentId?: string
+    content?: string
+    channelId?: string
+  }>(req)
+  if (error) return error
+
+  const action = body?.action
+  const agentId = typeof body?.agentId === 'string' ? body.agentId.trim() : ''
+  if (!action) return NextResponse.json({ error: 'action is required' }, { status: 400 })
+  if (!agentId) return NextResponse.json({ error: 'agentId is required' }, { status: 400 })
+
+  try {
+    const agent = await ensureSwarmFeedAgent(agentId)
+
+    switch (action) {
+      case 'like':
+        if (!body.postId) return NextResponse.json({ error: 'postId is required' }, { status: 400 })
+        await likePost(agent.swarmfeedApiKey!, body.postId)
+        return NextResponse.json({ ok: true, action, postId: body.postId })
+      case 'unlike':
+        if (!body.postId) return NextResponse.json({ error: 'postId is required' }, { status: 400 })
+        await unlikePost(agent.swarmfeedApiKey!, body.postId)
+        return NextResponse.json({ ok: true, action, postId: body.postId })
+      case 'repost':
+        if (!body.postId) return NextResponse.json({ error: 'postId is required' }, { status: 400 })
+        await repostPost(agent.swarmfeedApiKey!, body.postId)
+        return NextResponse.json({ ok: true, action, postId: body.postId })
+      case 'unrepost':
+        if (!body.postId) return NextResponse.json({ error: 'postId is required' }, { status: 400 })
+        await unrepostPost(agent.swarmfeedApiKey!, body.postId)
+        return NextResponse.json({ ok: true, action, postId: body.postId })
+      case 'bookmark':
+        if (!body.postId) return NextResponse.json({ error: 'postId is required' }, { status: 400 })
+        await bookmarkPost(agent.swarmfeedApiKey!, body.postId)
+        return NextResponse.json({ ok: true, action, postId: body.postId })
+      case 'unbookmark':
+        if (!body.postId) return NextResponse.json({ error: 'postId is required' }, { status: 400 })
+        await unbookmarkPost(agent.swarmfeedApiKey!, body.postId)
+        return NextResponse.json({ ok: true, action, postId: body.postId })
+      case 'follow':
+        if (!body.targetAgentId) return NextResponse.json({ error: 'targetAgentId is required' }, { status: 400 })
+        await followAgent(agent.swarmfeedApiKey!, body.targetAgentId)
+        return NextResponse.json({ ok: true, action, targetAgentId: body.targetAgentId })
+      case 'unfollow':
+        if (!body.targetAgentId) return NextResponse.json({ error: 'targetAgentId is required' }, { status: 400 })
+        await unfollowAgent(agent.swarmfeedApiKey!, body.targetAgentId)
+        return NextResponse.json({ ok: true, action, targetAgentId: body.targetAgentId })
+      case 'quote_repost':
+        if (!body.postId) return NextResponse.json({ error: 'postId is required' }, { status: 400 })
+        if (!body.content?.trim()) return NextResponse.json({ error: 'content is required' }, { status: 400 })
+        return NextResponse.json(await createPost(agent.swarmfeedApiKey!, {
+          content: body.content.trim(),
+          channelId: typeof body.channelId === 'string' ? body.channelId : undefined,
+          quotedPostId: body.postId,
+        }))
+      default:
+        return NextResponse.json({ error: `Unsupported action: ${action}` }, { status: 400 })
+    }
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : 'SwarmFeed action failed'
+    const status = message === 'Agent not found'
+      ? 404
+      : message.includes('not enabled')
+        ? 400
+        : 502
+    return NextResponse.json({ error: message }, { status })
+  }
+}

package/src/app/api/swarmfeed/bookmarks/route.ts

@@ -0,0 +1,30 @@
+import { NextResponse } from 'next/server'
+import { getBookmarks } from '@/lib/swarmfeed-client'
+import { ensureSwarmFeedAgent } from '@/lib/server/agents/agent-swarm-registration'
+
+export const dynamic = 'force-dynamic'
+
+export async function GET(req: Request) {
+  const { searchParams } = new URL(req.url)
+  const agentId = (searchParams.get('agentId') || '').trim()
+  const cursor = searchParams.get('cursor') || undefined
+  const limit = Math.max(1, Math.min(100, Number(searchParams.get('limit')) || 25))
+
+  if (!agentId) {
+    return NextResponse.json({ error: 'agentId is required' }, { status: 400 })
+  }
+
+  try {
+    const agent = await ensureSwarmFeedAgent(agentId)
+    const result = await getBookmarks(agent.swarmfeedApiKey!, { cursor, limit })
+    return NextResponse.json(result)
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : 'Failed to fetch bookmarks'
+    const status = message === 'Agent not found'
+      ? 404
+      : message.includes('not enabled')
+        ? 400
+        : 502
+    return NextResponse.json({ error: message }, { status })
+  }
+}

package/src/app/api/swarmfeed/notifications/route.ts

@@ -0,0 +1,30 @@
+import { NextResponse } from 'next/server'
+import { getNotifications } from '@/lib/swarmfeed-client'
+import { ensureSwarmFeedAgent } from '@/lib/server/agents/agent-swarm-registration'
+
+export const dynamic = 'force-dynamic'
+
+export async function GET(req: Request) {
+  const { searchParams } = new URL(req.url)
+  const agentId = (searchParams.get('agentId') || '').trim()
+  const cursor = searchParams.get('cursor') || undefined
+  const limit = Math.max(1, Math.min(100, Number(searchParams.get('limit')) || 25))
+
+  if (!agentId) {
+    return NextResponse.json({ error: 'agentId is required' }, { status: 400 })
+  }
+
+  try {
+    const agent = await ensureSwarmFeedAgent(agentId)
+    const result = await getNotifications(agent.swarmfeedApiKey!, { cursor, limit })
+    return NextResponse.json(result)
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : 'Failed to fetch notifications'
+    const status = message === 'Agent not found'
+      ? 404
+      : message.includes('not enabled')
+        ? 400
+        : 502
+    return NextResponse.json({ error: message }, { status })
+  }
+}

package/src/app/api/swarmfeed/posts/[postId]/replies/route.ts

@@ -0,0 +1,23 @@
+import { NextResponse } from 'next/server'
+import { getPostReplies } from '@/lib/swarmfeed-client'
+
+export const dynamic = 'force-dynamic'
+
+type RouteContext = {
+  params: Promise<{ postId: string }>
+}
+
+export async function GET(req: Request, context: RouteContext) {
+  const { postId } = await context.params
+  const { searchParams } = new URL(req.url)
+  const cursor = searchParams.get('cursor') || undefined
+  const limit = Math.max(1, Math.min(100, Number(searchParams.get('limit')) || 30))
+
+  try {
+    const replies = await getPostReplies(postId, { cursor, limit })
+    return NextResponse.json(replies)
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : 'Failed to fetch replies'
+    return NextResponse.json({ error: message }, { status: 502 })
+  }
+}

package/src/app/api/swarmfeed/posts/[postId]/route.ts

@@ -0,0 +1,20 @@
+import { NextResponse } from 'next/server'
+import { getPost } from '@/lib/swarmfeed-client'
+
+export const dynamic = 'force-dynamic'
+
+type RouteContext = {
+  params: Promise<{ postId: string }>
+}
+
+export async function GET(_req: Request, context: RouteContext) {
+  const { postId } = await context.params
+
+  try {
+    const post = await getPost(postId)
+    return NextResponse.json(post)
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : 'Failed to fetch post'
+    return NextResponse.json({ error: message }, { status: 502 })
+  }
+}

package/src/app/api/swarmfeed/posts/route.ts

@@ -1,9 +1,7 @@
 import { NextResponse } from 'next/server'
-import { createPost, getFeed, registerAgent } from '@/lib/swarmfeed-client'
-import { getAgent, patchAgent } from '@/lib/server/agents/agent-repository'
+import { createPost, getFeed } from '@/lib/swarmfeed-client'
+import { ensureSwarmFeedAgent } from '@/lib/server/agents/agent-swarm-registration'
 import { safeParseBody } from '@/lib/server/safe-parse-body'
-import { log } from '@/lib/server/logger'
-import type { Agent } from '@/types'
 
 export const dynamic = 'force-dynamic'
 
@@ -28,6 +26,7 @@ export async function POST(req: Request) {
     content?: string
     channelId?: string
     parentId?: string
+    quotedPostId?: string
   }>(req)
   if (error) return error
 
@@ -38,61 +37,22 @@ export async function POST(req: Request) {
     return NextResponse.json({ error: 'content is required' }, { status: 400 })
   }
 
-  // Look up the agent and auto-register on SwarmFeed if needed
-  let agent = getAgent(body.agentId) as Agent | undefined
-  if (!agent) {
-    return NextResponse.json({ error: 'Agent not found' }, { status: 404 })
-  }
-  if (!agent.swarmfeedEnabled) {
-    return NextResponse.json(
-      { error: 'SwarmFeed is not enabled for this agent. Enable it in agent settings first.' },
-      { status: 400 },
-    )
-  }
-
-  // Auto-register if enabled but no API key yet
-  if (!agent.swarmfeedApiKey) {
-    const agentName = agent.name
-    try {
-      log.info('swarmfeed', `Auto-registering agent "${agentName}" on SwarmFeed`)
-      const reg = await registerAgent({
-        name: agent.name,
-        description: agent.description || agent.swarmfeedBio || `${agent.name} agent on SwarmClaw`,
-        framework: 'swarmclaw',
-        model: agent.model,
-        avatar: agent.avatarUrl || undefined,
-        bio: agent.swarmfeedBio || undefined,
-      })
-      patchAgent(agent.id, (current) => {
-        if (!current) return null
-        return {
-          ...current,
-          swarmfeedApiKey: reg.apiKey,
-          swarmfeedAgentId: reg.agentId,
-          swarmfeedJoinedAt: current.swarmfeedJoinedAt ?? Date.now(),
-          updatedAt: Date.now(),
-        }
-      })
-      agent = getAgent(body.agentId) as Agent | undefined
-      if (!agent?.swarmfeedApiKey) {
-        return NextResponse.json({ error: 'Registration succeeded but API key not saved' }, { status: 500 })
-      }
-    } catch (err: unknown) {
-      const message = err instanceof Error ? err.message : 'Registration failed'
-      log.error('swarmfeed', `Auto-registration failed for "${agentName}": ${message}`)
-      return NextResponse.json({ error: `SwarmFeed registration failed: ${message}` }, { status: 502 })
-    }
-  }
-
   try {
-    const post = await createPost(agent.swarmfeedApiKey, {
+    const agent = await ensureSwarmFeedAgent(body.agentId)
+    const post = await createPost(agent.swarmfeedApiKey!, {
       content: body.content.trim(),
       channelId: typeof body.channelId === 'string' ? body.channelId : undefined,
       parentId: typeof body.parentId === 'string' ? body.parentId : undefined,
+      quotedPostId: typeof body.quotedPostId === 'string' ? body.quotedPostId : undefined,
     })
     return NextResponse.json(post)
   } catch (err: unknown) {
     const message = err instanceof Error ? err.message : 'Failed to create post'
-    return NextResponse.json({ error: message }, { status: 502 })
+    const status = message === 'Agent not found'
+      ? 404
+      : message.includes('not enabled')
+        ? 400
+        : 502
+    return NextResponse.json({ error: message }, { status })
   }
 }

package/src/app/api/swarmfeed/profiles/[agentId]/posts/route.ts

@@ -0,0 +1,25 @@
+import { NextResponse } from 'next/server'
+import { getProfilePosts } from '@/lib/swarmfeed-client'
+
+export const dynamic = 'force-dynamic'
+
+type RouteContext = {
+  params: Promise<{ agentId: string }>
+}
+
+export async function GET(req: Request, context: RouteContext) {
+  const { agentId } = await context.params
+  const { searchParams } = new URL(req.url)
+  const cursor = searchParams.get('cursor') || undefined
+  const limit = Math.max(1, Math.min(100, Number(searchParams.get('limit')) || 20))
+  const filterRaw = searchParams.get('filter')
+  const filter = filterRaw === 'posts' || filterRaw === 'replies' ? filterRaw : undefined
+
+  try {
+    const result = await getProfilePosts(agentId, { cursor, limit, filter })
+    return NextResponse.json(result)
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : 'Failed to fetch profile posts'
+    return NextResponse.json({ error: message }, { status: 502 })
+  }
+}

package/src/app/api/swarmfeed/profiles/[agentId]/route.ts

@@ -0,0 +1,32 @@
+import { NextResponse } from 'next/server'
+import { getFollowState, getProfile } from '@/lib/swarmfeed-client'
+import { ensureSwarmFeedAgent } from '@/lib/server/agents/agent-swarm-registration'
+
+export const dynamic = 'force-dynamic'
+
+type RouteContext = {
+  params: Promise<{ agentId: string }>
+}
+
+export async function GET(req: Request, context: RouteContext) {
+  const { agentId } = await context.params
+  const { searchParams } = new URL(req.url)
+  const viewerAgentId = (searchParams.get('viewerAgentId') || '').trim()
+
+  try {
+    const profile = await getProfile(agentId)
+    if (!viewerAgentId) return NextResponse.json(profile)
+
+    const viewer = await ensureSwarmFeedAgent(viewerAgentId)
+    const followState = await getFollowState(viewer.swarmfeedAgentId!, agentId)
+    return NextResponse.json({ ...profile, isFollowing: followState.isFollowing })
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : 'Failed to fetch profile'
+    const status = message === 'Agent not found'
+      ? 404
+      : message.includes('not enabled')
+        ? 400
+        : 502
+    return NextResponse.json({ error: message }, { status })
+  }
+}

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

@@ -1,8 +1,7 @@
 import { NextResponse } from 'next/server'
 import { getFeed } from '@/lib/swarmfeed-client'
-import { loadAgents } from '@/lib/server/storage'
+import { ensureSwarmFeedAgent } from '@/lib/server/agents/agent-swarm-registration'
 import type { FeedType } from '@/types/swarmfeed'
-import type { Agent } from '@/types'
 
 export const dynamic = 'force-dynamic'
 
@@ -11,6 +10,7 @@ const VALID_FEED_TYPES = new Set<FeedType>(['for_you', 'following', 'channel', '
 export async function GET(req: Request) {
   const { searchParams } = new URL(req.url)
   const type = (searchParams.get('type') || 'for_you') as FeedType
+  const localAgentId = searchParams.get('agentId') || undefined
   if (!VALID_FEED_TYPES.has(type)) {
     return NextResponse.json({ error: 'Invalid feed type' }, { status: 400 })
   }
@@ -19,23 +19,25 @@ export async function GET(req: Request) {
   const limitStr = searchParams.get('limit')
   const limit = limitStr ? Math.max(1, Math.min(100, Number(limitStr) || 20)) : undefined
 
-  // For authenticated feeds (following), find the first enabled agent's API key
-  let agentApiKey: string | undefined
-  if (type === 'following') {
-    const agents = Object.values(loadAgents()) as Agent[]
-    const feedAgent = agents.find((a) => a.swarmfeedEnabled && a.swarmfeedApiKey)
-    agentApiKey = feedAgent?.swarmfeedApiKey ?? undefined
-    // No registered agent — return empty feed instead of triggering a 401
-    if (!agentApiKey) {
-      return NextResponse.json({ posts: [], nextCursor: undefined })
-    }
+  if (type === 'following' && !localAgentId) {
+    return NextResponse.json({ error: 'agentId is required for following feeds' }, { status: 400 })
   }
 
   try {
+    let agentApiKey: string | undefined
+    if (localAgentId) {
+      const scopedAgent = await ensureSwarmFeedAgent(localAgentId)
+      agentApiKey = scopedAgent.swarmfeedApiKey || undefined
+    }
     const result = await getFeed(type, { channelId, cursor, limit }, agentApiKey)
     return NextResponse.json(result)
   } catch (err: unknown) {
     const message = err instanceof Error ? err.message : 'Failed to fetch feed'
-    return NextResponse.json({ error: message }, { status: 502 })
+    const status = message === 'Agent not found'
+      ? 404
+      : message.includes('not enabled')
+        ? 400
+        : 502
+    return NextResponse.json({ error: message }, { status })
   }
 }

package/src/app/api/swarmfeed/search/route.ts

@@ -0,0 +1,30 @@
+import { NextResponse } from 'next/server'
+import { searchSwarmFeed } from '@/lib/swarmfeed-client'
+import type { SwarmFeedSearchType } from '@/types/swarmfeed'
+
+export const dynamic = 'force-dynamic'
+
+const VALID_SEARCH_TYPES = new Set<SwarmFeedSearchType>(['posts', 'agents', 'channels', 'hashtags'])
+
+export async function GET(req: Request) {
+  const { searchParams } = new URL(req.url)
+  const query = (searchParams.get('q') || '').trim()
+  const typeRaw = searchParams.get('type') || undefined
+  const type = typeRaw && VALID_SEARCH_TYPES.has(typeRaw as SwarmFeedSearchType)
+    ? typeRaw as SwarmFeedSearchType
+    : undefined
+  const limit = Math.max(1, Math.min(50, Number(searchParams.get('limit')) || 12))
+  const offset = Math.max(0, Number(searchParams.get('offset')) || 0)
+
+  if (!query) {
+    return NextResponse.json({ error: 'q is required' }, { status: 400 })
+  }
+
+  try {
+    const results = await searchSwarmFeed({ query, type, limit, offset })
+    return NextResponse.json(results)
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : 'Failed to search SwarmFeed'
+    return NextResponse.json({ error: message }, { status: 502 })
+  }
+}

package/src/app/api/swarmfeed/suggested/route.ts

@@ -0,0 +1,25 @@
+import { NextResponse } from 'next/server'
+import { getSuggestedFollows } from '@/lib/swarmfeed-client'
+import { ensureSwarmFeedAgent } from '@/lib/server/agents/agent-swarm-registration'
+
+export const dynamic = 'force-dynamic'
+
+export async function GET(req: Request) {
+  const { searchParams } = new URL(req.url)
+  const localAgentId = (searchParams.get('agentId') || '').trim()
+  const limit = Math.max(1, Math.min(20, Number(searchParams.get('limit')) || 5))
+
+  try {
+    const agent = localAgentId ? await ensureSwarmFeedAgent(localAgentId) : null
+    const result = await getSuggestedFollows(agent?.swarmfeedApiKey || undefined, limit)
+    return NextResponse.json(result)
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : 'Failed to fetch suggestions'
+    const status = message === 'Agent not found'
+      ? 404
+      : message.includes('not enabled')
+        ? 400
+        : 502
+    return NextResponse.json({ error: message }, { status })
+  }
+}

package/src/cli/index.js

@@ -801,9 +801,20 @@ const COMMAND_GROUPS = [
     description: 'SwarmFeed social network',
     commands: [
       cmd('feed', 'GET', '/swarmfeed', 'Get SwarmFeed timeline'),
+      cmd('search', 'GET', '/swarmfeed/search', 'Search SwarmFeed posts, agents, channels, or hashtags'),
       cmd('channels', 'GET', '/swarmfeed/channels', 'List SwarmFeed channels'),
+      cmd('bookmarks', 'GET', '/swarmfeed/bookmarks', 'Get bookmarked SwarmFeed posts for an agent'),
+      cmd('notifications', 'GET', '/swarmfeed/notifications', 'Get SwarmFeed notifications for an agent'),
+      cmd('suggested', 'GET', '/swarmfeed/suggested', 'Get suggested SwarmFeed follows'),
       cmd('posts', 'GET', '/swarmfeed/posts', 'Get recent posts'),
+      cmd('post-get', 'GET', '/swarmfeed/posts/:postId', 'Get a SwarmFeed post by id'),
+      cmd('replies', 'GET', '/swarmfeed/posts/:postId/replies', 'Get replies for a SwarmFeed post'),
       cmd('post', 'POST', '/swarmfeed/posts', 'Create a post', { expectsJsonBody: true }),
+      cmd('profile', 'GET', '/swarmfeed/profiles/:agentId', 'Get a SwarmFeed agent profile'),
+      cmd('profile-posts', 'GET', '/swarmfeed/profiles/:agentId/posts', 'Get recent posts for a SwarmFeed agent profile'),
+      cmd('action', 'POST', '/swarmfeed/actions', 'Run a SwarmFeed action such as follow, bookmark, repost, or quote repost', {
+        expectsJsonBody: true,
+      }),
     ],
   },
   {

package/src/features/swarmfeed/agent-social-settings.tsx

@@ -179,6 +179,12 @@ export function AgentSocialSettings({ agent, onUpdate }: {
 
               {heartbeat.enabled && (
                 <>
+                  {agent.heartbeatEnabled !== true && (
+                    <div className="rounded-[14px] border border-amber-400/20 bg-amber-400/8 px-4 py-3 text-[12px] leading-[1.6] text-amber-100">
+                      SwarmFeed heartbeat depends on this agent&apos;s main heartbeat/autonomy loop. Social automation is configured here, but it will stay inactive until general heartbeat is enabled on the agent.
+                    </div>
+                  )}
+
                   <label className="flex items-center gap-3 cursor-pointer">
                     <div
                       onClick={() => setHeartbeat((h) => ({ ...h, browseFeed: !h.browseFeed }))}
@@ -226,7 +232,7 @@ export function AgentSocialSettings({ agent, onUpdate }: {
                       style={{ fontFamily: 'inherit' }}
                     >
                       <option value="manual_only">Manual only</option>
-                      <option value="every_cycle">Every cycle</option>
+                      <option value="every_cycle">Every heartbeat cycle</option>
                       <option value="daily">Daily</option>
                       <option value="on_task_completion">On task completion</option>
                     </select>