@swarmclawai/swarmclaw 0.7.3 → 0.7.5

package/src/lib/server/session-tools/file.ts

@@ -58,7 +58,7 @@ function inferFileAction(
   if (getFileEntryContent(normalized) !== undefined) return 'write'
   if (dirPath) return 'list'
   if (filePath) return 'read'
-  return undefined
+  return 'list'
 }
 
 export function normalizeFileArgs(rawArgs: Record<string, unknown>): Record<string, unknown> {
@@ -417,7 +417,13 @@ const FilePlugin: Plugin = {
   name: 'Core Files',
   description: 'Complete file management: read, write, list, move, copy, delete, and send.',
   hooks: {
-    getCapabilityDescription: () => 'I can read, write, copy, move, and send files (`read_file`, `write_file`, `list_files`, `copy_file`, `move_file`, `send_file`). When writing, I should always provide a target path (`filePath`, `path`, `filename`, or `name`) and the content (`content`, `text`, or `body`). When `send_file` returns a download link, I should copy that link exactly instead of rewriting it. Deleting files is destructive, so that may need explicit permission.',
+    getCapabilityDescription: () => 'I can manage files with the unified `files` tool (actions: `read`, `write`, `list`, `copy`, `move`, `delete`) and deliver finished artifacts with `send_file`.',
+    getOperatingGuidance: () => [
+      'The `files` tool always works best with an explicit action. Use `{"action":"list","dirPath":"."}` to inspect the workspace, `{"action":"read","filePath":"path/to/file.md"}` to inspect a file, and `{"action":"write","files":[{"path":"path/to/file.md","content":"..."}]}` to create or overwrite content.',
+      'For follow-up revision requests, read the current file first, then overwrite it with the improved version or use `edit_file` for a surgical change.',
+      'If a `files` call fails, correct the arguments and retry. Do not conclude that the workspace is inaccessible until an explicit read/list/write attempt with a path fails.',
+      'When `send_file` returns a download link, copy that link exactly instead of rewriting it.',
+    ],
   } as PluginHooks,
   tools: [
     {

package/src/lib/server/session-tools/http.ts

@@ -68,12 +68,18 @@ async function executeHttpAction(args: HttpRequestArgs) {
  */
 const HttpPlugin: Plugin = {
   name: 'Core HTTP',
-  description: 'Make direct HTTP API calls with custom methods, headers, and bodies.',
-  hooks: {} as PluginHooks,
+  description: 'Make direct HTTP API calls without generating throwaway code.',
+  hooks: {
+    getCapabilityDescription: () => 'I can make direct HTTP requests (`http_request`) without writing code. Use this for straightforward API calls or fetching JSON.',
+    getOperatingGuidance: () => [
+      'Prefer `http_request` over `sandbox_exec` for straightforward REST or JSON API calls.',
+      'Keep API keys in plugin settings or SwarmClaw secrets instead of hardcoding them in generated code.',
+    ],
+  } as PluginHooks,
   tools: [
     {
       name: 'http_request',
-      description: 'Make an HTTP API request.',
+      description: 'Make an HTTP API request without generating code.',
       parameters: {
         type: 'object',
         properties: {

package/src/lib/server/session-tools/index.ts

@@ -25,6 +25,7 @@ import { buildWalletTools } from './wallet'
 import { buildOpenClawWorkspaceTools } from './openclaw-workspace'
 import { buildScheduleTools } from './schedule'
 import { buildPlatformTools } from './platform'
+import { buildCrudTools } from './crud'
 import { buildSessionInfoTools } from './session-info'
 import { buildOpenClawNodeTools } from './openclaw-nodes'
 import { buildContextTools } from './context-mgmt'
@@ -179,6 +180,12 @@ export async function buildSessionTools(cwd: string, enabledPlugins: string[], c
       tools.push(...builtTools)
     }
 
+    const crudTools = buildCrudTools(bctx)
+    for (const toolEntry of crudTools) {
+      toolToPluginMap[toolEntry.name] = toolEntry.name
+    }
+    tools.push(...crudTools)
+
     // 2. Build Plugin Tools (Built-in + External)
     try {
       const pluginTools = pluginManager.getTools(activePlugins)
@@ -266,11 +273,34 @@ export async function buildSessionTools(cwd: string, enabledPlugins: string[], c
           const normalized = normalizeToolInputArgs((args ?? {}) as Record<string, unknown>)
           const toolId = normalized.toolId as string | undefined
           const reason = normalized.reason as string | undefined
+          if (!toolId?.trim()) {
+            return JSON.stringify({
+              error: 'toolId is required',
+              message: 'Specify the exact plugin ID to request access for.',
+            })
+          }
+          const { requestApprovalMaybeAutoApprove } = await import('../approvals')
+          const approval = await requestApprovalMaybeAutoApprove({
+            category: 'tool_access',
+            title: `Enable Plugin: ${toolId}`,
+            description: reason || `Agent is requesting access to "${toolId}".`,
+            data: { toolId, pluginId: toolId, reason: reason || '' },
+            agentId: ctx?.agentId,
+            sessionId: ctx?.sessionId,
+          })
+          if (approval.status === 'approved') {
+            return JSON.stringify({
+              type: 'tool_request',
+              toolId,
+              autoApproved: true,
+              message: `Tool access for "${toolId}" was granted. Proceed to use it directly.`,
+            })
+          }
           return JSON.stringify({
             type: 'tool_request',
             toolId,
             reason,
-            message: `Tool access request sent to user for "${toolId}". The user will be prompted to grant access — once granted, a follow-up message will arrive and you should immediately proceed with the original task using the newly available tool.`,
+            message: `Tool access request sent to user for "${toolId}". Once granted, continue immediately with the original task using the newly available tool.`,
           })
         },
         {

package/src/lib/server/session-tools/manage-schedules.test.ts

@@ -0,0 +1,137 @@
+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 { describe, it } 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-schedule-tool-'))
+  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'),
+      },
+      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 })
+  }
+}
+
+describe('manage_schedules tool', () => {
+  it('defaults schedules to the current agent and derives a runnable taskPrompt from run_script payloads', () => {
+    const output = runWithTempDataDir(`
+      import fs from 'node:fs'
+      import path from 'node:path'
+      const storageMod = await import('./src/lib/server/storage.ts')
+      const crudMod = await import('./src/lib/server/session-tools/crud.ts')
+      const storage = storageMod.default || storageMod
+      const crud = crudMod.default || crudMod
+
+      const now = Date.now()
+      storage.saveAgents({
+        default: {
+          id: 'default',
+          name: 'Molly',
+          description: '',
+          systemPrompt: '',
+          provider: 'openai',
+          model: 'gpt-test',
+          createdAt: now,
+          updatedAt: now,
+        },
+      })
+
+      const cwd = process.env.WORKSPACE_DIR
+      fs.mkdirSync(path.join(cwd, 'weather_workspace'), { recursive: true })
+      fs.writeFileSync(path.join(cwd, 'weather_workspace', 'weather_fetch.py'), 'print("weather")\\n')
+
+      const tools = crud.buildCrudTools({
+        cwd,
+        ctx: { sessionId: 'session-1', agentId: 'default', platformAssignScope: 'self' },
+        hasPlugin: (name) => name === 'manage_schedules',
+      })
+      const tool = tools.find((entry) => entry.name === 'manage_schedules')
+      const raw = await tool.invoke({
+        action: 'create',
+        data: JSON.stringify({
+          name: 'Daily Weather Update',
+          scheduleType: 'interval',
+          intervalMs: 60000,
+          action: 'run_script',
+          path: 'weather_workspace/weather_fetch.py',
+        }),
+      })
+
+      const schedule = Object.values(storage.loadSchedules())[0]
+      console.log(JSON.stringify({
+        raw,
+        schedule,
+      }))
+    `)
+
+    assert.equal(output.schedule.agentId, 'default')
+    assert.equal(output.schedule.path, 'weather_workspace/weather_fetch.py')
+    assert.match(output.schedule.taskPrompt, /weather_workspace\/weather_fetch\.py/)
+    assert.equal(output.schedule.status, 'active')
+    assert.equal(typeof output.schedule.nextRunAt, 'number')
+  })
+
+  it('rejects schedules whose referenced script path does not exist', () => {
+    const output = runWithTempDataDir(`
+      const storageMod = await import('./src/lib/server/storage.ts')
+      const crudMod = await import('./src/lib/server/session-tools/crud.ts')
+      const storage = storageMod.default || storageMod
+      const crud = crudMod.default || crudMod
+
+      const now = Date.now()
+      storage.saveAgents({
+        default: {
+          id: 'default',
+          name: 'Molly',
+          description: '',
+          systemPrompt: '',
+          provider: 'openai',
+          model: 'gpt-test',
+          createdAt: now,
+          updatedAt: now,
+        },
+      })
+
+      const tools = crud.buildCrudTools({
+        cwd: process.env.WORKSPACE_DIR,
+        ctx: { sessionId: 'session-2', agentId: 'default', platformAssignScope: 'self' },
+        hasPlugin: (name) => name === 'manage_schedules',
+      })
+      const tool = tools.find((entry) => entry.name === 'manage_schedules')
+      const raw = await tool.invoke({
+        action: 'create',
+        data: JSON.stringify({
+          name: 'Broken Weather Update',
+          scheduleType: 'interval',
+          intervalMs: 60000,
+          action: 'run_script',
+          path: 'weather_workspace/missing.py',
+        }),
+      })
+
+      console.log(JSON.stringify({ raw }))
+    `)
+
+    assert.match(String(output.raw), /schedule path not found: weather_workspace\/missing\.py/i)
+  })
+})

package/src/lib/server/session-tools/monitor.ts

@@ -1,7 +1,6 @@
 import { z } from 'zod'
 import { tool, type StructuredToolInterface } from '@langchain/core/tools'
 import fs from 'fs'
-import path from 'path'
 import * as os from 'os'
 import type { ToolBuildContext } from './context'
 import { getPluginManager } from '../plugins'
@@ -89,17 +88,25 @@ async function createDurableWatch(
   return JSON.stringify(job, null, 2)
 }
 
+function getErrorMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err)
+}
+
 /**
  * Unified Monitoring Logic
  */
-async function executeMonitorAction(args: any, bctx: { cwd: string; sessionId?: string; agentId?: string | null }) {
+async function executeMonitorAction(
+  args: Record<string, unknown> | undefined,
+  bctx: { cwd: string; sessionId?: string; agentId?: string | null },
+) {
   const normalized = normalizeToolInputArgs((args ?? {}) as Record<string, unknown>)
   const action = normalized.action as string | undefined
   const target = (normalized.target ?? normalized.url ?? normalized.path) as string | undefined
   const limit = normalized.limit as number | undefined
   const threshold = normalized.threshold as number | undefined
   const sessionId = typeof normalized.sessionId === 'string' ? normalized.sessionId : bctx.sessionId
-  const agentId = typeof normalized.agentId === 'string' ? normalized.agentId : (bctx.agentId || undefined)
+  void limit
+  void sessionId
 
   try {
     switch (action) {
@@ -150,10 +157,10 @@ async function executeMonitorAction(args: any, bctx: { cwd: string; sessionId?:
             thresholdExceeded: typeof threshold === 'number' ? latency >= threshold : undefined,
             url
           }, null, 2)
-        } catch (err: any) {
+        } catch (err: unknown) {
           return JSON.stringify({
             status: 'error',
-            error: err.message,
+            error: getErrorMessage(err),
             url
           }, null, 2)
         }
@@ -211,8 +218,8 @@ async function executeMonitorAction(args: any, bctx: { cwd: string; sessionId?:
       default:
         return `Error: Unknown action "${action}"`
     }
-  } catch (err: any) {
-    return `Error: ${err.message}`
+  } catch (err: unknown) {
+    return `Error: ${getErrorMessage(err)}`
   }
 }
 

package/src/lib/server/session-tools/openclaw-nodes.test.ts

@@ -0,0 +1,111 @@
+import assert from 'node:assert/strict'
+import { test } from 'node:test'
+import { executeNodesAction } from './openclaw-nodes'
+import type { OpenClawGateway } from '../openclaw-gateway'
+
+test('executeNodesAction returns not_connected when no gateway is available', async () => {
+  const raw = await executeNodesAction(
+    { action: 'list', profileId: 'gateway-1' },
+    { ensureGatewayConnected: async () => null },
+  )
+  const result = JSON.parse(raw)
+  assert.equal(result.status, 'not_connected')
+  assert.match(result.message, /gateway not connected/i)
+})
+
+test('executeNodesAction lists nodes against the selected gateway profile', async () => {
+  const calls: Array<{ method: string; params: unknown }> = []
+  const gateway = {
+    rpc: async (method: string, params?: unknown) => {
+      calls.push({ method, params })
+      return { ts: 1, nodes: [{ nodeId: 'node-1' }] }
+    },
+  }
+
+  const raw = await executeNodesAction(
+    { action: 'list', profileId: 'gateway-1' },
+    { ensureGatewayConnected: async () => gateway as unknown as OpenClawGateway },
+  )
+  const result = JSON.parse(raw)
+  assert.equal(result.status, 'ok')
+  assert.equal(calls[0]?.method, 'node.list')
+  assert.deepEqual(calls[0]?.params, { profileId: 'gateway-1' })
+  assert.equal(result.result.nodes[0].nodeId, 'node-1')
+})
+
+test('executeNodesAction aggregates node and device pairings', async () => {
+  const calls: string[] = []
+  const gateway = {
+    rpc: async (method: string) => {
+      calls.push(method)
+      if (method === 'node.pair.list') return { pending: [{ requestId: 'node-req-1' }] }
+      if (method === 'device.pair.list') return { pending: [{ requestId: 'device-req-1' }], paired: [{ deviceId: 'device-1' }] }
+      throw new Error(`Unexpected RPC ${method}`)
+    },
+  }
+
+  const raw = await executeNodesAction(
+    { action: 'pairings', profileId: 'gateway-1' },
+    { ensureGatewayConnected: async () => gateway as unknown as OpenClawGateway },
+  )
+  const result = JSON.parse(raw)
+  assert.equal(result.status, 'ok')
+  assert.deepEqual(calls, ['node.pair.list', 'device.pair.list'])
+  assert.equal(result.result.nodePairings.pending[0].requestId, 'node-req-1')
+  assert.equal(result.result.devicePairings.paired[0].deviceId, 'device-1')
+})
+
+test('executeNodesAction routes device pairing approvals to the device RPC surface', async () => {
+  const calls: Array<{ method: string; params: unknown }> = []
+  const gateway = {
+    rpc: async (method: string, params?: unknown) => {
+      calls.push({ method, params })
+      return { ok: true }
+    },
+  }
+
+  const raw = await executeNodesAction(
+    { action: 'approve_pairing', pairingType: 'device', requestId: 'req-1', profileId: 'gateway-1' },
+    { ensureGatewayConnected: async () => gateway as unknown as OpenClawGateway },
+  )
+  const result = JSON.parse(raw)
+  assert.equal(result.status, 'ok')
+  assert.equal(calls[0]?.method, 'device.pair.approve')
+  assert.deepEqual(calls[0]?.params, { requestId: 'req-1', profileId: 'gateway-1' })
+})
+
+test('executeNodesAction forwards notify payloads through node.invoke with a generated idempotency key', async () => {
+  const calls: Array<{ method: string; params: unknown }> = []
+  const gateway = {
+    rpc: async (method: string, params?: unknown) => {
+      calls.push({ method, params })
+      return { delivered: true }
+    },
+  }
+
+  const raw = await executeNodesAction(
+    {
+      action: 'notify',
+      profileId: 'gateway-1',
+      nodeId: 'node-42',
+      message: 'hello from test',
+      params: { urgency: 'high' },
+      timeoutMs: 5000,
+    },
+    {
+      ensureGatewayConnected: async () => gateway as unknown as OpenClawGateway,
+      generateId: () => 'fixed-id',
+    },
+  )
+  const result = JSON.parse(raw)
+  assert.equal(result.status, 'ok')
+  assert.equal(calls[0]?.method, 'node.invoke')
+  assert.deepEqual(calls[0]?.params, {
+    nodeId: 'node-42',
+    command: 'notify',
+    params: { urgency: 'high', message: 'hello from test' },
+    timeoutMs: 5000,
+    idempotencyKey: 'fixed-id',
+    profileId: 'gateway-1',
+  })
+})

package/src/lib/server/session-tools/openclaw-nodes.ts

@@ -1,46 +1,105 @@
 import { z } from 'zod'
+import { randomUUID } from 'crypto'
 import { tool, type StructuredToolInterface } from '@langchain/core/tools'
 import type { ToolBuildContext } from './context'
 import type { Plugin, PluginHooks } from '@/types'
 import { getPluginManager } from '../plugins'
 import { normalizeToolInputArgs } from './normalize-tool-args'
+import { ensureGatewayConnected } from '../openclaw-gateway'
+
+interface OpenClawNodesDeps {
+  ensureGatewayConnected?: typeof ensureGatewayConnected
+  generateId?: () => string
+}
 
 /**
  * Core OpenClaw Nodes Execution Logic
  */
-async function executeNodesAction(args: any) {
+export async function executeNodesAction(args: any, deps: OpenClawNodesDeps = {}) {
   const normalized = normalizeToolInputArgs((args ?? {}) as Record<string, unknown>)
   const action = normalized.action as string | undefined
   const nodeId = (normalized.nodeId ?? normalized.node_id) as string | undefined
+  const deviceId = (normalized.deviceId ?? normalized.device_id) as string | undefined
+  const requestId = (normalized.requestId ?? normalized.request_id) as string | undefined
   const message = normalized.message as string | undefined
   const params = normalized.params as Record<string, unknown> | undefined
+  const command = (normalized.command ?? params?.command ?? params?.action) as string | undefined
+  const pairingType = typeof normalized.pairingType === 'string' ? normalized.pairingType : (typeof normalized.kind === 'string' ? normalized.kind : 'node')
+  const profileId = (normalized.profileId ?? normalized.gatewayProfileId ?? normalized.gateway_profile_id) as string | undefined
+  const agentId = (normalized.agentId ?? normalized.agent_id) as string | undefined
+  const timeoutMs = typeof normalized.timeoutMs === 'number'
+    ? normalized.timeoutMs
+    : (typeof params?.timeoutMs === 'number' ? params.timeoutMs : undefined)
+  const ensureGatewayConnectedFn = deps.ensureGatewayConnected ?? ensureGatewayConnected
+  const generateId = deps.generateId ?? randomUUID
   try {
-    const { listRunningConnectors, getRunningInstance } = await import('../connectors/manager')
-    const openclawConnectors = listRunningConnectors('openclaw')
-    if (!openclawConnectors.length) {
+    const gateway = await ensureGatewayConnectedFn({ profileId, agentId })
+    if (!gateway) {
       return JSON.stringify({
         status: 'not_connected',
-        message: 'No running OpenClaw connector found.',
-        hint: 'Start an OpenClaw connector in the Connectors panel, then retry.',
+        message: 'OpenClaw gateway not connected.',
+        hint: 'Connect an OpenClaw gateway profile in Providers, then retry.',
       })
     }
-    const inst = getRunningInstance(openclawConnectors[0].id)
-    if (!inst) {
+
+    if (action === 'list') {
+      const result = await gateway.rpc('node.list', { profileId })
+      return JSON.stringify({ status: 'ok', action, result })
+    }
+    if (action === 'describe') {
+      if (!nodeId) return JSON.stringify({ status: 'error', error: 'nodeId is required for describe.' })
+      const result = await gateway.rpc('node.describe', { nodeId, profileId })
+      return JSON.stringify({ status: 'ok', action, nodeId, result })
+    }
+    if (action === 'pairings') {
+      const [nodePairings, devicePairings] = await Promise.all([
+        gateway.rpc('node.pair.list', { profileId }),
+        gateway.rpc('device.pair.list', { profileId }),
+      ])
       return JSON.stringify({
-        status: 'not_connected',
-        message: 'OpenClaw connector instance not accessible.',
-        connectorId: openclawConnectors[0].id,
+        status: 'ok',
+        action,
+        result: {
+          nodePairings,
+          devicePairings,
+        },
       })
     }
-
-    if (action === 'list') {
-      return JSON.stringify({ status: 'nodes.list not supported on gateway yet', connectorId: openclawConnectors[0].id })
+    if (action === 'approve_pairing') {
+      if (!requestId) return JSON.stringify({ status: 'error', error: 'requestId is required for approve_pairing.' })
+      const method = pairingType === 'device' ? 'device.pair.approve' : 'node.pair.approve'
+      const result = await gateway.rpc(method, { requestId, profileId })
+      return JSON.stringify({ status: 'ok', action, pairingType, requestId, result })
+    }
+    if (action === 'reject_pairing') {
+      if (!requestId) return JSON.stringify({ status: 'error', error: 'requestId is required for reject_pairing.' })
+      const method = pairingType === 'device' ? 'device.pair.reject' : 'node.pair.reject'
+      const result = await gateway.rpc(method, { requestId, profileId })
+      return JSON.stringify({ status: 'ok', action, pairingType, requestId, result })
     }
-    if (action === 'notify') {
-      return JSON.stringify({ status: 'nodes.notify not supported on gateway yet', nodeId, message })
+    if (action === 'remove_device') {
+      if (!deviceId) return JSON.stringify({ status: 'error', error: 'deviceId is required for remove_device.' })
+      const result = await gateway.rpc('device.pair.remove', { deviceId, profileId })
+      return JSON.stringify({ status: 'ok', action, deviceId, result })
     }
-    if (action === 'invoke') {
-      return JSON.stringify({ status: 'nodes.invoke not supported on gateway yet', nodeId, invokeAction: params?.action })
+    if (action === 'notify' || action === 'invoke') {
+      if (!nodeId) return JSON.stringify({ status: 'error', error: 'nodeId is required for invoke.' })
+      const invokeCommand = typeof command === 'string' && command.trim()
+        ? command.trim()
+        : (action === 'notify' ? 'notify' : '')
+      if (!invokeCommand) return JSON.stringify({ status: 'error', error: 'command is required for invoke.' })
+      const invokeParams = action === 'notify'
+        ? { ...(params || {}), message }
+        : (params || {})
+      const result = await gateway.rpc('node.invoke', {
+        nodeId,
+        command: invokeCommand,
+        params: invokeParams,
+        timeoutMs,
+        idempotencyKey: generateId(),
+        profileId,
+      })
+      return JSON.stringify({ status: 'ok', action, nodeId, command: invokeCommand, result })
     }
 
     return JSON.stringify({ status: 'error', error: `Unknown nodes action "${action}".` })
@@ -63,10 +122,17 @@ const NodesPlugin: Plugin = {
       parameters: {
         type: 'object',
         properties: {
-          action: { type: 'string', enum: ['list', 'notify', 'invoke'] },
+          action: { type: 'string', enum: ['list', 'describe', 'pairings', 'approve_pairing', 'reject_pairing', 'remove_device', 'notify', 'invoke'] },
           nodeId: { type: 'string' },
+          deviceId: { type: 'string' },
+          requestId: { type: 'string' },
+          pairingType: { type: 'string', enum: ['node', 'device'] },
+          profileId: { type: 'string' },
+          agentId: { type: 'string' },
+          command: { type: 'string' },
           message: { type: 'string' },
-          params: { type: 'object' }
+          params: { type: 'object' },
+          timeoutMs: { type: 'number' },
         },
         required: ['action']
       },

package/src/lib/server/session-tools/platform.ts

@@ -190,7 +190,7 @@ const PlatformPlugin: Plugin = {
   tools: [
     {
       name: 'manage_platform',
-      description: 'Unified tool for managing all SwarmClaw resources. For create/update, pass resource + action, then either put fields inside data, pass them as top-level fields, or use a single resources[0].parameters envelope.',
+      description: 'Unified fallback tool for managing SwarmClaw resources when a more specific `manage_*` tool is not available. For create/update, pass resource + action, then either put fields inside data, pass them as top-level fields, or use a single resources[0].parameters envelope.',
       parameters: {
         type: 'object',
         properties: {

package/src/lib/server/session-tools/plugin-creator.ts

@@ -245,8 +245,15 @@ Key rules:
  */
 const PluginCreatorPlugin: Plugin = {
   name: 'Plugin Creator',
-  description: 'Design, write, and test custom SwarmClaw plugins dynamically.',
-  hooks: {} as PluginHooks,
+  description: 'Design focused SwarmClaw plugins for durable capabilities and recurring automations.',
+  hooks: {
+    getCapabilityDescription: () => 'I can scaffold focused plugins (`plugin_creator_tool`) when a capability should become durable instead of living in a one-off sandbox script.',
+    getOperatingGuidance: () => [
+      'For recurring or scheduled automations, prefer a focused plugin plus `manage_schedules` over repeated sandbox runs.',
+      'Put API keys in plugin settings or SwarmClaw secrets instead of hardcoding them in plugin source.',
+      'Call `get_spec` before scaffolding so the plugin follows the current contract.',
+    ],
+  } as PluginHooks,
   tools: [
     {
       name: 'plugin_creator_tool',