@swarmclawai/swarmclaw 1.2.6 → 1.2.8

package/skills/tools/platform.md

@@ -0,0 +1,144 @@
+# Platform Tool
+
+Interact with the SwarmClaw platform: manage tasks, communicate with humans and other agents, access projects, and participate in chatrooms.
+
+## Action Groups
+
+### Tasks
+
+| Action | Description | Key Parameters |
+|--------|-------------|----------------|
+| `tasks.create` | Create a new task | `title`, `description`, `priority` |
+| `tasks.update` | Update task fields | `id`, fields to update |
+| `tasks.list` | List tasks with filters | `status`, `assignee`, `priority` |
+| `tasks.get` | Get task details | `id` |
+| `tasks.complete` | Mark task as done | `id`, `result` (optional summary) |
+
+#### Create a task
+
+```json
+{
+  "action": "tasks.create",
+  "title": "Review PR #55",
+  "description": "Check for type safety issues and test coverage",
+  "priority": "high"
+}
+```
+
+#### List open tasks
+
+```json
+{ "action": "tasks.list", "status": "open" }
+```
+
+### Communication
+
+| Action | Description | Key Parameters |
+|--------|-------------|----------------|
+| `communicate.ask_human` | Block and wait for human input | `question`, `context` |
+| `communicate.send_message` | Send to a connector channel | `connector`, `channel`, `message` |
+| `communicate.delegate` | Route work to another agent | `agentId`, `message` |
+| `communicate.spawn` | Create a subagent for parallel work | `agentId`, `message`, `mode` |
+
+#### Ask human (blocks execution)
+
+```json
+{
+  "action": "communicate.ask_human",
+  "question": "Should I proceed with the database migration?",
+  "context": "This will add 3 new columns to the users table and backfill existing rows."
+}
+```
+
+**Important:** `ask_human` blocks the agent loop until the human responds. Use it when you genuinely need input before continuing. Do not use it for status updates (use `send_message` instead).
+
+#### Send a message to Discord/Slack/Telegram
+
+```json
+{
+  "action": "communicate.send_message",
+  "connector": "discord",
+  "channel": "#general",
+  "message": "Deployment complete. All tests passing."
+}
+```
+
+#### Delegate to another agent
+
+```json
+{
+  "action": "communicate.delegate",
+  "agentId": "agent_research",
+  "message": "Find the top 5 competitors in the AI coding assistant space and summarize their pricing."
+}
+```
+
+#### Spawn a subagent
+
+```json
+{
+  "action": "communicate.spawn",
+  "agentId": "agent_coder",
+  "message": "Implement the dark mode toggle component",
+  "mode": "run"
+}
+```
+
+Modes:
+- `run` -- fire and forget, subagent runs independently
+- `session` -- creates a persistent session you can check on later
+
+### Projects
+
+| Action | Description | Key Parameters |
+|--------|-------------|----------------|
+| `projects.list` | List all projects | (none) |
+| `projects.get` | Get project details | `id` |
+
+```json
+{ "action": "projects.list" }
+```
+
+### Chatrooms
+
+| Action | Description | Key Parameters |
+|--------|-------------|----------------|
+| `chatrooms.send` | Send a message to a chatroom | `chatroomId`, `message` |
+| `chatrooms.list` | List available chatrooms | (none) |
+| `chatrooms.history` | Get recent messages | `chatroomId`, `limit` |
+
+```json
+{
+  "action": "chatrooms.send",
+  "chatroomId": "room_design",
+  "message": "The mockups are ready for review."
+}
+```
+
+### Agents
+
+| Action | Description | Key Parameters |
+|--------|-------------|----------------|
+| `agents.list` | List all agents | (none) |
+| `agents.get` | Get agent details | `id` |
+
+```json
+{ "action": "agents.list" }
+```
+
+## Communication Decision Guide
+
+| Situation | Action |
+|-----------|--------|
+| Need human approval before proceeding | `communicate.ask_human` |
+| Sharing a status update with the team | `communicate.send_message` |
+| Task is outside your expertise | `communicate.delegate` |
+| Task can run in parallel with your work | `communicate.spawn` |
+| Collaborating with agents in a shared space | `chatrooms.send` |
+
+## Tips
+
+- Use `ask_human` sparingly. Only block when you truly cannot proceed without input.
+- When delegating, provide enough context that the target agent can work independently.
+- Check `tasks.list` before creating duplicates.
+- Use `agents.list` to discover available agents and their capabilities before delegating.

package/skills/tools/skills.md

@@ -0,0 +1,83 @@
+# Skills Tool
+
+Discover and load skill files that teach you how to use tools, APIs, and workflows.
+
+## Actions
+
+| Action | Description | Key Parameters |
+|--------|-------------|----------------|
+| `list` | Browse all available skills | (none) |
+| `read` | Load a skill by name | `name` |
+| `search` | Find skills by keyword | `query` |
+
+## List Available Skills
+
+```json
+{ "action": "list" }
+```
+
+Returns all discoverable skill files with names and short descriptions.
+
+## Read a Skill
+
+```json
+{ "action": "read", "name": "tools/files" }
+```
+
+Loads the full content of a skill file. Skill names use path-style notation:
+
+- `tools/files` -- the files tool documentation
+- `tools/memory` -- the memory tool documentation
+- `swarmclaw` -- the platform overview skill
+- `github` -- GitHub CLI operations
+
+Name matching is flexible: partial matches work if unambiguous.
+
+## Search Skills
+
+```json
+{ "action": "search", "query": "browser screenshot" }
+```
+
+Searches skill file names, descriptions, and content for keyword matches. Returns ranked results.
+
+## Skill File Locations
+
+| Directory | Source | Description |
+|-----------|--------|-------------|
+| `skills/` | Built-in | Shipped with SwarmClaw, checked into the repo |
+| `data/skills/` | User-created | Added at runtime, not version-controlled |
+
+## Skill File Format
+
+Skills are markdown files (`.md`). They can be:
+
+- **Flat files**: `skills/swarmclaw.md`
+- **Directory-based**: `skills/github/SKILL.md`
+- **Nested**: `skills/tools/files.md`
+
+Optional YAML frontmatter can declare metadata:
+
+```yaml
+---
+name: my-skill
+description: What this skill teaches
+metadata:
+  openclaw:
+    requires:
+      bins: ["gh"]
+---
+```
+
+## When to Use Skills
+
+- **Before using an unfamiliar tool**: Load its skill to understand parameters, patterns, and best practices.
+- **When stuck on a task**: Search for skills related to what you're trying to accomplish.
+- **At the start of a session**: List skills to understand what documentation is available.
+
+## Tips
+
+- Skills are read-only reference material. They don't execute anything.
+- Load the relevant tool skill before attempting complex operations with that tool.
+- If a skill doesn't exist for what you need, you can still use the tool directly -- skills are guides, not gates.
+- User-created skills in `data/skills/` take the same format as built-in ones.

package/src/app/api/chats/[id]/messages/route.ts

@@ -3,7 +3,13 @@ import { notFound } from '@/lib/server/collection-helpers'
 import { materializeStreamingAssistantArtifacts } from '@/lib/chat/chat-streaming-state'
 import { appendSessionNote } from '@/lib/server/session-note'
 import { getSessionRunState } from '@/lib/server/runtime/session-run-manager'
-import { getSession, saveSession } from '@/lib/server/sessions/session-repository'
+import { getSession } from '@/lib/server/sessions/session-repository'
+import {
+  appendMessage,
+  getMessages,
+  replaceAllMessages,
+  replaceMessageAt,
+} from '@/lib/server/messages/message-repository'
 import type { Message } from '@/types'
 import { safeParseBody } from '@/lib/server/safe-parse-body'
 
@@ -11,22 +17,21 @@ export async function GET(req: Request, { params }: { params: Promise<{ id: stri
   const { id } = await params
   const session = getSession(id)
   if (!session) return notFound()
-  session.messages = Array.isArray(session.messages) ? session.messages : []
 
   // Use persisted fields plus the run ledger. Process-local execution state is
   // intentionally excluded here so stale registry entries do not block cleanup.
   const sessionClaimsActive = session.active === true
     || (typeof session.currentRunId === 'string' && session.currentRunId.trim().length > 0)
     || !!getSessionRunState(id).runningRunId
-  if (!sessionClaimsActive && materializeStreamingAssistantArtifacts(session.messages)) {
-    saveSession(id, session)
+  const allMessages = getMessages(id)
+  if (!sessionClaimsActive && materializeStreamingAssistantArtifacts(allMessages)) {
+    replaceAllMessages(id, allMessages)
   }
 
   const url = new URL(req.url)
   const limitParam = url.searchParams.get('limit')
   const beforeParam = url.searchParams.get('before')
 
-  const allMessages = Array.isArray(session.messages) ? session.messages : []
   const total = allMessages.length
 
   // If no limit param, return all messages (backward compatible)
@@ -64,13 +69,12 @@ export async function POST(req: Request, { params }: { params: Promise<{ id: str
     const session = getSession(id)
     if (!session) return notFound()
 
-    session.messages.push({
+    appendMessage(id, {
       role: 'user',
       text: '',
       kind: 'context-clear',
       time: Date.now(),
     })
-    saveSession(id, session)
     return NextResponse.json({ ok: true })
   }
 
@@ -96,37 +100,37 @@ export async function PUT(req: Request, { params }: { params: Promise<{ id: stri
   const { id } = await params
   const { data: body, error } = await safeParseBody<{ messageIndex: number; bookmarked: boolean }>(req)
   if (error) return error
-  const session = getSession(id)
-  if (!session) return notFound()
+  if (!getSession(id)) return notFound()
 
   const { messageIndex, bookmarked } = body
-  if (typeof messageIndex !== 'number' || messageIndex < 0 || messageIndex >= session.messages.length) {
+  const messages = getMessages(id)
+  if (typeof messageIndex !== 'number' || messageIndex < 0 || messageIndex >= messages.length) {
     return NextResponse.json({ error: 'Invalid message index' }, { status: 400 })
   }
 
-  session.messages[messageIndex].bookmarked = bookmarked
-  saveSession(id, session)
-  return NextResponse.json(session.messages[messageIndex])
+  const updated = { ...messages[messageIndex], bookmarked }
+  replaceMessageAt(id, messageIndex, updated)
+  return NextResponse.json(updated)
 }
 
 export async function DELETE(req: Request, { params }: { params: Promise<{ id: string }> }) {
   const { id } = await params
   const { data: body, error } = await safeParseBody<{ messageIndex: number }>(req)
   if (error) return error
-  const session = getSession(id)
-  if (!session) return notFound()
+  if (!getSession(id)) return notFound()
 
   const { messageIndex } = body
-  if (typeof messageIndex !== 'number' || messageIndex < 0 || messageIndex >= session.messages.length) {
+  const messages = getMessages(id)
+  if (typeof messageIndex !== 'number' || messageIndex < 0 || messageIndex >= messages.length) {
     return NextResponse.json({ error: 'Invalid message index' }, { status: 400 })
   }
 
   // Only allow deleting context-clear markers (safety guard)
-  if (session.messages[messageIndex].kind !== 'context-clear') {
+  if (messages[messageIndex].kind !== 'context-clear') {
     return NextResponse.json({ error: 'Only context-clear markers can be removed' }, { status: 400 })
   }
 
-  session.messages.splice(messageIndex, 1)
-  saveSession(id, session)
+  messages.splice(messageIndex, 1)
+  replaceAllMessages(id, messages)
   return NextResponse.json({ ok: true })
 }

package/src/app/api/chats/messages-route.test.ts

@@ -3,65 +3,119 @@ import test from 'node:test'
 
 import { runWithTempDataDir } from '@/lib/server/test-utils/run-with-temp-data-dir'
 
-test('chat messages route materializes stale streaming artifacts even if runtime memory is stale', () => {
+test('messages route serves and mutates repo-backed transcript history', () => {
   const output = runWithTempDataDir<{
-    status: number
-    returnedStreaming: boolean | null
-    returnedText: string | null
-    persistedStreaming: boolean | null
-    persistedText: string | null
-	  }>(`
-	    const storageMod = await import('./src/lib/server/storage')
-	    const routeMod = await import('./src/app/api/chats/[id]/messages/route')
-	    const runtimeStateMod = await import('./src/lib/server/runtime/runtime-state')
-	    const storage = storageMod.default || storageMod
-	    const route = routeMod.default || routeMod
-	    const runtimeState = runtimeStateMod.default || runtimeStateMod
+    fullCount: number
+    paginatedTexts: string[]
+    paginatedStartIndex: number
+    paginatedTotal: number
+    bookmarkPersisted: boolean
+    contextClearCountAfterPost: number
+    finalKinds: Array<string | null>
+    finalBookmarked: boolean
+    blobMessageCount: number
+  }>(`
+    const storageMod = await import('./src/lib/server/storage')
+    const repoMod = await import('@/lib/server/messages/message-repository')
+    const routeMod = await import('./src/app/api/chats/[id]/messages/route')
+    const storage = storageMod.default || storageMod
+    const repo = repoMod.default || repoMod
+    const route = routeMod.default || routeMod
 
-    storage.upsertStoredItem('sessions', 'session-stale', {
-      id: 'session-stale',
-      name: 'Stale session',
-      provider: 'ollama',
-      model: 'test-model',
-      createdAt: 1,
-      updatedAt: 1,
-      active: false,
-      currentRunId: null,
-      messages: [
-        { role: 'user', text: 'hello', time: 1 },
-        {
-          role: 'assistant',
-          text: 'partial reply',
-          time: 2,
-          streaming: true,
-          toolEvents: [{ name: 'http_request', input: '{}', output: '{"ok":true}' }],
-        },
-      ],
+    const now = Date.now()
+    storage.saveSessions({
+      sess_1: {
+        id: 'sess_1',
+        name: 'Repo-backed session',
+        cwd: process.env.WORKSPACE_DIR,
+        user: 'tester',
+        provider: 'openai',
+        model: 'gpt-5',
+        claudeSessionId: null,
+        codexThreadId: null,
+        opencodeSessionId: null,
+        delegateResumeIds: { claudeCode: null, codex: null, opencode: null, gemini: null },
+        messages: [],
+        createdAt: now,
+        lastActiveAt: now,
+      },
     })
 
-	    runtimeState.registerActiveSessionProcess('session-stale', { kill() {} })
+    repo.appendMessage('sess_1', { role: 'user', text: 'hello', time: now })
+    repo.appendMessage('sess_1', { role: 'user', text: '', kind: 'context-clear', time: now + 1 })
+    repo.appendMessage('sess_1', { role: 'assistant', text: 'welcome back', time: now + 2 })
+    storage.patchSession('sess_1', (current) => {
+      if (!current) return null
+      current.messages = [{ role: 'assistant', text: 'stale blob only', time: now - 10 }]
+      return current
+    })
+
+    const fullResponse = await route.GET(
+      new Request('http://local/api/chats/sess_1/messages'),
+      { params: Promise.resolve({ id: 'sess_1' }) },
+    )
+    const fullMessages = await fullResponse.json()
 
-    const response = await route.GET(
-      new Request('http://local/api/chats/session-stale/messages'),
-      { params: Promise.resolve({ id: 'session-stale' }) },
+    const paginatedResponse = await route.GET(
+      new Request('http://local/api/chats/sess_1/messages?limit=2'),
+      { params: Promise.resolve({ id: 'sess_1' }) },
     )
-    const payload = await response.json()
-    const persisted = storage.loadSession('session-stale')
-    const returned = Array.isArray(payload) ? payload[payload.length - 1] : null
-    const saved = Array.isArray(persisted?.messages) ? persisted.messages[persisted.messages.length - 1] : null
+    const paginated = await paginatedResponse.json()
+
+    const bookmarkResponse = await route.PUT(
+      new Request('http://local/api/chats/sess_1/messages', {
+        method: 'PUT',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ messageIndex: 2, bookmarked: true }),
+      }),
+      { params: Promise.resolve({ id: 'sess_1' }) },
+    )
+    const bookmarked = await bookmarkResponse.json()
+
+    await route.POST(
+      new Request('http://local/api/chats/sess_1/messages', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ kind: 'context-clear' }),
+      }),
+      { params: Promise.resolve({ id: 'sess_1' }) },
+    )
+
+    const afterPost = repo.getMessages('sess_1')
+    const contextClearCountAfterPost = afterPost.filter((message) => message.kind === 'context-clear').length
+
+    await route.DELETE(
+      new Request('http://local/api/chats/sess_1/messages', {
+        method: 'DELETE',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ messageIndex: 1 }),
+      }),
+      { params: Promise.resolve({ id: 'sess_1' }) },
+    )
+
+    const finalMessages = repo.getMessages('sess_1')
+    const sessions = storage.loadSessions()
 
     console.log(JSON.stringify({
-      status: response.status,
-      returnedStreaming: returned?.streaming === true,
-      returnedText: returned?.text || null,
-      persistedStreaming: saved?.streaming === true,
-      persistedText: saved?.text || null,
+      fullCount: fullMessages.length,
+      paginatedTexts: paginated.messages.map((message) => message.text),
+      paginatedStartIndex: paginated.startIndex,
+      paginatedTotal: paginated.total,
+      bookmarkPersisted: bookmarked.bookmarked === true,
+      contextClearCountAfterPost,
+      finalKinds: finalMessages.map((message) => message.kind || null),
+      finalBookmarked: finalMessages[1]?.bookmarked === true,
+      blobMessageCount: Array.isArray(sessions.sess_1.messages) ? sessions.sess_1.messages.length : -1,
     }))
-  `, { prefix: 'swarmclaw-chat-messages-route-' })
+  `, { prefix: 'swarmclaw-messages-route-' })
 
-  assert.equal(output.status, 200)
-  assert.equal(output.returnedStreaming, false)
-  assert.equal(output.persistedStreaming, false)
-  assert.equal(output.returnedText, 'partial reply')
-  assert.equal(output.persistedText, 'partial reply')
+  assert.equal(output.fullCount, 3)
+  assert.deepEqual(output.paginatedTexts, ['', 'welcome back'])
+  assert.equal(output.paginatedStartIndex, 1)
+  assert.equal(output.paginatedTotal, 3)
+  assert.equal(output.bookmarkPersisted, true)
+  assert.equal(output.contextClearCountAfterPost, 2)
+  assert.deepEqual(output.finalKinds, [null, null, 'context-clear'])
+  assert.equal(output.finalBookmarked, true)
+  assert.equal(output.blobMessageCount, 1)
 })

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

@@ -2,6 +2,7 @@ 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'
+import { errorMessage } from '@/lib/shared-utils'
 
 export async function POST(_req: Request, { params }: { params: Promise<{ id: string }> }) {
   const { id } = await params
@@ -15,9 +16,9 @@ export async function POST(_req: Request, { params }: { params: Promise<{ id: st
     const toolNames = tools.map((t: any) => t.name)
     await disconnectMcpServer(client, transport)
     return NextResponse.json({ ok: true, tools: toolNames })
-  } catch (err: any) {
+  } catch (err: unknown) {
     return NextResponse.json(
-      { ok: false, error: err.message || 'Connection failed' },
+      { ok: false, error: errorMessage(err) || 'Connection failed' },
       { status: 500 }
     )
   }

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

@@ -129,6 +129,7 @@ export async function POST(req: Request) {
         locals: result.locals,
         localPrimaryId: result.locals.find((item) => item.isPrimary)?.id || result.local.id,
         token: result.token,
+        gatewayProfileId: result.gatewayProfileId,
       })
     }
 
@@ -156,6 +157,7 @@ export async function POST(req: Request) {
         locals: result.locals,
         localPrimaryId: result.locals.find((item) => item.isPrimary)?.id || result.local.id,
         token: result.token,
+        gatewayProfileId: result.gatewayProfileId,
       })
     }
 

package/src/app/api/setup/doctor/route.ts

@@ -217,14 +217,14 @@ export async function GET(req: Request) {
   pushCheck(
     checks,
     'docker',
-    'Docker (sandbox runtime)',
+    'Docker (browser sandbox runtime)',
     docker.available ? 'pass' : 'warn',
     docker.available
-      ? `Docker ${docker.version || ''} is available for container sandbox execution.`.trim()
-      : 'Docker is not available. SwarmClaw will fall back to host execution until Docker Desktop is installed.',
+      ? `Docker ${docker.version || ''} is available for sandbox browser execution.`.trim()
+      : 'Docker is not available. SwarmClaw will use the host Playwright runtime unless Docker Desktop is installed.',
   )
   if (!docker.available) {
-    actions.push('Install Docker Desktop if you want shell, browser, and code execution to stay inside containers by default.')
+    actions.push('Install Docker Desktop if you want Playwright browser sessions to use the sandbox browser runtime.')
   }
 
   const gitRootCheck = run('git', ['rev-parse', '--is-inside-work-tree'], 4_000)

package/src/components/agents/agent-chat-list.tsx

@@ -193,9 +193,11 @@ export function AgentChatList({ inSidebar, onSelect }: Props) {
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [filteredAgents.map((a) => a.id).join(',')])
 
+  const [enableAgentTarget, setEnableAgentTarget] = useState<Agent | null>(null)
+
   const handleSelect = async (agent: Agent) => {
     if (agent.disabled === true && !agent.threadSessionId) {
-      toast.error(`${agent.name} is disabled. Re-enable it to start a new chat.`)
+      setEnableAgentTarget(agent)
       return
     }
     navigateTo('agents', agent.id)
@@ -547,6 +549,26 @@ export function AgentChatList({ inSidebar, onSelect }: Props) {
         onConfirm={() => { setConfirmBulkDelete(false); handleBulkDelete() }}
         onCancel={() => setConfirmBulkDelete(false)}
       />
+      <ConfirmDialog
+        open={!!enableAgentTarget}
+        title={`Enable ${enableAgentTarget?.name ?? 'Agent'}?`}
+        message={`${enableAgentTarget?.name ?? 'This agent'} is currently disabled. Enable it to start a new chat.`}
+        confirmLabel="Enable"
+        onConfirm={async () => {
+          if (!enableAgentTarget) return
+          try {
+            await api('PUT', `/agents/${enableAgentTarget.id}`, { disabled: false })
+            await loadAgents()
+            const agent = enableAgentTarget
+            setEnableAgentTarget(null)
+            handleSelect(agent)
+          } catch {
+            toast.error('Failed to enable agent')
+            setEnableAgentTarget(null)
+          }
+        }}
+        onCancel={() => setEnableAgentTarget(null)}
+      />
     </div>
   )
 }