@swarmclawai/swarmclaw 1.3.0 → 1.3.1

package/README.md

@@ -204,6 +204,14 @@ Read the full setup guide in [`SWARMDOCK.md`](./SWARMDOCK.md), browse the public
 
 ## Release Notes
 
+### v1.3.1 Highlights
+
+- **SwarmDock SDK v0.2.3**: upgraded marketplace integration with typed error handling, escrow state tracking, task invitation support for private tasks, and required example prompts for skill registration.
+- **SDK error resilience**: registration now gracefully handles already-registered agents by falling back to authentication; heartbeat catches expired tokens and re-authenticates automatically.
+- **Escrow event tracking**: new `escrow.releasing`, `escrow.refunding`, `escrow.release_failed`, and `escrow.refund_failed` SSE events are logged as activity entries, with failure events surfaced as incidents.
+- **Private task invitations**: when a SwarmDock task invites this agent directly, auto-discovery now evaluates it alongside public `task.created` events.
+- **SDK type imports**: replaced inlined SwarmDock type stubs with proper imports from `@swarmdock/shared`, eliminating type drift.
+
 ### v1.3.0 Highlights
 
 - **SwarmDock SDK v0.2.0**: upgraded marketplace integration to handle the new task lifecycle — `review` and `disputed` states are now tracked on board tasks, skill registration supports `inputModes`/`outputModes`, task submission accepts `notes`, and connector config supports `paymentPrivateKey` for on-chain payment signing.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmclawai/swarmclaw",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "Self-hosted AI runtime for OpenClaw, delegation, autonomy, runtime skills, crypto wallets, and chat platform connectors.",
   "license": "MIT",
   "publishConfig": {
@@ -87,7 +87,7 @@
     "@multiavatar/multiavatar": "^1.0.7",
     "@playwright/mcp": "^0.0.68",
     "@slack/bolt": "^4.6.0",
-    "@swarmdock/sdk": "^0.2.0",
+    "@swarmdock/sdk": "^0.2.3",
     "@tailwindcss/postcss": "^4",
     "@tanstack/react-query": "^5.91.0",
     "@types/better-sqlite3": "^7.6.13",

package/src/lib/server/connectors/swarmdock-bidding.ts

@@ -1,15 +1,8 @@
 import { log } from '@/lib/server/logger'
-import type { BidCreateInput } from '@swarmdock/shared'
+import type { Task, BidCreateInput } from '@swarmdock/shared'
 
 const TAG = 'swarmdock-bid'
 
-interface SwarmDockTask {
-  id: string
-  title: string
-  skillRequirements: string[]
-  budgetMax: string
-}
-
 interface SwarmDockConfig {
   skills: string
   maxBudget: string
@@ -20,7 +13,7 @@ interface SwarmDockConfig {
  * Determine if the agent should auto-bid on a discovered task.
  * Checks skill overlap and budget limits.
  */
-export function shouldAutoBid(task: SwarmDockTask, config: SwarmDockConfig): boolean {
+export function shouldAutoBid(task: Task, config: SwarmDockConfig): boolean {
   if (!config.autoDiscover) return false
 
   // Check budget

package/src/lib/server/connectors/swarmdock-payloads.test.ts

@@ -2,7 +2,7 @@ import assert from 'node:assert/strict'
 import test from 'node:test'
 
 import { submitAutoBid } from '@/lib/server/connectors/swarmdock-bidding'
-import { submitSwarmdockTaskResult } from '@/lib/server/connectors/swarmdock'
+import { submitSwarmdockTaskResult, generateExamplePrompts } from '@/lib/server/connectors/swarmdock'
 
 test('submitAutoBid includes empty portfolio refs for SDK compatibility', async () => {
   const seen: {
@@ -37,6 +37,23 @@ test('submitAutoBid includes empty portfolio refs for SDK compatibility', async
   })
 })
 
+test('generateExamplePrompts returns exactly 5 non-empty strings', () => {
+  const prompts = generateExamplePrompts('data-analysis')
+  assert.equal(prompts.length, 5)
+  for (const prompt of prompts) {
+    assert.equal(typeof prompt, 'string')
+    assert.ok(prompt.length > 0, 'prompt must be non-empty')
+    assert.ok(prompt.includes('data analysis'), 'prompt should include the humanized skill name')
+  }
+
+  // Single-word skill
+  const simple = generateExamplePrompts('coding')
+  assert.equal(simple.length, 5)
+  for (const prompt of simple) {
+    assert.ok(prompt.includes('coding'))
+  }
+})
+
 test('submitSwarmdockTaskResult includes empty files and propagates submit errors', async () => {
   const seen: {
     taskId?: string

package/src/lib/server/connectors/swarmdock-tasks.ts

@@ -2,23 +2,14 @@ import { genId } from '@/lib/id'
 import { loadTasks, saveTasks } from '@/lib/server/tasks/task-repository'
 import { logActivity } from '@/lib/server/activity/activity-log'
 import type { BoardTask } from '@/types/task'
-
-interface SwarmDockTask {
-  id: string
-  requesterId: string
-  title: string
-  description: string
-  skillRequirements: string[]
-  budgetMax: string
-  deadline: string | null
-}
+import type { Task } from '@swarmdock/shared'
 
 /**
  * Create a SwarmClaw BoardTask from a SwarmDock task assignment.
  * Uses `externalSource` to link back to the SwarmDock task (same pattern as GitHub issue import).
  */
 export async function createBoardTaskFromAssignment(
-  task: SwarmDockTask,
+  task: Task,
   agentId: string,
   connectorId: string,
   apiUrl: string,

package/src/lib/server/connectors/swarmdock.ts

@@ -5,29 +5,10 @@ import type { Connector, InboundMessage } from '@/types/connector'
 import type { PlatformConnector, ConnectorInstance } from '@/lib/server/connectors/types'
 import { createBoardTaskFromAssignment, updateBoardTaskFromEvent, findBoardTaskBySwarmdockId } from './swarmdock-tasks'
 import { shouldAutoBid, submitAutoBid } from './swarmdock-bidding'
-import type { TaskSubmitInput } from '@swarmdock/shared'
+import type { Task, SSEEvent, TaskSubmitInput } from '@swarmdock/shared'
 
 const TAG = 'swarmdock'
 
-// SDK types inlined until @swarmdock/sdk is built and linked
-interface SwarmDockTask {
-  id: string
-  requesterId: string
-  assigneeId: string | null
-  title: string
-  description: string
-  skillRequirements: string[]
-  budgetMax: string
-  status: string
-  deadline: string | null
-}
-
-interface SwarmDockSSEEvent {
-  type: string
-  data: Record<string, unknown>
-  timestamp: string
-}
-
 interface SwarmDockConfig {
   apiUrl: string
   walletAddress: string
@@ -51,7 +32,7 @@ function parseConfig(connector: Connector): SwarmDockConfig {
   }
 }
 
-function buildTaskPrompt(task: SwarmDockTask): string {
+function buildTaskPrompt(task: Task): string {
   const lines: string[] = [
     `# SwarmDock Task: ${task.title}`,
     '',
@@ -65,6 +46,17 @@ function buildTaskPrompt(task: SwarmDockTask): string {
   return lines.join('\n')
 }
 
+export function generateExamplePrompts(skillId: string): string[] {
+  const name = skillId.replace(/-/g, ' ')
+  return [
+    `Perform a ${name} task`,
+    `Help me with ${name}`,
+    `I need ${name} work done`,
+    `Complete a ${name} assignment`,
+    `Handle a ${name} request`,
+  ]
+}
+
 function formatUsdc(microUnits: string): string {
   const cents = BigInt(microUnits)
   const dollars = Number(cents) / 1_000_000
@@ -98,11 +90,15 @@ const swarmdock: PlatformConnector = {
     if (!privateKey) throw new Error('SwarmDock connector requires an Ed25519 private key credential')
     if (!config.walletAddress) throw new Error('SwarmDock connector requires a Base L2 wallet address in config')
 
-    // Dynamic import of the SDK (must be built and linked first)
+    // Dynamic import of the SDK
     let SwarmDockClient: typeof import('@swarmdock/sdk').SwarmDockClient
+    let ConflictError: typeof import('@swarmdock/sdk').ConflictError
+    let AuthenticationError: typeof import('@swarmdock/sdk').AuthenticationError
     try {
       const sdk = await import('@swarmdock/sdk')
       SwarmDockClient = sdk.SwarmDockClient
+      ConflictError = sdk.ConflictError
+      AuthenticationError = sdk.AuthenticationError
     } catch {
       throw new Error('SwarmDock SDK (@swarmdock/sdk) is not installed. Run: npm install @swarmdock/sdk')
     }
@@ -128,36 +124,47 @@ const swarmdock: PlatformConnector = {
         basePrice: '1000000', // $1.00 default
         inputModes: ['text'],
         outputModes: ['text'],
+        examplePrompts: generateExamplePrompts(skillId),
       }))
 
     log.info(TAG, `Registering agent "${connector.name}" on SwarmDock at ${config.apiUrl}`)
-    const registration = await client.register({
-      displayName: connector.name,
-      description: config.agentDescription,
-      framework: 'swarmclaw',
-      walletAddress: config.walletAddress,
-      skills: skillList,
-    })
-    log.info(TAG, `Registered as ${registration.agent.did} (trust level ${registration.agent.trustLevel})`)
-
-    logActivity({
-      entityType: 'connector',
-      entityId: connectorId,
-      action: 'swarmdock-registered',
-      actor: 'system',
-      summary: `Agent "${connector.name}" registered on SwarmDock as ${registration.agent.did}`,
-    })
+    try {
+      const registration = await client.register({
+        displayName: connector.name,
+        description: config.agentDescription,
+        framework: 'swarmclaw',
+        walletAddress: config.walletAddress,
+        skills: skillList,
+      })
+      log.info(TAG, `Registered as ${registration.agent.did} (trust level ${registration.agent.trustLevel})`)
+
+      logActivity({
+        entityType: 'connector',
+        entityId: connectorId,
+        action: 'swarmdock-registered',
+        actor: 'system',
+        summary: `Agent "${connector.name}" registered on SwarmDock as ${registration.agent.did}`,
+      })
+    } catch (err) {
+      if (err instanceof ConflictError) {
+        log.info(TAG, `Agent already registered, authenticating`)
+        await client.authenticate()
+      } else {
+        throw err
+      }
+    }
 
     // Set up SSE event stream
     let alive = true
 
-    const handleSSEEvent = async (event: SwarmDockSSEEvent) => {
+    const handleSSEEvent = async (event: SSEEvent) => {
       if (!alive) return
       try {
         switch (event.type) {
-          case 'task.created': {
+          case 'task.created':
+          case 'task.invited': {
             if (!config.autoDiscover) break
-            const task = event.data as unknown as SwarmDockTask
+            const task = event.data as unknown as Task
             if (shouldAutoBid(task, config)) {
               await submitAutoBid(client, task.id, config)
               logActivity({
@@ -172,7 +179,7 @@ const swarmdock: PlatformConnector = {
           }
 
           case 'task.assigned': {
-            const task = event.data as unknown as SwarmDockTask
+            const task = event.data as unknown as Task
             if (!task.assigneeId) break
 
             // Signal work started on SwarmDock
@@ -236,6 +243,32 @@ const swarmdock: PlatformConnector = {
             })
             break
           }
+
+          case 'escrow.releasing':
+          case 'escrow.refunding': {
+            const data = event.data as Record<string, string>
+            logActivity({
+              entityType: 'connector',
+              entityId: connectorId,
+              action: 'swarmdock-escrow',
+              actor: 'system',
+              summary: `Escrow ${event.type.split('.')[1]} for task ${data.taskId}`,
+            })
+            break
+          }
+
+          case 'escrow.release_failed':
+          case 'escrow.refund_failed': {
+            const data = event.data as Record<string, string>
+            logActivity({
+              entityType: 'connector',
+              entityId: connectorId,
+              action: 'incident',
+              actor: 'system',
+              summary: `Escrow ${event.type.replace('escrow.', '')} for task ${data.taskId}`,
+            })
+            break
+          }
         }
       } catch (err) {
         log.error(TAG, `Error handling SSE event ${event.type}: ${err instanceof Error ? err.message : String(err)}`)
@@ -250,7 +283,12 @@ const swarmdock: PlatformConnector = {
         await client.heartbeat()
         log.debug(TAG, 'SwarmDock token refreshed')
       } catch (err) {
-        log.error(TAG, `SwarmDock heartbeat failed: ${err instanceof Error ? err.message : String(err)}`)
+        if (err instanceof AuthenticationError) {
+          log.warn(TAG, 'SwarmDock token expired, re-authenticating')
+          try { await client.authenticate() } catch {}
+        } else {
+          log.error(TAG, `SwarmDock heartbeat failed: ${err instanceof Error ? err.message : String(err)}`)
+        }
       }
     }, 23 * 60 * 60 * 1000)