@swarmclawai/swarmclaw 1.2.6 → 1.2.9

package/skills/tools/memory.md

@@ -0,0 +1,104 @@
+# Memory Tool
+
+Persistent knowledge storage across conversations. Store facts, preferences, context, and decisions so they survive beyond the current session.
+
+## Memory Tiers
+
+| Tier | Scope | Lifetime | Use For |
+|------|-------|----------|---------|
+| **Working** | Current session | Session duration | Scratch notes, intermediate results, task state |
+| **Durable** | Cross-session | Permanent until deleted | User preferences, project facts, learned patterns |
+| **Archive** | Cross-session | Permanent, lower priority | Completed task summaries, historical context |
+
+## Actions
+
+| Action | Description | Key Parameters |
+|--------|-------------|----------------|
+| `store` | Save a new memory | `title`, `value`, `category` |
+| `search` | Find memories by query | `query`, `scope` (optional) |
+| `get` | Retrieve a specific memory | `id` or `key` |
+| `update` | Modify an existing memory | `id`, `value` (and/or `title`, `category`) |
+
+## Store
+
+```json
+{
+  "action": "store",
+  "title": "User prefers dark mode",
+  "value": "The user explicitly asked for dark mode in all UI components. Use dark backgrounds (#1a1a2e) with light text (#e0e0e0).",
+  "category": "preference"
+}
+```
+
+### Categories
+
+| Category | When to Use |
+|----------|------------|
+| `preference` | User likes, dislikes, style choices |
+| `fact` | Verified information about user, project, or domain |
+| `decision` | Architecture decisions, design choices with rationale |
+| `context` | Background info that helps future conversations |
+| `note` | General observations, reminders |
+| `identity` | Agent's learned personality traits, communication style |
+
+## Search
+
+```json
+{ "action": "search", "query": "database schema preferences" }
+```
+
+Returns ranked results with relevance scores. Supports semantic-style matching (expanded query terms).
+
+### Scope Filtering
+
+```json
+{ "action": "search", "query": "API keys", "scope": "agent" }
+```
+
+| Scope | What It Searches |
+|-------|-----------------|
+| `auto` | Smart default: session + agent + global (recommended) |
+| `session` | Current session only |
+| `agent` | Current agent's memories |
+| `project` | Current project's memories |
+| `global` | Shared across all agents |
+| `all` | Everything |
+
+## Update
+
+```json
+{ "action": "update", "id": "mem_abc123", "value": "Updated: user now prefers system theme over dark mode" }
+```
+
+Use `update` when information changes. Avoids creating duplicate memories.
+
+## When to Remember
+
+**Do remember:**
+- User-stated preferences ("I prefer TypeScript", "always use tabs")
+- Corrections ("actually, the API endpoint is /v2/...")
+- Project-specific facts (tech stack, coding conventions, team structure)
+- Important decisions and their rationale
+
+**Do not remember:**
+- Ephemeral task details (file paths being edited right now)
+- Information already in the codebase (README, config files)
+- Trivial conversational context
+- Sensitive data (passwords, tokens, private keys)
+
+## When to Forget
+
+Use `update` to revise outdated memories rather than storing contradictory ones. If a memory is no longer relevant, update its value to reflect the current state.
+
+## Memory in Practice
+
+1. **Start of session**: Relevant memories are automatically injected into context based on the current agent, project, and conversation topic.
+2. **During conversation**: Store new insights as they emerge. Search when you need to recall something.
+3. **End of significant interaction**: Store a summary of decisions made, preferences learned, or context that would help next time.
+
+## Tips
+
+- Write memories in the third person for clarity: "The user prefers..." not "You prefer..."
+- Include enough context in the `value` that the memory is useful standalone
+- Use descriptive `title` fields -- they're used for search ranking
+- Prefer `category: "decision"` for architectural choices so they can be filtered later

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/agents/[id]/page.tsx

@@ -1,19 +1,13 @@
 'use client'
 
-import { useEffect, useState } from 'react'
+import { useEffect } from 'react'
 import { useParams } from 'next/navigation'
 import { useAppStore } from '@/stores/use-app-store'
-import { selectActiveSessionId } from '@/stores/slices/session-slice'
 import { ChatArea } from '@/components/chat/chat-area'
-import { CanvasPanel } from '@/components/canvas/canvas-panel'
 
 export default function AgentChatPage() {
   const { id } = useParams<{ id: string }>()
   const setCurrentAgent = useAppStore((s) => s.setCurrentAgent)
-  const activeSessionId = useAppStore(selectActiveSessionId)
-  const sessions = useAppStore((s) => s.sessions)
-  const agents = useAppStore((s) => s.agents)
-  const [canvasDismissedFor, setCanvasDismissedFor] = useState<string | null>(null)
 
   // Sync URL param to store
   useEffect(() => {
@@ -22,22 +16,11 @@ export default function AgentChatPage() {
     }
   }, [id, setCurrentAgent])
 
-  const currentSession = activeSessionId ? sessions[activeSessionId] : null
-  const hasCanvas = !!(currentSession?.canvasContent && canvasDismissedFor !== activeSessionId)
-  const canvasAgentName = currentSession?.agentId && agents[currentSession.agentId] ? agents[currentSession.agentId].name : undefined
-
   return (
     <div className="flex-1 flex h-full min-h-0 min-w-0">
       <div className="flex-1 min-h-0 min-w-0 overflow-hidden">
         <ChatArea key={id} />
       </div>
-      {hasCanvas && activeSessionId && (
-        <CanvasPanel
-          sessionId={activeSessionId}
-          agentName={canvasAgentName}
-          onClose={() => activeSessionId && setCanvasDismissedFor(activeSessionId)}
-        />
-      )}
     </div>
   )
 }

package/src/app/api/agents/thread-route.test.ts

@@ -116,7 +116,6 @@ test('POST /api/agents/[id]/thread reuses an existing thread for a disabled agen
     file: null,
     queuedCount: 0,
     currentRunId: null,
-    canvasContent: null,
   }
   saveSessions(sessions)
 

package/src/app/api/approvals/route.test.ts

@@ -46,11 +46,6 @@ test('GET and POST /api/approvals handle human-loop approvals only', () => {
       title: 'Approve deploy',
       data: { question: 'Deploy now?' },
     })
-    approvals.requestApproval({
-      category: 'wallet_action',
-      title: 'Legacy wallet approval',
-      data: { action: 'sign_message' },
-    })
 
     const pendingBefore = await route.GET()
     const pendingBeforeJson = await pendingBefore.json()
@@ -84,43 +79,32 @@ test('GET and POST /api/approvals handle human-loop approvals only', () => {
   assert.equal(output.storedStatus, 'approved')
 })
 
-test('POST /api/approvals rejects invalid and non-human-loop approvals', () => {
+test('POST /api/approvals rejects invalid payloads', () => {
   const output = runWithTempDataDir(`
     const approvalsMod = await import('./src/lib/server/approvals')
     const routeMod = await import('./src/app/api/approvals/route')
     const approvals = approvalsMod.default || approvalsMod
     const route = routeMod.default || routeMod
 
-    const walletApproval = approvals.requestApproval({
-      category: 'wallet_action',
-      title: 'Legacy wallet approval',
-      data: { action: 'sign_message' },
+    const humanApproval = approvals.requestApproval({
+      category: 'human_loop',
+      title: 'Test approval',
+      data: { question: 'Proceed?' },
     })
 
     const invalidResponse = await route.POST(new Request('http://local/api/approvals', {
       method: 'POST',
       headers: { 'content-type': 'application/json' },
-      body: JSON.stringify({ id: walletApproval.id }),
+      body: JSON.stringify({ id: humanApproval.id }),
     }))
     const invalidPayload = await invalidResponse.json()
 
-    const wrongCategory = await route.POST(new Request('http://local/api/approvals', {
-      method: 'POST',
-      headers: { 'content-type': 'application/json' },
-      body: JSON.stringify({ id: walletApproval.id, approved: true }),
-    }))
-    const wrongCategoryPayload = await wrongCategory.json()
-
     console.log(JSON.stringify({
       invalidStatus: invalidResponse.status,
       invalidError: invalidPayload?.error || null,
-      wrongCategoryStatus: wrongCategory.status,
-      wrongCategoryError: wrongCategoryPayload?.error || null,
     }))
   `)
 
   assert.equal(output.invalidStatus, 400)
   assert.match(String(output.invalidError || ''), /id and approved required/i)
-  assert.equal(output.wrongCategoryStatus, 400)
-  assert.match(String(output.wrongCategoryError || ''), /human-loop/i)
 })

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 })
 }