@swarmclawai/swarmclaw 1.0.6 → 1.0.8

package/README.md

@@ -8,22 +8,31 @@
   <img src="https://raw.githubusercontent.com/swarmclawai/swarmclaw/main/public/branding/swarmclaw-org-avatar.png" alt="SwarmClaw lobster logo" width="120" />
 </p>
 
-SwarmClaw is a self-hosted AI orchestration runtime for OpenClaw and multi-agent work. It helps you run autonomous agents with heartbeats, schedules, delegation, memory, runtime skills, and reviewed conversation-to-skill learning across OpenClaw gateways and other providers.
+SwarmClaw is a self-hosted AI runtime for OpenClaw and multi-agent work. It helps you run autonomous agents with heartbeats, schedules, delegation, memory, runtime skills, and reviewed conversation-to-skill learning across OpenClaw gateways and other providers.
 
 GitHub: https://github.com/swarmclawai/swarmclaw  
 Docs: https://swarmclaw.ai/docs  
 Website: https://swarmclaw.ai  
-Plugin tutorial: https://swarmclaw.ai/docs/plugin-tutorial
+Extension tutorial: https://swarmclaw.ai/docs/extension-tutorial
+
+## Release Notes
+
+### v1.0.8 Highlights
+
+- **Learned skills and self-healing**: SwarmClaw now keeps agent-scoped learned skills and shadow revisions so repeated successes and repeated external integration failures can harden into reusable local behavior without silently mutating the shared skill library.
+- **Direct chat stability**: chat-origin runs now stop after the visible answer instead of enqueueing hidden follow-up loops, leaked control tokens such as `NO_MESSAGE` stay out of the user transcript, and repeated internal reruns no longer replace the reply the user already saw.
+- **OpenClaw and Ollama route hardening**: agent thread sessions now repair stale credential/endpoint resolution more aggressively, including Ollama Cloud vs local endpoint selection and OpenClaw gateway fallback behavior.
+- **Operator UX fixes**: new agents appear in the list immediately, gateway-disconnected chat CTAs now route to the current agent's settings instead of global settings, setup-wizard flicker after access-key login is gone, and screenshot-heavy tool runs no longer render duplicate previews in chat.
 
 ## What SwarmClaw Focuses On
 
-- **AI orchestration**: LangGraph-backed orchestration, delegated work, subagents, durable jobs, checkpointing, and background task execution.
-- **Autonomy and memory**: heartbeats, schedules, long-running execution, durable memory, working memory, document recall, and project-aware context.
+- **Delegation and background execution**: delegated work, subagents, durable jobs, checkpointing, and background task execution.
+- **Autonomy and memory**: heartbeats, schedules, long-running execution, durable memory, reflection memory, human-context learning, document recall, and project-aware context.
 - **OpenClaw integration**: named gateway profiles, external runtimes, deploy helpers, config sync, approval handling, and OpenClaw agent file editing.
 - **Runtime skills**: pinned skills, OpenClaw-compatible `SKILL.md` import, on-demand skill execution, and configurable keyword or embedding-based recommendation.
 - **Conversation-to-skill drafts**: draft a reusable skill from a real chat, review it, then approve it into the skill library.
 - **Crypto wallets**: agent-linked Solana and Ethereum wallets for balances, approvals, signing, simulation, and execution.
-- **Operator tooling**: connectors, plugins, browser automation, shell/files/git tooling, and runtime guardrails.
+- **Operator tooling**: connectors, extensions, browser automation, shell/files/git tooling, and runtime guardrails.
 
 ## OpenClaw
 
@@ -45,14 +54,23 @@ npm i -g @swarmclawai/swarmclaw
 swarmclaw
 ```
 
-Running `swarmclaw` starts the server on `http://localhost:3456`.
+```bash
+yarn global add @swarmclawai/swarmclaw
+swarmclaw
+```
 
-### One-off run
+```bash
+pnpm add -g @swarmclawai/swarmclaw
+swarmclaw
+```
 
 ```bash
-npx @swarmclawai/swarmclaw
+bun add -g @swarmclawai/swarmclaw
+swarmclaw
 ```
 
+Running `swarmclaw` starts the server on `http://localhost:3456`.
+
 ### From the repo
 
 ```bash
@@ -63,12 +81,25 @@ npm run quickstart
 
 `npm run quickstart` installs dependencies, prepares local config and runtime state, and starts SwarmClaw.
 
+### Docker
+
+```bash
+git clone https://github.com/swarmclawai/swarmclaw.git
+cd swarmclaw
+mkdir -p data
+touch .env.local
+docker compose up -d --build
+```
+
+Then open `http://localhost:3456`.
+
 ## Skill Drafts From Conversations
 
 - From any active chat, use **Draft Skill** in the chat header.
 - Or open **Skills** and use **Draft From Current Chat**.
 - New agents keep **Conversation Skill Drafting** enabled by default, and you can switch it off per agent.
 - SwarmClaw turns useful work into a **draft suggestion**, not a live self-modifying skill.
+- Learned skills stay **user/agent scoped** by default. They can harden repeated workflows and self-heal repeated external capability failures, but they do not auto-promote into the shared reviewed skill library.
 - Review the suggested name, rationale, summary, and transcript snippet.
 - Approve it to save it into the normal skill library, or dismiss it.
 - Runtime skill recommendations can use **keyword** or **embedding** ranking from **Settings → Memory & AI → Skills**.
@@ -77,11 +108,11 @@ npm run quickstart
 
 - **Providers**: OpenClaw, OpenAI, Anthropic, Ollama, Google, DeepSeek, Groq, Together, Mistral, xAI, Fireworks, plus compatible custom endpoints.
 - **Delegation**: built-in delegation to Claude Code, Codex CLI, OpenCode CLI, Gemini CLI, and native SwarmClaw subagents.
-- **Autonomy**: heartbeat loops, schedules, background jobs, task execution, and agent wakeups.
-- **Memory**: hybrid recall, graph traversal, journaling, durable documents, and project-scoped context.
+- **Autonomy**: heartbeat loops, schedules, background jobs, task execution, supervisor recovery, and agent wakeups.
+- **Memory**: hybrid recall, graph traversal, journaling, durable documents, project-scoped context, automatic reflection memory, communication preferences, profile and boundary memory, significant events, and open follow-up loops.
 - **Wallets**: balances, transfers, signatures, EVM call/quote/swap flows, and approval-gated execution.
 - **Connectors**: Discord, Slack, Telegram, WhatsApp, Teams, Matrix, OpenClaw, and more.
-- **Plugins**: tool plugins, UI extensions, hooks, install/update flows, and runtime policy controls.
+- **Extensions**: external tool extensions, UI modules, hooks, and install/update flows.
 
 ## Requirements
 
@@ -102,7 +133,6 @@ npm run quickstart
 - Getting started: https://swarmclaw.ai/docs/getting-started
 - OpenClaw setup: https://swarmclaw.ai/docs/openclaw-setup
 - Agents: https://swarmclaw.ai/docs/agents
-- Orchestration: https://swarmclaw.ai/docs/orchestration
 - Connectors: https://swarmclaw.ai/docs/connectors
-- Plugins: https://swarmclaw.ai/docs/plugins
+- Extensions: https://swarmclaw.ai/docs/extensions
 - CLI reference: https://swarmclaw.ai/docs/cli

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@swarmclawai/swarmclaw",
-  "version": "1.0.6",
-  "description": "Self-hosted AI orchestration control plane for OpenClaw, multi-agent workflows, runtime skills, crypto wallets, and chat platform connectors.",
+  "version": "1.0.8",
+  "description": "Self-hosted AI runtime for OpenClaw, delegation, autonomy, runtime skills, crypto wallets, and chat platform connectors.",
   "license": "MIT",
   "publishConfig": {
     "access": "public",
@@ -12,15 +12,15 @@
     "url": "git+https://github.com/swarmclawai/swarmclaw.git"
   },
   "keywords": [
-    "ai",
-    "agents",
-    "llm",
-    "orchestration",
-    "swarm",
     "openclaw",
-    "self-hosted",
-    "wallets",
-    "multi-agent"
+    "crustacean",
+    "clawd",
+    "clawdbot",
+    "moltbot",
+    "openclaw-skill",
+    "openclaw-dashboard",
+    "openclaw-gateway",
+    "clawdbot-dashboard"
   ],
   "engines": {
     "node": ">=22.6.0"

package/src/app/activity/page.tsx

@@ -21,6 +21,8 @@ const ACTION_COLORS: Record<string, string> = {
   queued: 'bg-amber-500/15 text-amber-400',
   completed: 'bg-emerald-500/15 text-emerald-400',
   failed: 'bg-red-500/15 text-red-400',
+  archived: 'bg-white/[0.06] text-text-3',
+  restored: 'bg-sky-500/15 text-sky-400',
   approved: 'bg-green-500/15 text-green-400',
   rejected: 'bg-red-500/15 text-red-400',
 }

package/src/app/api/agents/[id]/clone/route.ts

@@ -14,7 +14,7 @@ export async function POST(_req: Request, { params }: { params: Promise<{ id: st
   const now = Date.now()
 
   // Deep-copy the source agent, then override clone-specific fields
-  const cloned = JSON.parse(JSON.stringify(source)) as Record<string, unknown>
+  const cloned = JSON.parse(JSON.stringify(source)) as typeof source
   cloned.id = newId
   cloned.name = `${source.name} (Copy)`
   cloned.createdAt = now

package/src/app/api/agents/[id]/route.ts

@@ -6,6 +6,7 @@ import { ensureAgentThreadSession } from '@/lib/server/agents/agent-thread-sessi
 import { suspendAgentReferences } from '@/lib/server/agents/agent-cascade'
 import { notify } from '@/lib/server/ws-hub'
 import { normalizeAgentSandboxConfig } from '@/lib/agent-sandbox-defaults'
+import { normalizeCapabilitySelection } from '@/lib/capability-selection'
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 const ops: CollectionOps<any> = { load: () => loadAgents({ includeTrashed: true }), save: saveAgents, topic: 'agents', table: 'agents' }
@@ -15,15 +16,27 @@ export async function PUT(req: Request, { params }: { params: Promise<{ id: stri
   const body = await req.json()
   const result = mutateItem(ops, id, (agent) => {
     Object.assign(agent, body, { updatedAt: Date.now() })
-    if (Array.isArray(body.plugins) || Array.isArray(body.tools)) {
-      agent.plugins = Array.isArray(body.plugins) ? body.plugins : body.tools
-      delete (agent as Record<string, unknown>).tools
+    if (body.tools !== undefined || body.extensions !== undefined) {
+      const nextSelection = normalizeCapabilitySelection({
+        tools: Array.isArray(body.tools) ? body.tools : agent.tools,
+        extensions: Array.isArray(body.extensions) ? body.extensions : agent.extensions,
+      })
+      agent.tools = nextSelection.tools
+      agent.extensions = nextSelection.extensions
     }
-    if (body.platformAssignScope === 'all' || body.platformAssignScope === 'self') {
-      agent.platformAssignScope = body.platformAssignScope
-      agent.isOrchestrator = body.platformAssignScope === 'all'
-    } else if (agent.platformAssignScope === 'all' || agent.platformAssignScope === 'self') {
-      agent.isOrchestrator = agent.platformAssignScope === 'all'
+    if (body.delegationEnabled !== undefined) {
+      agent.delegationEnabled = body.delegationEnabled === true
+    }
+    if (body.delegationTargetMode === 'all' || body.delegationTargetMode === 'selected') {
+      agent.delegationTargetMode = body.delegationTargetMode
+    }
+    if (body.delegationTargetAgentIds !== undefined) {
+      agent.delegationTargetAgentIds = Array.isArray(body.delegationTargetAgentIds)
+        ? body.delegationTargetAgentIds.filter((entry: unknown): entry is string => typeof entry === 'string' && entry.trim().length > 0)
+        : []
+    }
+    if (agent.delegationTargetMode !== 'selected') {
+      agent.delegationTargetAgentIds = []
     }
     if (body.apiEndpoint !== undefined) {
       agent.apiEndpoint = normalizeProviderEndpoint(
@@ -67,8 +80,9 @@ export async function PUT(req: Request, { params }: { params: Promise<{ id: stri
         priority: typeof target.priority === 'number' ? target.priority : index + 1,
       }))
     }
+    delete (agent as Record<string, unknown>).platformAssignScope
+    delete (agent as Record<string, unknown>).subAgentIds
     delete (agent as Record<string, unknown>).isOrchestrator
-    agent.isOrchestrator = agent.platformAssignScope === 'all'
     delete (agent as Record<string, unknown>).id
     agent.id = id
     return agent
@@ -113,11 +127,11 @@ export async function DELETE(_req: Request, { params }: { params: Promise<{ id:
   // Detach sessions from the trashed agent
   const sessions = loadSessions()
   const detached: Array<[string, unknown]> = []
-  for (const session of Object.values(sessions) as Array<Record<string, unknown>>) {
+  for (const session of Object.values(sessions)) {
     if (!session || session.agentId !== id) continue
     session.agentId = null
     session.heartbeatEnabled = false
-    detached.push([session.id as string, session])
+    detached.push([session.id, session])
   }
   if (detached.length > 0) {
     upsertStoredItems('sessions', detached)

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

@@ -5,7 +5,7 @@ import { loadAgents, loadSessions, loadUsage, logActivity, upsertStoredItem } fr
 import { normalizeProviderEndpoint } from '@/lib/openclaw/openclaw-endpoint'
 import { notify } from '@/lib/server/ws-hub'
 import { getAgentSpendWindows } from '@/lib/server/cost'
-import { resolveAgentPluginSelection } from '@/lib/agent-default-tools'
+import { resolveAgentToolSelection } from '@/lib/agent-default-tools'
 import { normalizeAgentSandboxConfig } from '@/lib/agent-sandbox-defaults'
 import { AgentCreateSchema, formatZodError } from '@/lib/validation/schemas'
 import { z } from 'zod'
@@ -22,9 +22,6 @@ export async function GET(req: Request) {
   const agents = loadAgents()
   const sessions = loadSessions()
   const usage = loadUsage()
-  for (const agent of Object.values(agents)) {
-    agent.isOrchestrator = agent.platformAssignScope === 'all'
-  }
   // Enrich agents that have spend limits with current spend windows
   for (const agent of Object.values(agents)) {
     if (
@@ -32,7 +29,10 @@ export async function GET(req: Request) {
       || (typeof agent.dailyBudget === 'number' && agent.dailyBudget > 0)
       || (typeof agent.hourlyBudget === 'number' && agent.hourlyBudget > 0)
     ) {
-      const spend = getAgentSpendWindows(agent.id, Date.now(), { sessions, usage })
+      const spend = getAgentSpendWindows(agent.id, Date.now(), {
+        sessions: sessions as unknown as Record<string, Record<string, unknown>>,
+        usage,
+      })
       if (typeof agent.monthlyBudget === 'number' && agent.monthlyBudget > 0) agent.monthlySpend = spend.monthly
       if (typeof agent.dailyBudget === 'number' && agent.dailyBudget > 0) agent.dailySpend = spend.daily
       if (typeof agent.hourlyBudget === 'number' && agent.hourlyBudget > 0) agent.hourlySpend = spend.hourly
@@ -63,15 +63,14 @@ export async function POST(req: Request) {
     return NextResponse.json(formatZodError(parsed.error as z.ZodError), { status: 400 })
   }
   const body = parsed.data
-  const plugins = resolveAgentPluginSelection({
-    hasExplicitPlugins: Boolean(rawRecord && Object.prototype.hasOwnProperty.call(rawRecord, 'plugins')),
+  const capabilitySelection = resolveAgentToolSelection({
     hasExplicitTools: Boolean(rawRecord && Object.prototype.hasOwnProperty.call(rawRecord, 'tools')),
-    plugins: body.plugins,
+    hasExplicitExtensions: Boolean(rawRecord && Object.prototype.hasOwnProperty.call(rawRecord, 'extensions')),
     tools: body.tools,
+    extensions: body.extensions,
   })
   const id = genId()
   const now = Date.now()
-  const platformAssignScope = body.platformAssignScope
   const agent = {
     id,
     name: body.name,
@@ -91,10 +90,11 @@ export async function POST(req: Request) {
       ...target,
       apiEndpoint: normalizeProviderEndpoint(target.provider, target.apiEndpoint || null),
     })),
-    isOrchestrator: platformAssignScope === 'all',
-    platformAssignScope,
-    subAgentIds: body.subAgentIds,
-    plugins,
+    delegationEnabled: body.delegationEnabled ?? false,
+    delegationTargetMode: body.delegationTargetMode ?? 'all',
+    delegationTargetAgentIds: (body.delegationTargetMode === 'selected' ? body.delegationTargetAgentIds : []).filter(Boolean),
+    tools: capabilitySelection.tools,
+    extensions: capabilitySelection.extensions,
     skills: body.skills,
     skillIds: body.skillIds,
     mcpServerIds: body.mcpServerIds,
@@ -103,7 +103,7 @@ export async function POST(req: Request) {
     thinkingLevel: body.thinkingLevel || undefined,
     autoRecovery: body.autoRecovery || false,
     disabled: body.disabled || false,
-    heartbeatEnabled: body.heartbeatEnabled || false,
+    heartbeatEnabled: body.heartbeatEnabled ?? true,
     heartbeatInterval: body.heartbeatInterval,
     heartbeatIntervalSec: body.heartbeatIntervalSec,
     heartbeatModel: body.heartbeatModel,
@@ -116,6 +116,7 @@ export async function POST(req: Request) {
     identityState: body.identityState ?? null,
     memoryScopeMode: body.memoryScopeMode,
     memoryTierPreference: body.memoryTierPreference,
+    proactiveMemory: body.proactiveMemory ?? true,
     autoDraftSkillSuggestions: body.autoDraftSkillSuggestions,
     projectId: body.projectId,
     avatarSeed: body.avatarSeed,

package/src/app/api/canvas/[sessionId]/route.ts

@@ -11,7 +11,7 @@ export async function GET(_req: Request, { params }: { params: Promise<{ session
 
   return NextResponse.json({
     sessionId,
-    content: (session as Record<string, unknown>).canvasContent || null,
+    content: (session as unknown as Record<string, unknown>).canvasContent || null,
   })
 }
 
@@ -23,7 +23,7 @@ export async function POST(req: Request, { params }: { params: Promise<{ session
   if (!session) return NextResponse.json({ error: 'Session not found' }, { status: 404 })
 
   const nextContent = normalizeCanvasContent(body.document ?? body.content)
-  ;(session as Record<string, unknown>).canvasContent = nextContent
+  ;(session as unknown as Record<string, unknown>).canvasContent = nextContent
   session.lastActiveAt = Date.now()
   sessions[sessionId] = session
   saveSessions(sessions)

package/src/app/api/chatrooms/[id]/chat/route.ts

@@ -21,7 +21,7 @@ import {
 import { filterHealthyChatroomAgents } from '@/lib/server/chatrooms/chatroom-health'
 import { evaluateRoutingRules } from '@/lib/server/chatrooms/chatroom-routing'
 import { markProviderFailure, markProviderSuccess } from '@/lib/server/provider-health'
-import { applyAgentReactionsFromText } from '@/lib/server/chatrooms/chatroom-orchestration'
+import { applyAgentReactionsFromText } from '@/lib/server/chatrooms/chatroom-agent-signals'
 import { resolvePrimaryAgentRoute } from '@/lib/server/agents/agent-runtime-config'
 import { shouldSuppressHiddenControlText, stripHiddenControlTokens } from '@/lib/server/agents/assistant-control'
 import type { Chatroom, ChatroomMessage, Agent } from '@/types'

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

@@ -5,7 +5,7 @@ import { normalizeProviderEndpoint } from '@/lib/openclaw/openclaw-endpoint'
 import { resolvePrimaryAgentRoute } from '@/lib/server/agents/agent-runtime-config'
 import { clearMainLoopStateForSession } from '@/lib/server/agents/main-agent-loop'
 import { getSessionRunState } from '@/lib/server/runtime/session-run-manager'
-import type { Session } from '@/types'
+import { normalizeCapabilitySelection } from '@/lib/capability-selection'
 
 export async function GET(_req: Request, { params }: { params: Promise<{ id: string }> }) {
   const { id } = await params
@@ -79,8 +79,18 @@ export async function PUT(req: Request, { params }: { params: Promise<{ id: stri
     session.routePreferredGatewayUseCase = routePreferredGatewayUseCase
   }
 
-  if (updates.plugins !== undefined) session.plugins = updates.plugins
-  else if (agentIdUpdateProvided && linkedAgent) session.plugins = Array.isArray(linkedAgent.plugins) ? linkedAgent.plugins : []
+  if (updates.tools !== undefined || updates.extensions !== undefined || (agentIdUpdateProvided && linkedAgent)) {
+    const nextSelection = normalizeCapabilitySelection({
+      tools: Array.isArray(updates.tools)
+        ? updates.tools
+        : (agentIdUpdateProvided && linkedAgent ? linkedAgent.tools : session.tools as string[] | undefined),
+      extensions: Array.isArray(updates.extensions)
+        ? updates.extensions
+        : (agentIdUpdateProvided && linkedAgent ? linkedAgent.extensions : session.extensions as string[] | undefined),
+    })
+    session.tools = nextSelection.tools
+    session.extensions = nextSelection.extensions
+  }
 
   if (updates.apiEndpoint !== undefined) {
     session.apiEndpoint = normalizeProviderEndpoint(

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

@@ -12,6 +12,7 @@ import { applyResolvedRoute, resolvePrimaryAgentRoute } from '@/lib/server/agent
 import { buildAgentDisabledMessage, isAgentDisabled } from '@/lib/server/agents/agent-availability'
 import { materializeStreamingAssistantArtifacts } from '@/lib/chat/chat-streaming-state'
 import { buildSessionListSummary } from '@/lib/chat/session-summary'
+import { normalizeCapabilitySelection } from '@/lib/capability-selection'
 export const dynamic = 'force-dynamic'
 
 async function ensureDaemonIfNeeded(source: string) {
@@ -22,6 +23,12 @@ async function ensureDaemonIfNeeded(source: string) {
 
 export async function GET(req: Request) {
   const endPerf = perf.start('api', 'GET /api/chats')
+  try {
+    const { pruneThreadConnectorMirrors } = await import('@/lib/server/connectors/session-consolidation')
+    pruneThreadConnectorMirrors()
+  } catch (err) {
+    console.error('[api/chats] pruneThreadConnectorMirrors failed:', err)
+  }
   const sessions = loadSessions()
   const changedSessionIds: string[] = []
   for (const id of Object.keys(sessions)) {
@@ -105,8 +112,10 @@ export async function POST(req: Request) {
     preferredGatewayTags: routePreferredGatewayTags,
     preferredGatewayUseCase: routePreferredGatewayUseCase,
   }) : null
-  const requestedPlugins = Array.isArray(body.plugins) ? body.plugins : (Array.isArray(body.tools) ? body.tools : null)
-  const resolvedPlugins = requestedPlugins ?? (Array.isArray(agent?.plugins) ? agent.plugins : (Array.isArray(agent?.tools) ? agent.tools : []))
+  const resolvedCapabilities = normalizeCapabilitySelection({
+    tools: Array.isArray(body.tools) ? body.tools : agent?.tools,
+    extensions: Array.isArray(body.extensions) ? body.extensions : agent?.extensions,
+  })
 
   // If session with this ID already exists, return it as-is
   if (body.id && sessions[id]) {
@@ -142,7 +151,8 @@ export async function POST(req: Request) {
     sessionType: body.sessionType || 'human',
     agentId: body.agentId || null,
     parentSessionId: body.parentSessionId || null,
-    plugins: resolvedPlugins,
+    tools: resolvedCapabilities.tools,
+    extensions: resolvedCapabilities.extensions,
     heartbeatEnabled: body.heartbeatEnabled ?? null,
     heartbeatIntervalSec: body.heartbeatIntervalSec ?? null,
     sessionResetMode: body.sessionResetMode ?? agent?.sessionResetMode ?? null,

package/src/app/api/clawhub/install/route.test.ts

@@ -0,0 +1,97 @@
+import assert from 'node:assert/strict'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+import test from 'node:test'
+
+const repoRoot = path.resolve(path.dirname(new URL(import.meta.url).pathname), '../../../../..')
+
+function runWithTempDataDir(script: string) {
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-clawhub-install-route-'))
+  try {
+    const result = spawnSync(process.execPath, ['--import', 'tsx', '--input-type=module', '--eval', script], {
+      cwd: repoRoot,
+      env: {
+        ...process.env,
+        DATA_DIR: path.join(tempDir, 'data'),
+        WORKSPACE_DIR: path.join(tempDir, 'workspace'),
+        SWARMCLAW_HOME: path.join(tempDir, 'swarmclaw-home'),
+      },
+      encoding: 'utf-8',
+    })
+    assert.equal(result.status, 0, result.stderr || result.stdout || 'subprocess failed')
+    const lines = (result.stdout || '')
+      .trim()
+      .split('\n')
+      .map((line) => line.trim())
+      .filter(Boolean)
+    const jsonLine = [...lines].reverse().find((line) => line.startsWith('{'))
+    return JSON.parse(jsonLine || '{}')
+  } finally {
+    fs.rmSync(tempDir, { recursive: true, force: true })
+  }
+}
+
+test('POST /api/clawhub/install materializes bundle files into the workspace skills directory', () => {
+  const output = runWithTempDataDir(`
+    const fs = await import('node:fs')
+    const path = await import('node:path')
+    const JSZip = (await import('jszip')).default
+    const storageMod = await import('./src/lib/server/storage')
+    const routeMod = await import('./src/app/api/clawhub/install/route')
+    const storage = storageMod.default || storageMod
+    const route = routeMod.default || routeMod
+
+    const archive = new JSZip()
+    archive.file('SKILL.md', \`---
+name: test-hub-skill
+description: A ClawHub test skill.
+---
+
+# Test Hub Skill
+
+Use this skill when the user asks for a ClawHub installation test.
+\`)
+    archive.file('scripts/run.sh', '#!/bin/sh\\necho hi\\n')
+    archive.file('references/notes.md', '# Notes\\n')
+    const zipBuffer = await archive.generateAsync({ type: 'nodebuffer' })
+
+    globalThis.fetch = async () => new Response(zipBuffer, {
+      status: 200,
+      headers: { 'content-type': 'application/zip' },
+    })
+
+    const response = await route.POST(new Request('http://local/api/clawhub/install', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({
+        name: 'test-hub-skill',
+        description: 'A ClawHub test skill.',
+        url: 'https://clawhub.ai/skills/test-hub-skill',
+        author: 'ClawHub',
+        tags: ['test'],
+      }),
+    }))
+    const payload = await response.json()
+    const skillsDir = path.join(process.env.SWARMCLAW_HOME, 'skills', 'test-hub-skill')
+    const storedSkills = storage.loadSkills()
+    const stored = Object.values(storedSkills).find((skill) => skill.name === 'test-hub-skill')
+
+    console.log(JSON.stringify({
+      status: response.status,
+      installedName: payload?.name || null,
+      storedSkillId: stored?.id || null,
+      hasWorkspaceSkill: fs.existsSync(path.join(skillsDir, 'SKILL.md')),
+      hasWorkspaceScript: fs.existsSync(path.join(skillsDir, 'scripts', 'run.sh')),
+      hasWorkspaceReference: fs.existsSync(path.join(skillsDir, 'references', 'notes.md')),
+    }))
+  `)
+
+  assert.equal(output.status, 200)
+  assert.equal(output.installedName, 'test-hub-skill')
+  assert.notEqual(output.storedSkillId, null)
+  assert.equal(output.hasWorkspaceSkill, true)
+  assert.equal(output.hasWorkspaceScript, true)
+  assert.equal(output.hasWorkspaceReference, true)
+})

package/src/app/api/clawhub/install/route.ts

@@ -1,9 +1,74 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
 import { NextResponse } from 'next/server'
 import { genId } from '@/lib/id'
 import { loadSkills, saveSkills } from '@/lib/server/storage'
-import { fetchSkillContent } from '@/lib/server/skills/clawhub-client'
+import type { ClawHubSkillBundle } from '@/lib/server/skills/clawhub-client'
+import { fetchClawHubSkillBundle, fetchSkillContent } from '@/lib/server/skills/clawhub-client'
+import { clearDiscoveredSkillsCache, resolveWorkspaceSkillsDir } from '@/lib/server/skills/skill-discovery'
 import { normalizeSkillPayload } from '@/lib/server/skills/skills-normalize'
 
+function sanitizeSkillDirName(value: string): string {
+  return value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 80) || 'skill'
+}
+
+function normalizeBundlePath(filePath: string): string | null {
+  const normalized = path.posix.normalize(filePath).replace(/^(\.\.(\/|\\|$))+/, '')
+  if (!normalized || normalized === '.' || normalized.startsWith('/') || normalized.includes('\0')) return null
+  return normalized
+}
+
+function stripSharedTopLevelDir(paths: string[]): string[] {
+  const splitPaths = paths.map((filePath) => filePath.split('/').filter(Boolean))
+  const sharedRoot = splitPaths[0]?.[0]
+  if (!sharedRoot) return paths
+  const shouldStrip = splitPaths.every((parts) => parts.length > 1 && parts[0] === sharedRoot)
+  return shouldStrip
+    ? splitPaths.map((parts) => parts.slice(1).join('/'))
+    : paths
+}
+
+async function materializeClawHubBundle(url: string): Promise<string | null> {
+  const bundle = await fetchClawHubSkillBundle(url)
+  if (!bundle) return null
+  await writeClawHubBundleToWorkspace(bundle)
+  return bundle.content
+}
+
+async function writeClawHubBundleToWorkspace(bundle: ClawHubSkillBundle): Promise<void> {
+  const normalizedEntries = bundle.files
+    .map((file) => ({
+      file,
+      path: normalizeBundlePath(file.path),
+    }))
+    .filter((entry): entry is { file: ClawHubSkillBundle['files'][number], path: string } => Boolean(entry.path))
+
+  const workspaceSkillsDir = resolveWorkspaceSkillsDir()
+  const targetDir = path.join(workspaceSkillsDir, sanitizeSkillDirName(bundle.slug))
+  const normalizedPaths = stripSharedTopLevelDir(normalizedEntries.map((entry) => entry.path))
+
+  await fs.rm(targetDir, { recursive: true, force: true })
+  await fs.mkdir(targetDir, { recursive: true })
+
+  for (let index = 0; index < normalizedEntries.length; index += 1) {
+    const relativePath = normalizedPaths[index]
+    if (!relativePath) continue
+    const destination = path.join(targetDir, relativePath)
+    if (!destination.startsWith(targetDir + path.sep) && destination !== targetDir) {
+      throw new Error(`Refusing to write bundle file outside the target directory: ${relativePath}`)
+    }
+    await fs.mkdir(path.dirname(destination), { recursive: true })
+    await fs.writeFile(destination, normalizedEntries[index].file.content)
+  }
+
+  clearDiscoveredSkillsCache()
+}
+
 export async function POST(req: Request) {
   const body = await req.json()
   const { name, description, url, author, tags } = body
@@ -11,7 +76,7 @@ export async function POST(req: Request) {
 
   if (!content) {
     try {
-      content = await fetchSkillContent(url)
+      content = await materializeClawHubBundle(url) || await fetchSkillContent(url)
     } catch (err: unknown) {
       return NextResponse.json(
         { error: err instanceof Error ? err.message : 'Failed to fetch skill content' },
@@ -30,8 +95,14 @@ export async function POST(req: Request) {
   })
 
   const skills = loadSkills()
-  const id = genId()
+  const duplicate = Object.values(skills).find((skill) => {
+    const left = (skill.skillKey || skill.name || '').trim().toLowerCase()
+    const right = (normalized.skillKey || normalized.name || '').trim().toLowerCase()
+    return left && right && left === right
+  })
+  const id = duplicate?.id || genId()
   skills[id] = {
+    ...(duplicate || {}),
     id,
     name: normalized.name,
     filename: normalized.filename || `skill-${id}.md`,
@@ -52,10 +123,13 @@ export async function POST(req: Request) {
     skillRequirements: normalized.skillRequirements,
     detectedEnvVars: normalized.detectedEnvVars,
     security: normalized.security,
+    invocation: normalized.invocation,
+    commandDispatch: normalized.commandDispatch,
     frontmatter: normalized.frontmatter,
-    createdAt: Date.now(),
+    createdAt: duplicate?.createdAt || Date.now(),
     updatedAt: Date.now(),
   }
   saveSkills(skills)
+  clearDiscoveredSkillsCache()
   return NextResponse.json(skills[id])
 }