@swarmclawai/swarmclaw 0.7.6 → 0.7.8

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

@@ -11,11 +11,19 @@ import { loadRuntimeSettings, getAgentLoopRecursionLimit } from './runtime-setti
 
 import { logExecution } from './execution-log'
 import { buildCurrentDateTimePromptContext } from './prompt-runtime-context'
-import { expandPluginIds } from './tool-aliases'
+import { canonicalizePluginId, 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'
+import { resolveActiveProjectContext } from './project-context'
+import {
+  getEnabledToolPlanningView,
+  getFirstToolForCapability,
+  getToolsForCapability,
+  matchToolCapabilitiesForMessage,
+  TOOL_CAPABILITY,
+} from './tool-planning'
 
 /** Extract a breadcrumb title from notable tool completions (task/schedule/agent creation). */
 interface StreamAgentChatOpts {
@@ -46,7 +54,8 @@ function buildPluginCapabilityLines(enabledPlugins: string[], opts?: { platformA
 }
 
 export function buildToolDisciplineLines(enabledPlugins: string[]): string[] {
-  const uniqueTools = Array.from(new Set(enabledPlugins.filter(Boolean))).sort()
+  const planning = getEnabledToolPlanningView(enabledPlugins)
+  const uniqueTools = planning.displayToolIds
   if (uniqueTools.length === 0) return []
 
   const lines = [
@@ -59,33 +68,26 @@ export function buildToolDisciplineLines(enabledPlugins: string[]): string[] {
     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.')
-  }
+  lines.push(...planning.disciplineGuidance)
 
-  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.')
-  }
+  const researchSearchTools = getToolsForCapability(enabledPlugins, TOOL_CAPABILITY.researchSearch)
+  const researchFetchTools = getToolsForCapability(enabledPlugins, TOOL_CAPABILITY.researchFetch)
+  const browserCaptureTools = getToolsForCapability(enabledPlugins, TOOL_CAPABILITY.browserCapture)
+  const deliveryMediaTools = getToolsForCapability(enabledPlugins, TOOL_CAPABILITY.deliveryMedia)
+  const deliveryVoiceTools = getToolsForCapability(enabledPlugins, TOOL_CAPABILITY.deliveryVoiceNote)
 
-  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 ((researchSearchTools.length || researchFetchTools.length) && browserCaptureTools.length) {
+    const researchLabel = [...researchSearchTools, ...researchFetchTools].map((toolName) => `\`${toolName}\``).join('/')
+    lines.push(`Research tools like ${researchLabel} gather sources and text, but they do not capture screenshots. Use \`${browserCaptureTools[0]}\` for screenshots or rendered page evidence.`)
+    lines.push(`When a task asks for both research and screenshots, use ${researchLabel} first to identify the right source URLs, then use \`${browserCaptureTools[0]}\` to capture the relevant page.`)
   }
 
-  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 (browserCaptureTools.length && deliveryMediaTools.length) {
+    lines.push(`When the user asks you to send screenshots or other media, capture the artifact first with \`${browserCaptureTools[0]}\`, then deliver that exact file or upload URL through \`${deliveryMediaTools[0]}\` instead of saying the capability is unavailable.`)
   }
 
-  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":"..."}`.')
+  if (deliveryVoiceTools.length) {
+    lines.push(`If the user asks for a voice note and \`${deliveryVoiceTools[0]}\` is enabled, try it before saying voice notes are unsupported.`)
   }
 
   return lines
@@ -99,9 +101,36 @@ export function looksLikeOpenEndedDeliverableTask(text: string): boolean {
   return isBroadGoal(text) && /(\.md\b|\.txt\b|copy|brief|proposal|plan|report|draft|document)/.test(normalized)
 }
 
-function getExplicitRequiredToolNames(userMessage: string, enabledPlugins: string[]): string[] {
+export function getExplicitRequiredToolNames(userMessage: string, enabledPlugins: string[]): string[] {
   const normalized = userMessage.toLowerCase()
   const required: string[] = []
+  const matchedCapabilities = matchToolCapabilitiesForMessage(enabledPlugins, userMessage)
+
+  const requireCapability = (capability: string) => {
+    const toolName = matchedCapabilities.get(capability)?.[0] || getFirstToolForCapability(enabledPlugins, capability)
+    if (toolName && !required.includes(toolName)) required.push(toolName)
+  }
+
+  if (matchedCapabilities.has(TOOL_CAPABILITY.researchSearch)) {
+    requireCapability(TOOL_CAPABILITY.researchSearch)
+  }
+
+  if (matchedCapabilities.has(TOOL_CAPABILITY.researchFetch)) {
+    requireCapability(TOOL_CAPABILITY.researchFetch)
+  }
+
+  if (matchedCapabilities.has(TOOL_CAPABILITY.browserCapture)) {
+    requireCapability(TOOL_CAPABILITY.browserCapture)
+  }
+
+  if (matchedCapabilities.has(TOOL_CAPABILITY.deliveryVoiceNote)) {
+    requireCapability(TOOL_CAPABILITY.deliveryVoiceNote)
+  }
+
+  if (matchedCapabilities.has(TOOL_CAPABILITY.deliveryMedia) || matchedCapabilities.has(TOOL_CAPABILITY.deliveryMessage)) {
+    requireCapability(TOOL_CAPABILITY.deliveryMedia)
+    requireCapability(TOOL_CAPABILITY.deliveryMessage)
+  }
 
   if (enabledPlugins.includes('ask_human')
     && (/\bask_human\b/.test(normalized) || /ask the human/.test(normalized) || /request_input/.test(normalized))) {
@@ -140,10 +169,10 @@ const GOAL_DECOMPOSITION_BLOCK = [
   '## Goal Decomposition',
   'When you receive a broad, open-ended goal:',
   '1. Break it into 3-7 concrete, sequentially-executable subtasks before taking action.',
-  '2. If manage_tasks is available, create a task for each subtask to track progress.',
-  '3. Present the plan as a short checklist or numbered list in plain language.',
-  '4. Execute the first subtask immediately — do not stop after planning.',
-  '5. After each subtask, update progress and move to the next.',
+  '2. If manage_tasks is available, use it only for durable tracking: multi-turn work, delegation, explicit backlog requests, or work you expect to resume later. Do not create a task for every micro-step.',
+  '3. Present the plan as a short checklist or numbered list in plain language. If durable tracking is unnecessary, keep it inline instead of creating tasks.',
+  '4. Execute the first substantive subtask immediately — do not stop after planning.',
+  '5. Update only the durable tasks you actually created; otherwise just continue executing and report progress plainly.',
 ].join('\n')
 
 function buildAgenticExecutionPolicy(opts: {
@@ -275,6 +304,8 @@ export async function streamAgentChat(opts: StreamAgentChatOpts): Promise<Stream
   let agentMcpServerIds: string[] | undefined
   let agentMcpDisabledTools: string[] | undefined
   let agentHeartbeatEnabled = false
+  let agentMemoryScopeMode: 'auto' | 'all' | 'global' | 'agent' | 'session' | 'project' | null = null
+  const activeProjectContext = resolveActiveProjectContext(session)
   if (session.agentId) {
     const agents = loadAgents()
     const agent = agents[session.agentId]
@@ -282,6 +313,7 @@ export async function streamAgentChat(opts: StreamAgentChatOpts): Promise<Stream
     agentMcpServerIds = agent?.mcpServerIds
     agentMcpDisabledTools = agent?.mcpDisabledTools
     agentHeartbeatEnabled = agent?.heartbeatEnabled === true
+    agentMemoryScopeMode = agent?.memoryScopeMode || null
     if (!hasProvidedSystemPrompt) {
       // Identity block — make sure the agent knows who it is
       const identityLines = [`## My Identity`, `My name is ${agent?.name || 'Agent'}.`]
@@ -336,6 +368,43 @@ export async function streamAgentChat(opts: StreamAgentChatOpts): Promise<Stream
     // Plugin context injection is non-critical
   }
 
+  if (!hasProvidedSystemPrompt && activeProjectContext.projectId) {
+    const projectLines = ['## Current Project']
+    if (activeProjectContext.project?.name) {
+      projectLines.push(`Active project: ${activeProjectContext.project.name}.`)
+    } else {
+      projectLines.push(`Active project ID: ${activeProjectContext.projectId}.`)
+    }
+    if (activeProjectContext.project?.description) {
+      projectLines.push(`Project description: ${activeProjectContext.project.description}`)
+      projectLines.push('Treat the project description above as authoritative context for who the project is for, what it is focused on, and which pilot priorities matter right now. If the user asks about the active project, answer from that description instead of saying the context is unavailable.')
+    }
+    if (activeProjectContext.objective) projectLines.push(`Project objective: ${activeProjectContext.objective}`)
+    if (activeProjectContext.audience) projectLines.push(`Who it is for: ${activeProjectContext.audience}`)
+    if (activeProjectContext.priorities.length > 0) projectLines.push(`Pilot priorities: ${activeProjectContext.priorities.join('; ')}`)
+    if (activeProjectContext.openObjectives.length > 0) projectLines.push(`Open objectives: ${activeProjectContext.openObjectives.join('; ')}`)
+    if (activeProjectContext.capabilityHints.length > 0) projectLines.push(`Suggested operating modes: ${activeProjectContext.capabilityHints.join('; ')}`)
+    if (activeProjectContext.credentialRequirements.length > 0) projectLines.push(`Credential and secret requirements: ${activeProjectContext.credentialRequirements.join('; ')}`)
+    if (activeProjectContext.successMetrics.length > 0) projectLines.push(`Success metrics: ${activeProjectContext.successMetrics.join('; ')}`)
+    if (activeProjectContext.heartbeatPrompt) projectLines.push(`Preferred heartbeat prompt: ${activeProjectContext.heartbeatPrompt}`)
+    if (activeProjectContext.heartbeatIntervalSec != null) projectLines.push(`Preferred heartbeat interval: ${activeProjectContext.heartbeatIntervalSec}s`)
+    if (activeProjectContext.resourceSummary) {
+      const summary = activeProjectContext.resourceSummary
+      const resourceBits = [
+        `open tasks ${summary.openTaskCount}`,
+        `active schedules ${summary.activeScheduleCount}`,
+        `project secrets ${summary.secretCount}`,
+      ]
+      if (summary.topTaskTitles.length > 0) projectLines.push(`Top open tasks: ${summary.topTaskTitles.join('; ')}`)
+      if (summary.scheduleNames.length > 0) projectLines.push(`Active schedules: ${summary.scheduleNames.join('; ')}`)
+      if (summary.secretNames.length > 0) projectLines.push(`Known project secrets: ${summary.secretNames.join('; ')}`)
+      projectLines.push(`Project resource summary: ${resourceBits.join(', ')}.`)
+    }
+    if (activeProjectContext.projectRoot) projectLines.push(`Workspace root: ${activeProjectContext.projectRoot}`)
+    projectLines.push('When creating project tasks, schedules, secrets, memories, or deliverables for this work, default them to the active project unless the user redirects you.')
+    stateModifierParts.push(projectLines.join('\n'))
+  }
+
   // Tell the LLM about available plugins and their access status
   {
     const agentEnabledSet = new Set(sessionPlugins)
@@ -407,6 +476,11 @@ export async function streamAgentChat(opts: StreamAgentChatOpts): Promise<Stream
     platformAssignScope: agentPlatformAssignScope,
     mcpServerIds: agentMcpServerIds,
     mcpDisabledTools: agentMcpDisabledTools,
+    projectId: activeProjectContext.projectId,
+    projectRoot: activeProjectContext.projectRoot,
+    projectName: activeProjectContext.project?.name || null,
+    projectDescription: activeProjectContext.project?.description || null,
+    memoryScopeMode: agentMemoryScopeMode,
   })
   const agent = createReactAgent({ llm, tools, stateModifier })
   const recursionLimit = getAgentLoopRecursionLimit(runtime)
@@ -707,7 +781,7 @@ export async function streamAgentChat(opts: StreamAgentChatOpts): Promise<Stream
             needsTextSeparator = true
             lastSegment = ''
             const toolName = event.name || 'unknown'
-            usedToolNames.add(toolName)
+            usedToolNames.add(canonicalizePluginId(toolName) || toolName)
             const input = event.data?.input
             // Estimate input tokens for plugin invocation tracking
             const inputStr = typeof input === 'string' ? input : JSON.stringify(input)
@@ -851,7 +925,7 @@ export async function streamAgentChat(opts: StreamAgentChatOpts): Promise<Stream
           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.`,
+          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, do not replace outbound delivery tools with prose, and do not replace screenshot requests with text-only summaries.`,
         }))
         lastSegment = ''
       } else if (shouldContinue === 'transient') {

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

@@ -7,6 +7,7 @@ const PLUGIN_ALIAS_GROUPS: string[][] = [
   ['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_projects'],
   ['manage_tasks'],
   ['manage_schedules'],
   ['manage_skills'],
@@ -43,6 +44,7 @@ const PLUGIN_IMPLICATIONS: Record<string, string[]> = {
   shell: ['process'],
   manage_platform: [
     'manage_agents',
+    'manage_projects',
     'manage_tasks',
     'manage_schedules',
     'manage_skills',

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

@@ -56,3 +56,27 @@ test('concrete tool checks inherit blocked family rules', () => {
     null,
   )
 })
+
+test('task and project management can be disabled from app settings', () => {
+  const decision = resolveSessionToolPolicy(
+    ['manage_platform', 'manage_tasks', 'manage_projects'],
+    {
+      taskManagementEnabled: false,
+      projectManagementEnabled: false,
+    },
+  )
+
+  assert.deepEqual(decision.enabledPlugins, ['manage_platform'])
+  assert.equal(
+    decision.blockedPlugins.some((entry) => entry.tool === 'manage_tasks' && /disabled in app settings/.test(entry.reason)),
+    true,
+  )
+  assert.equal(
+    decision.blockedPlugins.some((entry) => entry.tool === 'manage_projects' && /disabled in app settings/.test(entry.reason)),
+    true,
+  )
+  assert.match(
+    resolveConcreteToolPolicyBlock('manage_tasks', decision, { taskManagementEnabled: false }),
+    /task management is disabled/i,
+  )
+})

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

@@ -64,8 +64,9 @@ const TOOL_DESCRIPTORS: Record<string, ToolDescriptor> = {
   monitor: { categories: ['execution'], concreteTools: ['monitor', 'monitor_tool'] },
   openclaw_workspace: { categories: ['filesystem', 'platform'], concreteTools: ['openclaw_workspace'] },
   openclaw_nodes: { categories: ['platform'], concreteTools: ['openclaw_nodes'] },
-  manage_platform: { categories: ['platform'], concreteTools: ['manage_platform', 'manage_agents', 'manage_tasks', 'manage_schedules', 'manage_skills', 'manage_documents', 'manage_webhooks', 'manage_connectors', 'manage_sessions', 'manage_secrets'] },
+  manage_platform: { categories: ['platform'], concreteTools: ['manage_platform', 'manage_agents', 'manage_projects', 'manage_tasks', 'manage_schedules', 'manage_skills', 'manage_documents', 'manage_webhooks', 'manage_connectors', 'manage_sessions', 'manage_secrets'] },
   manage_agents: { categories: ['platform'], concreteTools: ['manage_agents'] },
+  manage_projects: { categories: ['platform'], concreteTools: ['manage_projects'] },
   manage_tasks: { categories: ['platform'], concreteTools: ['manage_tasks'] },
   manage_schedules: { categories: ['platform'], concreteTools: ['manage_schedules'] },
   schedule_wake: { categories: ['platform'], concreteTools: ['schedule_wake'] },
@@ -179,6 +180,24 @@ function ensureSettings(settings?: AppSettings | Record<string, unknown> | null)
   return settings as Record<string, unknown>
 }
 
+export function isTaskManagementEnabled(settings?: AppSettings | Record<string, unknown> | null): boolean {
+  return ensureSettings(settings).taskManagementEnabled !== false
+}
+
+export function isProjectManagementEnabled(settings?: AppSettings | Record<string, unknown> | null): boolean {
+  return ensureSettings(settings).projectManagementEnabled !== false
+}
+
+function settingsBlockReason(toolName: string, settings?: AppSettings | Record<string, unknown> | null): string | null {
+  if (toolName === 'manage_tasks' && !isTaskManagementEnabled(settings)) {
+    return 'blocked because task management is disabled in app settings'
+  }
+  if (toolName === 'manage_projects' && !isProjectManagementEnabled(settings)) {
+    return 'blocked because project management is disabled in app settings'
+  }
+  return null
+}
+
 function parsePolicyConfig(settings: Record<string, unknown>) {
   const mode = normalizeMode(settings.capabilityPolicyMode)
   const safetyBlocked = new Set(getSettingsList(settings, 'safetyBlockedTools'))
@@ -216,6 +235,12 @@ export function resolveSessionToolPolicy(
 
   for (const pluginName of requestedPlugins) {
     const descriptor = TOOL_DESCRIPTORS[pluginName]
+    const settingsReason = settingsBlockReason(pluginName, normalizedSettings)
+
+    if (settingsReason) {
+      blockedPlugins.push({ tool: pluginName, reason: settingsReason, source: 'policy' })
+      continue
+    }
 
     if (safetyMatchesTool(safetyBlocked, pluginName, descriptor)) {
       blockedPlugins.push({ tool: pluginName, reason: 'blocked by safety policy', source: 'safety' })
@@ -269,6 +294,9 @@ export function resolveConcreteToolPolicyBlock(
     policyBlockedNames,
     policyAllowedNames,
   } = parsePolicyConfig(normalizedSettings)
+  const settingsReason = settingsBlockReason(name, normalizedSettings)
+
+  if (settingsReason) return settingsReason
 
   if (safetyBlocked.has(name)) return 'blocked by safety policy'
 

package/src/lib/server/tool-planning.test.ts

@@ -0,0 +1,44 @@
+import assert from 'node:assert/strict'
+import { describe, it } from 'node:test'
+import { getPluginManager } from './plugins'
+import { getEnabledToolPlanningView, getToolsForCapability, TOOL_CAPABILITY } from './tool-planning'
+
+let seq = 0
+
+function uniquePluginId(prefix: string): string {
+  seq += 1
+  return `${prefix}_${Date.now()}_${seq}`
+}
+
+describe('tool-planning', () => {
+  it('collects core planning metadata for aliased built-in tools', () => {
+    const view = getEnabledToolPlanningView(['web_search', 'web_fetch', 'browser', 'manage_connectors'])
+
+    assert.deepEqual(view.displayToolIds, ['browser', 'manage_connectors', 'web'])
+    assert.deepEqual(getToolsForCapability(['web_search'], TOOL_CAPABILITY.researchSearch), ['web_search'])
+    assert.deepEqual(getToolsForCapability(['manage_connectors'], TOOL_CAPABILITY.deliveryVoiceNote), ['connector_message_tool'])
+  })
+
+  it('collects planning metadata from custom plugin tools', () => {
+    const pluginId = uniquePluginId('planner_plugin')
+    getPluginManager().registerBuiltin(pluginId, {
+      name: 'Planner Plugin',
+      tools: [
+        {
+          name: 'custom_media_sender',
+          description: 'Send rendered media somewhere special.',
+          planning: {
+            capabilities: ['delivery.media', 'delivery.voice_note'],
+            disciplineGuidance: ['Use `custom_media_sender` for bespoke outbound media delivery.'],
+          },
+          parameters: { type: 'object', properties: {} },
+          execute: async () => 'ok',
+        },
+      ],
+    })
+
+    const view = getEnabledToolPlanningView([pluginId])
+    assert.deepEqual(getToolsForCapability([pluginId], TOOL_CAPABILITY.deliveryMedia), ['custom_media_sender'])
+    assert.equal(view.disciplineGuidance.includes('Use `custom_media_sender` for bespoke outbound media delivery.'), true)
+  })
+})

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

@@ -0,0 +1,269 @@
+import type { PluginToolPlanning } from '@/types'
+import { getPluginManager } from './plugins'
+import { canonicalizePluginId, expandPluginIds } from './tool-aliases'
+
+export const TOOL_CAPABILITY = {
+  researchSearch: 'research.search',
+  researchFetch: 'research.fetch',
+  browserNavigate: 'browser.navigate',
+  browserCapture: 'browser.capture',
+  artifactPdf: 'artifact.pdf',
+  deliveryMessage: 'delivery.message',
+  deliveryMedia: 'delivery.media',
+  deliveryVoiceNote: 'delivery.voice_note',
+} as const
+
+export interface ToolPlanningEntry {
+  toolName: string
+  capabilities: string[]
+  disciplineGuidance: string[]
+  requestMatchers: NonNullable<PluginToolPlanning['requestMatchers']>
+}
+
+export interface ToolPlanningView {
+  displayToolIds: string[]
+  expandedPluginIds: string[]
+  entries: ToolPlanningEntry[]
+  disciplineGuidance: string[]
+  capabilityToTools: Map<string, string[]>
+}
+
+const CORE_TOOL_PLANNING: Record<string, ToolPlanningEntry[]> = {
+  files: [
+    {
+      toolName: 'files',
+      capabilities: ['artifact.files'],
+      disciplineGuidance: [
+        '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":"..."}]}`.',
+      ],
+      requestMatchers: [],
+    },
+  ],
+  shell: [
+    {
+      toolName: 'shell',
+      capabilities: ['runtime.shell'],
+      disciplineGuidance: [
+        'For `shell`, use `{"action":"execute","command":"..."}` for commands and `{"action":"status","processId":"..."}` or `{"action":"log","processId":"..."}` for long-lived processes.',
+      ],
+      requestMatchers: [],
+    },
+  ],
+  web: [
+    {
+      toolName: 'web_search',
+      capabilities: [TOOL_CAPABILITY.researchSearch],
+      disciplineGuidance: [
+        'For `web_search`, use `{"query":"..."}` to research fresh information. For current events, breaking news, or "latest" requests, start with `web_search` before summarizing.',
+      ],
+      requestMatchers: [
+        {
+          capability: TOOL_CAPABILITY.researchSearch,
+          patterns: ['research', 'look up', 'find out', 'search for', 'compare', 'latest', 'news', 'headline', 'current event', 'recent update', "what's new", 'what happened'],
+          forbidLiteralUrl: true,
+        },
+      ],
+    },
+    {
+      toolName: 'web_fetch',
+      capabilities: [TOOL_CAPABILITY.researchFetch],
+      disciplineGuidance: [
+        'For `web_fetch`, use `{"url":"https://..."}` to read a specific page or article after you know the URL.',
+      ],
+      requestMatchers: [
+        {
+          capability: TOOL_CAPABILITY.researchFetch,
+          patterns: ['read', 'summarize', 'summarise', 'analyze', 'analyse', 'extract', 'review', 'article', 'page', 'url', 'link'],
+          requireLiteralUrl: true,
+        },
+      ],
+    },
+  ],
+  browser: [
+    {
+      toolName: 'browser',
+      capabilities: [TOOL_CAPABILITY.browserNavigate, TOOL_CAPABILITY.browserCapture, TOOL_CAPABILITY.artifactPdf],
+      disciplineGuidance: [
+        '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`.',
+        '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.',
+        'Use `browser` when the user asks for screenshots, visual proof, page capture, PDFs, or a rendered view of a page. `navigate` alone is not a screenshot.',
+      ],
+      requestMatchers: [
+        {
+          capability: TOOL_CAPABILITY.browserNavigate,
+          patterns: ['browser', 'click', 'fill form', 'log in', 'login', 'navigate'],
+          requireLiteralUrl: true,
+        },
+        {
+          capability: TOOL_CAPABILITY.browserCapture,
+          patterns: ['screenshot', 'screen shot', 'snapshot', 'page capture', 'visual proof', 'capture the page', 'rendered view'],
+        },
+        {
+          capability: TOOL_CAPABILITY.artifactPdf,
+          patterns: ['pdf', 'save as pdf', 'export pdf'],
+        },
+      ],
+    },
+  ],
+  manage_connectors: [
+    {
+      toolName: 'connector_message_tool',
+      capabilities: [TOOL_CAPABILITY.deliveryMessage, TOOL_CAPABILITY.deliveryMedia, TOOL_CAPABILITY.deliveryVoiceNote],
+      disciplineGuidance: [
+        'For outbound delivery, inspect available channels with `connector_message_tool` using `{"action":"list_running"}` before claiming something cannot be sent.',
+        'Use `connector_message_tool` with `{"action":"send","message":"...","mediaPath":"..."}` for text/media and `{"action":"send_voice_note","voiceText":"..."}` for voice notes.',
+        'If no channel or recipient is configured, explain that connector/channel setup is missing rather than claiming the capability does not exist.',
+      ],
+      requestMatchers: [
+        {
+          capability: TOOL_CAPABILITY.deliveryMessage,
+          patterns: ['send', 'share', 'deliver', 'message'],
+        },
+        {
+          capability: TOOL_CAPABILITY.deliveryMedia,
+          patterns: ['screenshot', 'screen shot', 'snapshot', 'image', 'photo', 'file', 'pdf', 'attachment'],
+        },
+        {
+          capability: TOOL_CAPABILITY.deliveryVoiceNote,
+          patterns: ['voice note', 'voice-note', 'voicenote', 'voice memo', 'voice message', 'audio note', 'audio update', 'ptt'],
+        },
+      ],
+    },
+  ],
+  http_request: [
+    {
+      toolName: 'http_request',
+      capabilities: ['network.http'],
+      disciplineGuidance: [
+        'For `http_request`, send exact literal URLs from the task or from prior tool results. Keep JSON request bodies as raw JSON strings.',
+      ],
+      requestMatchers: [],
+    },
+  ],
+  email: [
+    {
+      toolName: 'email',
+      capabilities: ['delivery.email'],
+      disciplineGuidance: [
+        '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.',
+      ],
+      requestMatchers: [],
+    },
+  ],
+  ask_human: [
+    {
+      toolName: 'ask_human',
+      capabilities: ['human.input'],
+      disciplineGuidance: [
+        '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":"..."}`.',
+      ],
+      requestMatchers: [],
+    },
+  ],
+}
+
+function dedupeStrings(values: string[]): string[] {
+  return Array.from(new Set(values.filter((value) => typeof value === 'string' && value.trim()).map((value) => value.trim())))
+}
+
+function normalizePlanningEntry(toolName: string, planning: PluginToolPlanning | null | undefined): ToolPlanningEntry | null {
+  if (!planning) return null
+  const capabilities = dedupeStrings(Array.isArray(planning.capabilities) ? planning.capabilities : [])
+  const disciplineGuidance = dedupeStrings(Array.isArray(planning.disciplineGuidance) ? planning.disciplineGuidance : [])
+  const requestMatchers = Array.isArray(planning.requestMatchers)
+    ? planning.requestMatchers
+        .map((matcher) => ({
+          capability: typeof matcher?.capability === 'string' ? matcher.capability.trim() : '',
+          patterns: dedupeStrings(Array.isArray(matcher?.patterns) ? matcher.patterns : []),
+          requireLiteralUrl: matcher?.requireLiteralUrl === true,
+          forbidLiteralUrl: matcher?.forbidLiteralUrl === true,
+        }))
+        .filter((matcher) => matcher.capability || matcher.patterns.length > 0)
+    : []
+  if (!capabilities.length && !disciplineGuidance.length && !requestMatchers.length) return null
+  return {
+    toolName,
+    capabilities,
+    disciplineGuidance,
+    requestMatchers,
+  }
+}
+
+export function getEnabledToolPlanningView(enabledPlugins: string[]): ToolPlanningView {
+  const displayToolIds = dedupeStrings(enabledPlugins.map((toolId) => canonicalizePluginId(toolId))).sort()
+  const expandedPluginIds = dedupeStrings(expandPluginIds(enabledPlugins)).sort()
+  const entries: ToolPlanningEntry[] = []
+
+  for (const pluginId of expandedPluginIds) {
+    const coreEntries = CORE_TOOL_PLANNING[pluginId] || []
+    for (const entry of coreEntries) {
+      entries.push({
+        toolName: entry.toolName,
+        capabilities: [...entry.capabilities],
+        disciplineGuidance: [...entry.disciplineGuidance],
+        requestMatchers: [...entry.requestMatchers],
+      })
+    }
+  }
+
+  for (const entry of getPluginManager().getTools(expandedPluginIds)) {
+    const planningEntry = normalizePlanningEntry(entry.tool.name, entry.tool.planning)
+    if (planningEntry) entries.push(planningEntry)
+  }
+
+  const disciplineSet = new Set<string>()
+  const capabilityToTools = new Map<string, Set<string>>()
+  for (const entry of entries) {
+    for (const line of entry.disciplineGuidance) disciplineSet.add(line)
+    for (const capability of entry.capabilities) {
+      const current = capabilityToTools.get(capability) || new Set<string>()
+      current.add(entry.toolName)
+      capabilityToTools.set(capability, current)
+    }
+  }
+
+  return {
+    displayToolIds,
+    expandedPluginIds,
+    entries,
+    disciplineGuidance: Array.from(disciplineSet),
+    capabilityToTools: new Map(
+      Array.from(capabilityToTools.entries()).map(([capability, toolNames]) => [capability, Array.from(toolNames)]),
+    ),
+  }
+}
+
+export function getToolsForCapability(enabledPlugins: string[], capability: string): string[] {
+  return getEnabledToolPlanningView(enabledPlugins).capabilityToTools.get(capability) || []
+}
+
+export function getFirstToolForCapability(enabledPlugins: string[], capability: string): string | null {
+  return getToolsForCapability(enabledPlugins, capability)[0] || null
+}
+
+export function matchToolCapabilitiesForMessage(
+  enabledPlugins: string[],
+  message: string,
+): Map<string, string[]> {
+  const text = String(message || '').toLowerCase()
+  const hasLiteralUrl = /https?:\/\/[^\s<>"')]+/i.test(message)
+  const matches = new Map<string, Set<string>>()
+
+  for (const entry of getEnabledToolPlanningView(enabledPlugins).entries) {
+    for (const matcher of entry.requestMatchers) {
+      const patterns = Array.isArray(matcher.patterns) ? matcher.patterns : []
+      if (matcher.requireLiteralUrl === true && !hasLiteralUrl) continue
+      if (matcher.forbidLiteralUrl === true && hasLiteralUrl) continue
+      if (!patterns.length) continue
+      const matched = patterns.some((pattern) => text.includes(pattern.toLowerCase()))
+      if (!matched) continue
+      const capability = matcher.capability || entry.capabilities[0] || ''
+      if (!capability) continue
+      const current = matches.get(capability) || new Set<string>()
+      current.add(entry.toolName)
+      matches.set(capability, current)
+    }
+  }
+
+  return new Map(Array.from(matches.entries()).map(([capability, toolNames]) => [capability, Array.from(toolNames)]))
+}