@swarmclawai/swarmclaw 0.7.3 → 0.7.5

package/src/lib/server/stream-agent-chat.test.ts

@@ -0,0 +1,61 @@
+import assert from 'node:assert/strict'
+import fs from 'node:fs'
+import path from 'node:path'
+import { describe, it } from 'node:test'
+import { buildToolDisciplineLines, looksLikeOpenEndedDeliverableTask } from './stream-agent-chat'
+
+const streamAgentChatSource = fs.readFileSync(path.join(path.dirname(new URL(import.meta.url).pathname), 'stream-agent-chat.ts'), 'utf-8')
+
+describe('buildToolDisciplineLines', () => {
+  it('tells the agent to use direct platform tools when manage_platform is absent', () => {
+    const lines = buildToolDisciplineLines(['files', 'manage_schedules'])
+
+    assert.equal(lines[0], 'Enabled tools in this session: `files`, `manage_schedules`.')
+    assert.ok(lines.some((line) => line.includes('Do not substitute `manage_platform`')))
+  })
+
+  it('omits the manage_platform warning when the umbrella tool is enabled', () => {
+    const lines = buildToolDisciplineLines(['manage_platform', 'manage_schedules'])
+
+    assert.ok(lines.every((line) => !line.includes('Do not substitute `manage_platform`')))
+  })
+
+  it('includes concrete files-tool examples for revision work', () => {
+    const lines = buildToolDisciplineLines(['files'])
+
+    assert.ok(lines.some((line) => line.includes('{"action":"read","filePath":"path/to/file.md"}')))
+  })
+
+  it('warns browser tasks to use literal urls and the supported form schema', () => {
+    const lines = buildToolDisciplineLines(['browser', 'http_request', 'email', 'ask_human'])
+
+    assert.ok(lines.some((line) => line.includes('Do not invent placeholder URLs')))
+    assert.ok(lines.some((line) => line.includes('A shorthand `form` object keyed by input id/name also works')))
+    assert.ok(lines.some((line) => line.includes('Keep JSON request bodies as raw JSON strings')))
+    assert.ok(lines.some((line) => line.includes('{"action":"send","to":"user@example.com","subject":"...","body":"..."}')))
+    assert.ok(lines.some((line) => line.includes('do not guess or keep re-submitting blank forms')))
+  })
+
+  it('tells the agent that named enabled tools are completion requirements', () => {
+    assert.ok(streamAgentChatSource.includes('If a task explicitly names an enabled tool, use that tool before declaring success.'))
+    assert.ok(streamAgentChatSource.includes('collect required human input through the tool'))
+    assert.ok(streamAgentChatSource.includes('You have not yet completed the required explicit tool step(s):'))
+    assert.ok(streamAgentChatSource.includes('[Loop Budget Reached]'))
+  })
+})
+
+describe('looksLikeOpenEndedDeliverableTask', () => {
+  it('detects open-ended deliverable prompts', () => {
+    assert.equal(
+      looksLikeOpenEndedDeliverableTask('Revise the landing copy and update the proposal draft with a stronger second pass.'),
+      true,
+    )
+  })
+
+  it('does not misclassify explicit coding tasks', () => {
+    assert.equal(
+      looksLikeOpenEndedDeliverableTask('Fix the React bug in src/components/chat/chat-area.tsx and run npm run build.'),
+      false,
+    )
+  })
+})

package/src/lib/server/stream-agent-chat.ts

@@ -1,6 +1,7 @@
 import fs from 'fs'
 import { createReactAgent } from '@langchain/langgraph/prebuilt'
 import { HumanMessage, AIMessage } from '@langchain/core/messages'
+import { DEFAULT_HEARTBEAT_INTERVAL_SEC } from '@/lib/heartbeat-defaults'
 import { buildSessionTools } from './session-tools'
 import { buildChatModel } from './build-llm'
 import { loadSettings, loadAgents, loadSkills, appendUsage } from './storage'
@@ -14,6 +15,7 @@ import { expandPluginIds } from './tool-aliases'
 import type { Session, Message, UsageRecord, PluginInvocationRecord } from '@/types'
 import { extractSuggestions } from './suggestions'
 import { buildIdentityContinuityContext } from './identity-continuity'
+import { enqueueSystemEvent } from './system-events'
 
 /** Extract a breadcrumb title from notable tool completions (task/schedule/agent creation). */
 interface StreamAgentChatOpts {
@@ -43,6 +45,85 @@ function buildPluginCapabilityLines(enabledPlugins: string[], opts?: { platformA
   return lines
 }
 
+export function buildToolDisciplineLines(enabledPlugins: string[]): string[] {
+  const uniqueTools = Array.from(new Set(enabledPlugins.filter(Boolean))).sort()
+  if (uniqueTools.length === 0) return []
+
+  const lines = [
+    `Enabled tools in this session: ${uniqueTools.map((toolId) => `\`${toolId}\``).join(', ')}.`,
+    'Only call tools from this enabled list or tools explicitly returned by the runtime.',
+  ]
+
+  const directPlatformTools = uniqueTools.filter((toolId) => toolId.startsWith('manage_') && toolId !== 'manage_platform')
+  if (directPlatformTools.length > 0 && !uniqueTools.includes('manage_platform')) {
+    lines.push(`Use direct platform tools exactly as named (${directPlatformTools.map((toolId) => `\`${toolId}\``).join(', ')}). Do not substitute \`manage_platform\` unless it is explicitly enabled.`)
+  }
+
+  if (uniqueTools.includes('files')) {
+    lines.push('For `files`, include an explicit action whenever possible. Common patterns: `{"action":"list","dirPath":"."}`, `{"action":"read","filePath":"path/to/file.md"}`, and `{"action":"write","files":[{"path":"path/to/file.md","content":"..."}]}`.')
+  }
+
+  if (uniqueTools.includes('shell')) {
+    lines.push('For `shell`, use `{"action":"execute","command":"..."}` for commands and `{"action":"status","processId":"..."}` or `{"action":"log","processId":"..."}` for long-lived processes.')
+  }
+
+  if (uniqueTools.includes('web')) {
+    lines.push('For `web`, use `{"action":"search","query":"..."}` to research and `{"action":"fetch","url":"https://..."}` to read a specific page.')
+  }
+
+  if (uniqueTools.includes('browser')) {
+    lines.push('For `browser`, when the task includes a literal URL, pass that exact URL string to `{"action":"navigate","url":"..."}`. Do not invent placeholder URLs like `[Your URL]`, `Example_URL`, or `MockMailPage_URL`.')
+    lines.push('For `browser` form work, prefer `{"action":"fill_form","fields":[{"element":"#email","value":"user@example.com"},{"element":"#password","value":"..."}]}`. A shorthand `form` object keyed by input id/name also works for simple forms.')
+  }
+
+  if (uniqueTools.includes('http_request')) {
+    lines.push('For `http_request`, send exact literal URLs from the task or from prior tool results. Keep JSON request bodies as raw JSON strings.')
+  }
+
+  if (uniqueTools.includes('email')) {
+    lines.push('For `email`, send mail with `{"action":"send","to":"user@example.com","subject":"...","body":"..."}`. If delivery depends on SMTP setup, check `{"action":"status"}` before claiming success.')
+  }
+
+  if (uniqueTools.includes('ask_human')) {
+    lines.push('For `ask_human`, when a workflow needs a code, approval, or out-of-band value from a person, do not guess or keep re-submitting blank forms. Use `{"action":"request_input","question":"..."}` and, for durable pauses, `{"action":"wait_for_reply","correlationId":"..."}`.')
+  }
+
+  return lines
+}
+
+export function looksLikeOpenEndedDeliverableTask(text: string): boolean {
+  const normalized = text.toLowerCase()
+  if (!normalized.trim()) return false
+  if (/```|package\.json|tsconfig|tsx?\b|jsx?\b|pytest|vitest|npm run|src\/|components\/|api\//.test(normalized)) return false
+  if (/\b(revise|revision|iterate|iteration|draft|deliverable|deliverables|offer|brief|copy|proposal|landing|outreach|plan|strategy|report|memo|document|docs?)\b/.test(normalized)) return true
+  return isBroadGoal(text) && /(\.md\b|\.txt\b|copy|brief|proposal|plan|report|draft|document)/.test(normalized)
+}
+
+function getExplicitRequiredToolNames(userMessage: string, enabledPlugins: string[]): string[] {
+  const normalized = userMessage.toLowerCase()
+  const required: string[] = []
+
+  if (enabledPlugins.includes('ask_human')
+    && (/\bask_human\b/.test(normalized) || /ask the human/.test(normalized) || /request_input/.test(normalized))) {
+    required.push('ask_human')
+  }
+
+  if (enabledPlugins.includes('email')
+    && (/\bemail\b/.test(normalized) || /send a welcome email/.test(normalized) || /send an email/.test(normalized))) {
+    required.push('email')
+  }
+
+  return required
+}
+
+const OPEN_ENDED_REVISION_BLOCK = [
+  '## Revision Loop',
+  'For open-ended deliverable work, do a real two-pass loop before declaring success: create the draft artifacts, critique them against the objective, then modify at least one artifact based on that critique.',
+  'A critique by itself does not count as iteration. Iteration requires an actual changed artifact.',
+  'When resuming in an existing workspace, inspect the current files first, then update them. Do not assume you lost access to the workspace without an explicit tool attempt.',
+  'If `files` is available, use it with explicit actions and paths to inspect and revise the artifacts.',
+].join('\n')
+
 /** Detect whether a user message is a broad, high-level goal that benefits from decomposition. */
 function isBroadGoal(text: string): boolean {
   if (text.length < 50) return false
@@ -75,6 +156,7 @@ function buildAgenticExecutionPolicy(opts: {
 }) {
   const hasTooling = opts.enabledPlugins.length > 0
   const pluginLines = buildPluginCapabilityLines(opts.enabledPlugins, { platformAssignScope: opts.platformAssignScope })
+  const toolDisciplineLines = buildToolDisciplineLines(opts.enabledPlugins)
 
   const parts: string[] = []
 
@@ -85,7 +167,8 @@ function buildAgenticExecutionPolicy(opts: {
       ? 'I take initiative — plan briefly, execute tools, evaluate, iterate until done. Never stop at advice when action is implied.'
       : 'No tools enabled. Be explicit about what tool access is needed.',
     'Follow through on stated intentions with tool calls. Never claim results without tool evidence.',
-    'If a tool is named explicitly, invoke it. Short progress updates between steps.',
+    'If a task explicitly names an enabled tool, use that tool before declaring success. A prose request is not a substitute for `ask_human`, and browser work is not a substitute for `email` delivery.',
+    'When `ask_human` is enabled, collect required human input through the tool instead of asking for it only in plain assistant text.',
     opts.loopMode === 'ongoing'
       ? 'Loop: ONGOING — keep iterating until done, blocked, or limits reached.'
       : 'Loop: BOUNDED — execute multiple steps but finish within recursion budget.',
@@ -103,14 +186,21 @@ function buildAgenticExecutionPolicy(opts: {
     'Execute by default — only ask for confirmation on high-risk/irreversible actions. Do not end every response with a question.',
     'Never repeat completed side effects. Verify state first.',
     'If a tool returns an error or validation failure, do not claim the task succeeded. Retry with corrected arguments or explain the blocker plainly.',
+    'Prefer the most specific tool you already have. Example: use `manage_schedules` for schedules and `manage_tasks` for tasks; treat `manage_platform` as a fallback umbrella only when a specific `manage_*` tool is unavailable.',
+    'For recurring, cron, interval, or follow-up automation requests, use `manage_schedules` directly when it is available.',
     'Delegation is optional, not a stopping condition. If one delegate backend is unavailable or unauthenticated, try another delegate backend or continue with your other tools.',
+    'If a required tool is missing, request access by name with `manage_capabilities` action `request_access` (for example `shell` or `manage_schedules`).',
     'Only mention files, screenshots, URLs, or download links that were actually returned by tools. Copy returned links exactly; do not rewrite them or prepend extra prefixes like "sandbox:".',
     `Heartbeat: if message is "${opts.heartbeatPrompt}", reply "HEARTBEAT_OK" unless you have a progress update.`,
     opts.heartbeatIntervalSec > 0 ? `Heartbeat cadence: ~${opts.heartbeatIntervalSec}s.` : '',
   )
 
+  if (toolDisciplineLines.length) parts.push('## Tool Discipline', ...toolDisciplineLines)
   if (pluginLines.length) parts.push('What I can do:\n' + pluginLines.join('\n'))
   if (opts.userMessage && isBroadGoal(opts.userMessage)) parts.push(GOAL_DECOMPOSITION_BLOCK)
+  if (opts.userMessage && looksLikeOpenEndedDeliverableTask(opts.userMessage) && opts.enabledPlugins.some((toolId) => toolId === 'files' || toolId === 'edit_file')) {
+    parts.push(OPEN_ENDED_REVISION_BLOCK)
+  }
 
   return parts.filter(Boolean).join('\n')
 }
@@ -166,7 +256,7 @@ export async function streamAgentChat(opts: StreamAgentChatOpts): Promise<Stream
       : typeof raw === 'string'
         ? Number.parseInt(raw, 10)
         : Number.NaN
-    if (!Number.isFinite(parsed)) return 120
+    if (!Number.isFinite(parsed)) return DEFAULT_HEARTBEAT_INTERVAL_SEC
     return Math.max(0, Math.min(3600, Math.trunc(parsed)))
   })()
 
@@ -184,12 +274,14 @@ export async function streamAgentChat(opts: StreamAgentChatOpts): Promise<Stream
   let agentPlatformAssignScope: 'self' | 'all' = 'self'
   let agentMcpServerIds: string[] | undefined
   let agentMcpDisabledTools: string[] | undefined
+  let agentHeartbeatEnabled = false
   if (session.agentId) {
     const agents = loadAgents()
     const agent = agents[session.agentId]
     agentPlatformAssignScope = agent?.platformAssignScope || 'self'
     agentMcpServerIds = agent?.mcpServerIds
     agentMcpDisabledTools = agent?.mcpDisabledTools
+    agentHeartbeatEnabled = agent?.heartbeatEnabled === true
     if (!hasProvidedSystemPrompt) {
       // Identity block — make sure the agent knows who it is
       const identityLines = [`## My Identity`, `My name is ${agent?.name || 'Agent'}.`]
@@ -506,13 +598,18 @@ export async function streamAgentChat(opts: StreamAgentChatOpts): Promise<Stream
 
   const MAX_AUTO_CONTINUES = 3
   const MAX_TRANSIENT_RETRIES = 2
+  const MAX_REQUIRED_TOOL_CONTINUES = 2
   let autoContinueCount = 0
   let transientRetryCount = 0
+  let requiredToolContinueCount = 0
+  const explicitRequiredToolNames = getExplicitRequiredToolNames(message, sessionPlugins)
+  const usedToolNames = new Set<string>()
 
   try {
-    const maxIterations = MAX_AUTO_CONTINUES + MAX_TRANSIENT_RETRIES
+    const maxIterations = MAX_AUTO_CONTINUES + MAX_TRANSIENT_RETRIES + MAX_REQUIRED_TOOL_CONTINUES
     for (let iteration = 0; iteration <= maxIterations; iteration++) {
-      let shouldContinue: 'recursion' | 'transient' | false = false
+      let shouldContinue: 'recursion' | 'transient' | 'required_tool' | false = false
+      let requiredToolReminderNames: string[] = []
       let waitingForToolResult = false
       let idleTimedOut = false
       let idleTimer: ReturnType<typeof setTimeout> | null = null
@@ -610,6 +707,7 @@ export async function streamAgentChat(opts: StreamAgentChatOpts): Promise<Stream
             needsTextSeparator = true
             lastSegment = ''
             const toolName = event.name || 'unknown'
+            usedToolNames.add(toolName)
             const input = event.data?.input
             // Estimate input tokens for plugin invocation tracking
             const inputStr = typeof input === 'string' ? input : JSON.stringify(input)
@@ -723,6 +821,22 @@ export async function streamAgentChat(opts: StreamAgentChatOpts): Promise<Stream
         abortController.signal.removeEventListener('abort', onParentAbort)
       }
 
+      if (!shouldContinue && explicitRequiredToolNames.length > 0 && requiredToolContinueCount < MAX_REQUIRED_TOOL_CONTINUES) {
+        requiredToolReminderNames = explicitRequiredToolNames.filter((toolName) => !usedToolNames.has(toolName))
+        if (requiredToolReminderNames.length > 0) {
+          shouldContinue = 'required_tool'
+          requiredToolContinueCount++
+          write(`data: ${JSON.stringify({
+            t: 'status',
+            text: JSON.stringify({
+              requiredToolsPending: requiredToolReminderNames,
+              reminderCount: requiredToolContinueCount,
+              maxReminders: MAX_REQUIRED_TOOL_CONTINUES,
+            }),
+          })}\n\n`)
+        }
+      }
+
       if (!shouldContinue) break
 
       if (shouldContinue === 'recursion') {
@@ -732,6 +846,14 @@ export async function streamAgentChat(opts: StreamAgentChatOpts): Promise<Stream
         }
         langchainMessages.push(new HumanMessage({ content: 'Continue where you left off. Complete the remaining steps of the objective.' }))
         lastSegment = ''
+      } else if (shouldContinue === 'required_tool') {
+        if (fullText.trim()) {
+          langchainMessages.push(new AIMessage({ content: fullText }))
+        }
+        langchainMessages.push(new HumanMessage({
+          content: `You have not yet completed the required explicit tool step(s): ${requiredToolReminderNames.join(', ')}. Use those enabled tools now before declaring success. Do not replace ask_human with a plain-text request, and do not replace email delivery with browser work or prose.`,
+        }))
+        lastSegment = ''
       } else if (shouldContinue === 'transient') {
         // Short delay before retrying transient errors (API timeout, rate limit, etc.)
         await new Promise((r) => setTimeout(r, 2000 * transientRetryCount))
@@ -741,6 +863,19 @@ export async function streamAgentChat(opts: StreamAgentChatOpts): Promise<Stream
     const errMsg = timedOut
       ? 'Ongoing loop stopped after reaching the configured runtime limit.'
       : err instanceof Error ? err.message : String(err)
+    const heartbeatEligible = runtime.loopMode === 'ongoing' || session.heartbeatEnabled === true || agentHeartbeatEnabled
+    const budgetLimited = timedOut || /recursion limit|maximum recursion/i.test(errMsg)
+    if (heartbeatEligible && budgetLimited) {
+      enqueueSystemEvent(
+        session.id,
+        '[Loop Budget Reached] The previous autonomous run stopped after hitting its loop budget. On the next heartbeat, resume carefully from the current state, verify completed work before repeating it, and focus only on the remaining objective.',
+        'loop_budget_reached',
+      )
+      logExecution(session.id, 'decision', 'Queued a deferred resume cue for the next heartbeat after loop budget exhaustion.', {
+        agentId: session.agentId,
+        detail: { timedOut, heartbeatEligible },
+      })
+    }
     logExecution(session.id, 'error', errMsg, { agentId: session.agentId, detail: { timedOut } })
     write(`data: ${JSON.stringify({ t: 'err', text: errMsg })}\n\n`)
   } finally {

package/src/lib/server/structured-extract.ts

@@ -348,7 +348,7 @@ export async function runStructuredExtraction(params: {
   let parsed: unknown
   try {
     parsed = parseModelJson(raw)
-  } catch (error) {
+  } catch {
     raw = await callExtractionModel({
       session: params.session,
       prompt: [

package/src/lib/server/task-mention.ts

@@ -43,7 +43,6 @@ export function parseMentionedAgentId(
   agents: Record<string, Agent>,
 ): string | null {
   const mentionRegex = /(?:^|[\s(])@([a-zA-Z0-9._-]+)/g
-  const agentList = Object.values(agents)
   let match: RegExpExecArray | null
 
   while ((match = mentionRegex.exec(description)) !== null) {

package/src/lib/server/tool-aliases.ts

@@ -1,11 +1,18 @@
 const PLUGIN_ALIAS_GROUPS: string[][] = [
-  ['shell', 'execute_command', 'process_tool', 'process'],
+  ['shell', 'execute_command', 'process_tool'],
   ['files', 'read_file', 'write_file', 'list_files', 'copy_file', 'move_file', 'delete_file', 'send_file'],
   ['edit_file'],
   ['web', 'web_search', 'web_fetch'],
   ['browser', 'openclaw_browser'],
   ['delegate', 'claude_code', 'codex_cli', 'opencode_cli', 'gemini_cli', 'delegate_to_claude_code', 'delegate_to_codex_cli', 'delegate_to_opencode_cli', 'delegate_to_gemini_cli'],
-  ['manage_platform', 'manage_agents', 'manage_tasks', 'manage_schedules', 'manage_skills', 'manage_documents', 'manage_webhooks', 'manage_secrets', 'manage_sessions'],
+  ['manage_platform'],
+  ['manage_agents'],
+  ['manage_tasks'],
+  ['manage_schedules'],
+  ['manage_skills'],
+  ['manage_documents'],
+  ['manage_webhooks'],
+  ['manage_secrets'],
   ['manage_connectors', 'connectors', 'connector_message_tool'],
   ['manage_chatrooms', 'chatroom'],
   ['spawn_subagent', 'subagent', 'delegate_to_agent'],
@@ -32,6 +39,21 @@ const PLUGIN_ALIAS_GROUPS: string[][] = [
   ['crawl', 'site_crawler'],
 ]
 
+const PLUGIN_IMPLICATIONS: Record<string, string[]> = {
+  shell: ['process'],
+  manage_platform: [
+    'manage_agents',
+    'manage_tasks',
+    'manage_schedules',
+    'manage_skills',
+    'manage_documents',
+    'manage_webhooks',
+    'manage_connectors',
+    'manage_sessions',
+    'manage_secrets',
+  ],
+}
+
 const PLUGIN_CANONICAL_MAP = (() => {
   const map = new Map<string, string>()
   for (const group of PLUGIN_ALIAS_GROUPS) {
@@ -85,13 +107,22 @@ export function expandPluginIds(values: string[] | null | undefined): string[] {
   while (queue.length > 0) {
     const next = queue.shift()!
     const normalized = normalizePluginId(next)
+    const canonical = canonicalizePluginId(next)
     const aliases = PLUGIN_ALIAS_MAP.get(normalized)
-    const key = aliases ? normalized : next
+    const key = aliases ? normalized : (canonical || next)
     if (expanded.has(key)) continue
     expanded.add(key)
-    if (!aliases) continue
-    for (const alias of aliases) {
-      if (!expanded.has(alias)) queue.push(alias)
+    if (aliases) {
+      for (const alias of aliases) {
+        if (!expanded.has(alias)) queue.push(alias)
+      }
+    }
+    const implicationSources = [key, normalized, normalizePluginId(canonical)]
+    for (const source of implicationSources) {
+      if (!source) continue
+      for (const implied of PLUGIN_IMPLICATIONS[source] || []) {
+        if (!expanded.has(implied)) queue.push(implied)
+      }
     }
   }
 

package/src/lib/server/tool-capability-policy.ts

@@ -56,7 +56,7 @@ const TOOL_DESCRIPTORS: Record<string, ToolDescriptor> = {
   opencode_cli: { categories: ['delegation', 'execution'], concreteTools: ['delegate_to_opencode_cli'] },
   gemini_cli: { categories: ['delegation', 'execution'], concreteTools: ['delegate_to_gemini_cli'] },
   memory: { categories: ['memory'], concreteTools: ['memory', 'memory_tool', 'context_status', 'context_summarize'] },
-  sandbox: { categories: ['execution', 'filesystem'], concreteTools: ['sandbox', 'sandbox_exec', 'sandbox_list_runtimes', 'openclaw_sandbox'] },
+  sandbox: { categories: ['execution', 'filesystem'], concreteTools: ['sandbox', 'sandbox_exec', 'sandbox_list_runtimes'] },
   git: { categories: ['execution', 'filesystem'], concreteTools: ['git'] },
   http_request: { categories: ['network'], concreteTools: ['http_request'] },
   canvas: { categories: ['filesystem'], concreteTools: ['canvas'] },