@swarmclawai/swarmclaw 0.7.7 → 0.8.0

package/src/lib/server/tool-loop-detection.test.ts

@@ -0,0 +1,105 @@
+import assert from 'node:assert/strict'
+import { describe, it } from 'node:test'
+import { ToolLoopTracker, hashToolInput, hashToolOutput } from './tool-loop-detection'
+
+describe('ToolLoopTracker', () => {
+  it('returns null for normal non-repeating tool calls', () => {
+    const tracker = new ToolLoopTracker()
+    assert.equal(tracker.record('web_search', { query: 'weather london' }, 'Sunny, 20C'), null)
+    assert.equal(tracker.record('files', { action: 'write', path: '/tmp/test.json' }, 'OK'), null)
+    assert.equal(tracker.record('web_search', { query: 'weather paris' }, 'Cloudy, 15C'), null)
+    assert.equal(tracker.size, 3)
+  })
+
+  it('detects generic repeat at warning threshold', () => {
+    const tracker = new ToolLoopTracker({ repeatWarn: 3, repeatCritical: 6 })
+    for (let i = 0; i < 2; i++) {
+      assert.equal(tracker.record('web_search', { query: 'same query' }, `result ${i}`), null)
+    }
+    const result = tracker.record('web_search', { query: 'same query' }, 'result 2')
+    assert.ok(result)
+    assert.equal(result.severity, 'warning')
+    assert.equal(result.detector, 'generic_repeat')
+  })
+
+  it('detects generic repeat at critical threshold', () => {
+    const tracker = new ToolLoopTracker({ repeatWarn: 3, repeatCritical: 5, toolFrequencyWarn: 100, toolFrequencyCritical: 100 })
+    for (let i = 0; i < 4; i++) {
+      tracker.record('web_search', { query: 'same' }, `result ${i}`)
+    }
+    const result = tracker.record('web_search', { query: 'same' }, 'result 4')
+    assert.ok(result)
+    assert.equal(result.severity, 'critical')
+    assert.equal(result.detector, 'generic_repeat')
+  })
+
+  it('detects polling stall when same tool returns identical output', () => {
+    const tracker = new ToolLoopTracker({ pollWarn: 3, pollCritical: 5 })
+    // Different inputs but same output = polling stall
+    for (let i = 0; i < 2; i++) {
+      assert.equal(tracker.record('process', { action: 'poll', id: `run-${i}` }, 'status: running'), null)
+    }
+    const result = tracker.record('process', { action: 'poll', id: 'run-2' }, 'status: running')
+    assert.ok(result)
+    assert.equal(result.severity, 'warning')
+    assert.equal(result.detector, 'polling_stall')
+  })
+
+  it('detects ping-pong between two tools', () => {
+    const tracker = new ToolLoopTracker({ pingPongWarn: 2, pingPongCritical: 4 })
+    // Simulate A-B-A-B with identical outputs
+    for (let i = 0; i < 2; i++) {
+      tracker.record('web_search', { query: 'find it' }, 'no results found')
+      tracker.record('web_fetch', { url: 'https://example.com' }, '404 not found')
+    }
+    // One more A to complete the 3rd pair-start
+    const result = tracker.record('web_search', { query: 'find it' }, 'no results found')
+    // The ping-pong detector checks the last pair against previous pairs
+    // After 4 calls (A-B-A-B) + 1 more A, we have 2 full A-B cycles with identical results
+    if (result) {
+      assert.equal(result.detector, 'ping_pong')
+    }
+  })
+
+  it('circuit breaker fires at absolute cap', () => {
+    const tracker = new ToolLoopTracker({ circuitBreaker: 5, repeatWarn: 100, repeatCritical: 100, toolFrequencyWarn: 100, toolFrequencyCritical: 100 })
+    for (let i = 0; i < 4; i++) {
+      tracker.record('shell', { command: 'curl http://stuck.com' }, `err ${i}`)
+    }
+    const result = tracker.record('shell', { command: 'curl http://stuck.com' }, 'err 4')
+    assert.ok(result)
+    assert.equal(result.severity, 'critical')
+    assert.equal(result.detector, 'circuit_breaker')
+  })
+
+  it('does not fire for varied tool calls even with many total calls', () => {
+    const tracker = new ToolLoopTracker({ toolFrequencyWarn: 100, toolFrequencyCritical: 100 })
+    for (let i = 0; i < 20; i++) {
+      const result = tracker.record('web_search', { query: `query ${i}` }, `result ${i}`)
+      assert.equal(result, null, `Unexpected detection at call ${i}`)
+    }
+    assert.equal(tracker.size, 20)
+  })
+
+  it('detects tool frequency when same tool is called too many times (any input)', () => {
+    const tracker = new ToolLoopTracker({ toolFrequencyWarn: 3, toolFrequencyCritical: 5 })
+    for (let i = 0; i < 2; i++) {
+      assert.equal(tracker.record('web_search', { query: `q${i}` }, `r${i}`), null)
+    }
+    const warn = tracker.record('web_search', { query: 'q2' }, 'r2')
+    assert.ok(warn)
+    assert.equal(warn.severity, 'warning')
+    assert.equal(warn.detector, 'tool_frequency')
+  })
+})
+
+describe('hash helpers', () => {
+  it('produces consistent hashes for same input', () => {
+    assert.equal(hashToolInput({ query: 'test' }), hashToolInput({ query: 'test' }))
+    assert.equal(hashToolOutput('hello world'), hashToolOutput('hello world'))
+  })
+
+  it('produces different hashes for different input', () => {
+    assert.notEqual(hashToolInput({ query: 'a' }), hashToolInput({ query: 'b' }))
+  })
+})

package/src/lib/server/tool-loop-detection.ts

@@ -0,0 +1,260 @@
+/**
+ * Tool loop detection — modelled after OpenClaw's approach.
+ *
+ * Four detectors run on every on_tool_end event:
+ * 1. Generic repeat    — same (name, inputHash) seen N+ times
+ * 2. Polling stall     — repeated poll-like calls with identical output
+ * 3. Ping-pong         — two tools alternating with identical results
+ * 4. Circuit breaker   — absolute cap on identical calls regardless of type
+ *
+ * Each detector returns a severity: 'ok' | 'warning' | 'critical'.
+ * The caller decides what to do (log, inject guidance, abort).
+ */
+
+import { createHash } from 'crypto'
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface ToolCallRecord {
+  name: string
+  inputHash: string
+  outputHash: string
+  /** first 200 chars of output for logging */
+  outputPreview: string
+  timestamp: number
+}
+
+export type LoopSeverity = 'ok' | 'warning' | 'critical'
+
+export interface LoopDetectionResult {
+  severity: LoopSeverity
+  detector: 'generic_repeat' | 'polling_stall' | 'ping_pong' | 'circuit_breaker' | 'tool_frequency'
+  message: string
+}
+
+export interface LoopDetectionThresholds {
+  /** Generic repeat: warn after this many identical (name, input) calls. Default 6. */
+  repeatWarn: number
+  /** Generic repeat: critical after this many. Default 12. */
+  repeatCritical: number
+  /** Polling stall: warn after N poll-like calls with identical output. Default 4. */
+  pollWarn: number
+  /** Polling stall: critical after this many. Default 8. */
+  pollCritical: number
+  /** Ping-pong: how many alternating-pair cycles trigger warning. Default 3. */
+  pingPongWarn: number
+  /** Ping-pong: critical after this many cycles. Default 5. */
+  pingPongCritical: number
+  /** Circuit breaker: absolute cap on any identical call. Default 20. */
+  circuitBreaker: number
+  /** Per-tool frequency: warn after this many calls to the same tool (any input). Default 5. */
+  toolFrequencyWarn: number
+  /** Per-tool frequency: critical after this many calls to the same tool (any input). Default 8. */
+  toolFrequencyCritical: number
+}
+
+const DEFAULT_THRESHOLDS: LoopDetectionThresholds = {
+  repeatWarn: 6,
+  repeatCritical: 12,
+  pollWarn: 4,
+  pollCritical: 8,
+  pingPongWarn: 3,
+  pingPongCritical: 5,
+  circuitBreaker: 20,
+  toolFrequencyWarn: 3,
+  toolFrequencyCritical: 5,
+}
+
+// ---------------------------------------------------------------------------
+// Hash helpers
+// ---------------------------------------------------------------------------
+
+function quickHash(input: string): string {
+  return createHash('sha256').update(input).digest('hex').slice(0, 16)
+}
+
+export function hashToolInput(input: unknown): string {
+  const str = typeof input === 'string' ? input : JSON.stringify(input ?? '')
+  return quickHash(str)
+}
+
+export function hashToolOutput(output: unknown): string {
+  const str = typeof output === 'string' ? output : JSON.stringify(output ?? '')
+  return quickHash(str)
+}
+
+// ---------------------------------------------------------------------------
+// Tracker
+// ---------------------------------------------------------------------------
+
+export class ToolLoopTracker {
+  private history: ToolCallRecord[] = []
+  private thresholds: LoopDetectionThresholds
+
+  constructor(thresholds?: Partial<LoopDetectionThresholds>) {
+    this.thresholds = { ...DEFAULT_THRESHOLDS, ...thresholds }
+  }
+
+  /** Record a completed tool call and run all detectors. */
+  record(name: string, input: unknown, output: unknown): LoopDetectionResult | null {
+    const inputHash = hashToolInput(input)
+    const outputStr = typeof output === 'string' ? output : JSON.stringify(output ?? '')
+    const outputHash = hashToolOutput(output)
+    const record: ToolCallRecord = {
+      name,
+      inputHash,
+      outputHash,
+      outputPreview: outputStr.slice(0, 200),
+      timestamp: Date.now(),
+    }
+    this.history.push(record)
+
+    // Run detectors in severity order (most severe first)
+    return this.checkCircuitBreaker(record)
+      ?? this.checkToolFrequency(record)
+      ?? this.checkGenericRepeat(record)
+      ?? this.checkPollingStall(record)
+      ?? this.checkPingPong()
+      ?? null
+  }
+
+  /** Get the full call history (for diagnostics). */
+  getHistory(): ReadonlyArray<ToolCallRecord> {
+    return this.history
+  }
+
+  /** Total recorded calls. */
+  get size(): number {
+    return this.history.length
+  }
+
+  // -------------------------------------------------------------------------
+  // Detectors
+  // -------------------------------------------------------------------------
+
+  private checkToolFrequency(current: ToolCallRecord): LoopDetectionResult | null {
+    let count = 0
+    for (const r of this.history) {
+      if (r.name === current.name) count++
+    }
+    if (count >= this.thresholds.toolFrequencyCritical) {
+      return {
+        severity: 'critical',
+        detector: 'tool_frequency',
+        message: `Tool "${current.name}" called ${count} times this turn. Excessive repetition — wrap up with available results.`,
+      }
+    }
+    if (count >= this.thresholds.toolFrequencyWarn) {
+      return {
+        severity: 'warning',
+        detector: 'tool_frequency',
+        message: `Tool "${current.name}" called ${count} times. Consider whether more calls are needed.`,
+      }
+    }
+    return null
+  }
+
+  private checkCircuitBreaker(current: ToolCallRecord): LoopDetectionResult | null {
+    const key = `${current.name}:${current.inputHash}`
+    let count = 0
+    for (const r of this.history) {
+      if (`${r.name}:${r.inputHash}` === key) count++
+    }
+    if (count >= this.thresholds.circuitBreaker) {
+      return {
+        severity: 'critical',
+        detector: 'circuit_breaker',
+        message: `Circuit breaker: "${current.name}" called ${count} times with identical input. Halting to prevent runaway.`,
+      }
+    }
+    return null
+  }
+
+  private checkGenericRepeat(current: ToolCallRecord): LoopDetectionResult | null {
+    const key = `${current.name}:${current.inputHash}`
+    let count = 0
+    for (const r of this.history) {
+      if (`${r.name}:${r.inputHash}` === key) count++
+    }
+    if (count >= this.thresholds.repeatCritical) {
+      return {
+        severity: 'critical',
+        detector: 'generic_repeat',
+        message: `Tool "${current.name}" has been called ${count} times with the same input. This appears to be a stuck loop.`,
+      }
+    }
+    if (count >= this.thresholds.repeatWarn) {
+      return {
+        severity: 'warning',
+        detector: 'generic_repeat',
+        message: `Tool "${current.name}" has been called ${count} times with the same input. Consider a different approach.`,
+      }
+    }
+    return null
+  }
+
+  private checkPollingStall(current: ToolCallRecord): LoopDetectionResult | null {
+    // Look for recent sequential calls to the same tool with identical output
+    const recent = this.history.slice(-this.thresholds.pollCritical)
+    const pollRuns = recent.filter(
+      (r) => r.name === current.name && r.outputHash === current.outputHash,
+    )
+    if (pollRuns.length >= this.thresholds.pollCritical) {
+      return {
+        severity: 'critical',
+        detector: 'polling_stall',
+        message: `Polling stall: "${current.name}" returned identical output ${pollRuns.length} times consecutively. The polled resource is not changing.`,
+      }
+    }
+    if (pollRuns.length >= this.thresholds.pollWarn) {
+      return {
+        severity: 'warning',
+        detector: 'polling_stall',
+        message: `Polling stall: "${current.name}" returned identical output ${pollRuns.length} times. The state may not be progressing.`,
+      }
+    }
+    return null
+  }
+
+  private checkPingPong(): LoopDetectionResult | null {
+    const len = this.history.length
+    if (len < 4) return null
+
+    // Check if the last N calls form an A-B-A-B pattern with identical results
+    const last = this.history[len - 1]
+    const prev = this.history[len - 2]
+    if (last.name === prev.name) return null // same tool — not ping-pong
+
+    let cycles = 0
+    for (let i = len - 2; i >= 1; i -= 2) {
+      const a = this.history[i]
+      const b = this.history[i - 1]
+      if (
+        a.name === last.name && a.outputHash === last.outputHash
+        && b.name === prev.name && b.outputHash === prev.outputHash
+      ) {
+        cycles++
+      } else {
+        break
+      }
+    }
+
+    if (cycles >= this.thresholds.pingPongCritical) {
+      return {
+        severity: 'critical',
+        detector: 'ping_pong',
+        message: `Ping-pong: "${prev.name}" and "${last.name}" are alternating with identical results (${cycles} cycles). Breaking the loop.`,
+      }
+    }
+    if (cycles >= this.thresholds.pingPongWarn) {
+      return {
+        severity: 'warning',
+        detector: 'ping_pong',
+        message: `Ping-pong: "${prev.name}" and "${last.name}" may be stuck in an alternating loop (${cycles} cycles).`,
+      }
+    }
+    return null
+  }
+}

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,271 @@
+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',
+  walletInspect: 'wallet.inspect',
+  walletExecute: 'wallet.execute',
+} 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', 'update', 'updates', 'breaking', 'developments', 'keep watching', 'watch for', 'watching for', 'monitor', 'track', "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', 'send file', 'send a 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)]))
+}