Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript
15.8 KB
Raw Blame
import type { McpTool } from '../types'
import type { InternalToolDefinition, InternalToolResult } from '../workflow/types'

/**
 * Read-only meta-tools for dynamic tool discovery (Phase F2 of the
 * dynamic-tool-loading "stable bridge" design).
 *
 * Both tools are stateless and query the live catalog on demand via a
 * `getCatalog` provider. In production it is bound to `McpManager.getAllTools()`
 * and, when native `auto` is on (#1003), also to the non-bridge native
 * definitions under the `native` pseudo-server (see `NativeToolRegistry`). They
 * never mutate session state and never advertise catalog tools into the
 * `tools[]` array — the whole point of the design is to keep schemas OUT of
 * the prompt prefix.
 *
 *   - `clerum__tool_search`   → ranks tools by keyword over name+description,
 *                               returns name/server/description, NEVER schemas
 *                               (Critical Detail #4).
 *   - `clerum__tool_describe` → returns the full JSON schema for ONE tool,
 *                               on demand (Critical Detail #5).
 *
 * The env/catalog provider is supplied by the caller so this module stays
 * decoupled from McpManager wiring (same pattern as getCapabilitiesTool).
 */
export type CatalogProvider = () => McpTool[]

/** The 3 dynamic-tool-loading bridge tools. They are native and must never be
 * the TARGET of `clerum__tool_call` (LOCKED #11 — no recursion), nor appear in
 * the discovery catalog, nor be hidden by native `auto` (#1003). */
export const BRIDGE_TOOL_NAMES: ReadonlySet<string> = new Set([
  'clerum__tool_search',
  'clerum__tool_describe',
  'clerum__tool_call',
])

/**
 * #1003 — whether the bridge also serves native tools (native `auto`). When
 * false, every model-visible text below is exactly the pre-#1003 text.
 */
export interface BridgeToolOptions {
  nativeTargets: boolean
}

/** Default cap for tool_search results. The model asks for one schema at a
 * time via tool_describe, so the search result stays a small, schema-free
 * index even with a 290-tool catalog. */
const DEFAULT_SEARCH_LIMIT = 20
const MAX_SEARCH_LIMIT = 50
// Bound context per discovery result, not the size of the approved catalog.
const MAX_SEARCH_BYTES = 32 * 1024
const MAX_DESCRIPTION_BYTES = 512

export interface ToolSearchResultEntry {
  name: string
  server: string
  description: string
}

export interface ToolSearchResponse {
  /** Total number of tools that matched the query, BEFORE the `limit` slice. */
  found: number
  /** Number of tools actually returned (`results.length`); `<= found`. */
  returned: number
  results: ToolSearchResultEntry[]
  /** Continue with the same query/filter and this offset; absent on the last page. */
  nextOffset?: number
  /** Optional hint set when the query was empty/whitespace-only. */
  message?: string
}

export interface ToolDescribeResponse {
  found: boolean
  name?: string
  server?: string
  description?: string
  parameters?: Record<string, unknown>
}

/**
 * Derive the logical server name from a prefixed tool name. MCP tools are
 * prefixed `${server}__${tool}` (double underscore). Tools without a `__`
 * separator are native and reported as `"native"`.
 *
 * This is only a FALLBACK: `McpTool.serverName` is the authoritative source
 * and is preserved through `getAllTools()`. Prefer `serverNameOf` below,
 * which reads `serverName` and string-splits only when it is absent. Parsing
 * the name truncates servers whose own name contains `__`.
 */
export function serverPrefixOf(name: string): string {
  const idx = name.indexOf('__')
  if (idx <= 0) return 'native'
  return name.slice(0, idx)
}

/**
 * Authoritative server name for a catalog tool: the `serverName` field set by
 * the MCP client, falling back to parsing the prefixed name only when it is
 * missing (e.g. native tools, which report `"native"`).
 */
export function serverNameOf(tool: McpTool): string {
  return tool.serverName || serverPrefixOf(tool.name)
}

function tokenize(text: string): string[] {
  return text
    .toLowerCase()
    .split(/[^a-z0-9]+/)
    .filter(t => t.length > 0)
}

function compactDescription(text: string): string {
  if (Buffer.byteLength(text, 'utf8') <= MAX_DESCRIPTION_BYTES) return text
  let result = ''
  let bytes = 0
  for (const character of text) {
    const size = Buffer.byteLength(character, 'utf8')
    if (bytes + size > MAX_DESCRIPTION_BYTES - 3) break
    result += character
    bytes += size
  }
  return `${result}…`
}

function searchOffset(value: unknown): number {
  if (value === undefined) return 0
  if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0) {
    throw new Error('offset must be a non-negative safe integer')
  }
  return value
}

/**
 * Simple, dependency-free keyword overlap scorer. Counts how many distinct
 * query tokens appear (as substrings of tokens) in the tool's name+description.
 * Name matches are weighted slightly higher than description matches so a
 * query that hits the tool name ranks above one that only hits the prose.
 * No embeddings, no external index — keyword/overlap as mandated by the spec.
 */
function scoreTool(queryTokens: string[], name: string, description: string): number {
  if (queryTokens.length === 0) return 0
  const nameTokens = new Set(tokenize(name))
  const descTokens = new Set(tokenize(description))
  let score = 0
  for (const qt of queryTokens) {
    let matched = false
    for (const nt of nameTokens) {
      if (nt.includes(qt)) {
        score += 2
        matched = true
        break
      }
    }
    if (matched) continue
    for (const dt of descTokens) {
      if (dt.includes(qt)) {
        score += 1
        break
      }
    }
  }
  return score
}

export function buildToolSearchResponse(
  catalog: McpTool[],
  query: string,
  options: { server?: string; limit?: number; offset?: number; enumerate?: boolean }
): ToolSearchResponse {
  const offset = searchOffset(options.offset)
  const queryTokens = tokenize(query)
  const serverFilter = options.server?.trim()
  // Fall back to the default for non-finite limits (e.g. NaN) — `slice(0, NaN)`
  // would otherwise silently return zero results.
  const requestedLimit = Number.isFinite(options.limit)
    ? (options.limit as number)
    : DEFAULT_SEARCH_LIMIT
  const limit = Math.min(Math.max(1, Math.floor(requestedLimit)), MAX_SEARCH_LIMIT)

  const scored: Array<{ entry: ToolSearchResultEntry; score: number }> = []
  for (const tool of catalog) {
    const server = serverNameOf(tool)
    if (serverFilter && server !== serverFilter) continue
    const description = tool.description ?? ''
    const score = scoreTool(queryTokens, tool.name, description)
    if (score <= 0 && !(options.enumerate === true && queryTokens.length === 0)) continue
    scored.push({
      entry: { name: tool.name, server, description: compactDescription(description) },
      score,
    })
  }

  scored.sort((a, b) => {
    if (b.score !== a.score) return b.score - a.score
    // Code-point ordering stays identical across runtime locales.
    return a.entry.name < b.entry.name ? -1 : a.entry.name > b.entry.name ? 1 : 0
  })

  if (offset > scored.length)
    throw new Error('offset exceeds matching catalog; restart at offset 0')
  const payload: ToolSearchResponse = { found: scored.length, returned: 0, results: [] }
  for (const { entry } of scored.slice(offset, offset + limit)) {
    payload.results.push(entry)
    payload.returned = payload.results.length
    payload.nextOffset =
      offset + payload.returned < scored.length ? offset + payload.returned : undefined
    if (Buffer.byteLength(JSON.stringify(payload), 'utf8') > MAX_SEARCH_BYTES) {
      payload.results.pop()
      payload.returned = payload.results.length
      if (payload.returned === 0)
        throw new Error('Tool identifier exceeds discovery page byte budget')
      payload.nextOffset = offset + payload.returned
      break
    }
  }
  return payload
}

export function buildToolDescribeResponse(catalog: McpTool[], name: string): ToolDescribeResponse {
  const target = name?.trim()
  if (!target) return { found: false }
  const tool = catalog.find(t => t.name === target)
  if (!tool) return { found: false }
  return {
    found: true,
    name: tool.name,
    server: serverNameOf(tool),
    description: tool.description ?? '',
    parameters: tool.inputSchema,
  }
}

/**
 * `clerum__tool_search` — read-only, stateless keyword search over the
 * catalog. Returns name/server/description only; NEVER schemas (Critical
 * Detail #4 — schemas are exactly the prefix cost the bridge avoids).
 * With `nativeTargets` the `server` filter also accepts the `native`
 * pseudo-server (#1003); otherwise the parameter text is the pre-#1003 text.
 */
export function createToolSearchTool(
  getCatalog: CatalogProvider,
  options: BridgeToolOptions
): InternalToolDefinition {
  return {
    name: 'clerum__tool_search',
    description:
      'Search the full catalog of available tools by keyword. Returns a ' +
      'lightweight index of matching tools (name, server, description) — NOT ' +
      'their input schemas. Use this to discover tools that are not listed ' +
      'directly, then call `clerum__tool_describe` to fetch the schema of one. ' +
      '`found` is the total number of matches; `returned` may be smaller when ' +
      'bounded by count and bytes. Prefer precise queries; use `nextOffset` as ' +
      '`offset` with the same query and server to continue. Set `enumerate: true` ' +
      'with an empty query to list a page when keywords are unknown. Pages read ' +
      'the live catalog: restart at offset 0 after connections or permissions ' +
      'change. Reuse a known schema instead of repeatedly searching/describing.',
    parameters: {
      type: 'object',
      properties: {
        query: { type: 'string', description: 'Keywords to search for.' },
        server: {
          type: 'string',
          description: options.nativeTargets
            ? 'Optional: restrict results to a single MCP server name, or `native` for internal tools.'
            : 'Optional: restrict results to a single MCP server name.',
        },
        limit: {
          type: 'number',
          description: `Optional: max results to return (default ${DEFAULT_SEARCH_LIMIT}, capped at ${MAX_SEARCH_LIMIT}).`,
        },
        offset: {
          type: 'integer',
          minimum: 0,
          description:
            'Optional: nextOffset from the preceding page, default 0. Keep query and server unchanged.',
        },
        enumerate: {
          type: 'boolean',
          description:
            'Optional: explicitly list tools for an empty query. Prefer keyword search for a specific task.',
        },
      },
      required: ['query'],
      additionalProperties: false,
    },
    async execute(args: Record<string, unknown>): Promise<InternalToolResult> {
      try {
        // Lenient at runtime by design: a missing/non-string query coerces to
        // '' and yields an empty result rather than failing the call, mirroring
        // tool_describe's empty-name handling.
        const query = typeof args.query === 'string' ? args.query : ''
        const server = typeof args.server === 'string' ? args.server : undefined
        const limit = typeof args.limit === 'number' ? args.limit : undefined
        const offset = searchOffset(args.offset)
        if (args.enumerate !== undefined && typeof args.enumerate !== 'boolean') {
          throw new Error('enumerate must be a boolean')
        }
        // Empty/whitespace-only query: return an informative result rather than a
        // bare `{ found: 0 }`, which reads like "no tools exist" to the model.
        if (query.trim().length === 0 && args.enumerate !== true) {
          const payload: ToolSearchResponse = {
            found: 0,
            returned: 0,
            results: [],
            message: 'Empty query — provide keywords to search the tool catalog.',
          }
          return { success: true, content: JSON.stringify(payload) }
        }
        const payload = buildToolSearchResponse(getCatalog(), query, {
          server,
          limit,
          offset,
          enumerate: args.enumerate === true,
        })
        return { success: true, content: JSON.stringify(payload) }
      } catch (err) {
        return { success: false, error: err instanceof Error ? err.message : String(err) }
      }
    },
  }
}

/**
 * `clerum__tool_describe` — read-only, stateless. Returns the full JSON
 * schema for ONE tool on demand. An unknown name yields `{ found: false }`
 * rather than failing the call (Phase F2.2).
 */
export function createToolDescribeTool(getCatalog: CatalogProvider): InternalToolDefinition {
  return {
    name: 'clerum__tool_describe',
    description:
      'Fetch the full input schema for a single tool by its exact name (as ' +
      'returned by `clerum__tool_search`). Returns `{ found: false }` for an ' +
      'unknown name. Use the schema to build a correct call.',
    parameters: {
      type: 'object',
      properties: {
        name: { type: 'string', description: 'Exact tool name to describe.' },
      },
      required: ['name'],
      additionalProperties: false,
    },
    async execute(args: Record<string, unknown>): Promise<InternalToolResult> {
      try {
        const name = typeof args.name === 'string' ? args.name : ''
        const payload = buildToolDescribeResponse(getCatalog(), name)
        return { success: true, content: JSON.stringify(payload) }
      } catch (err) {
        return { success: false, error: err instanceof Error ? err.message : String(err) }
      }
    },
  }
}

/**
 * `clerum__tool_call` — the execution bridge for deferred MCP tools (Phase F3.2)
 * and, with `nativeTargets` (native `auto`, #1003), for native tools too.
 *
 * IMPORTANT: this `execute` is a SAFETY NET only. The real handling happens in
 * `executeToolCalls` (`core/orchestration/toolUseLoopToolBatch.ts`), which
 * intercepts `clerum__tool_call` at the TOP of the per-call loop, BEFORE the
 * approval/validation gate, unwraps `{ name, arguments }`, and rewrites the
 * call to a synthetic call against the REAL tool so approval/validation run
 * against the real name (LOCKED #8). The tool is still registered as a native so
 * it appears in `tools[]` and in `nativeNames`. If `execute` is ever reached
 * (the intercept did not fire), we return an error rather than silently doing
 * nothing — that would be a bug, not a normal path.
 */
export function createToolCallTool(options: BridgeToolOptions): InternalToolDefinition {
  return {
    name: 'clerum__tool_call',
    description: options.nativeTargets
      ? 'Invoke a tool discovered via `clerum__tool_search` / `clerum__tool_describe` ' +
        'by its exact name. Pass the target tool name and its arguments. Use this ' +
        'for tools that are not listed directly, including internal tools; tools ' +
        'listed directly are called by their own name.'
      : 'Invoke a tool discovered via `clerum__tool_search` / `clerum__tool_describe` ' +
        'by its exact name. Pass the target tool name and its arguments. Use this ' +
        'for tools that are not listed directly; native tools are called directly.',
    parameters: {
      type: 'object',
      properties: {
        name: {
          type: 'string',
          description: 'Exact name of the tool to invoke (as returned by tool_search).',
        },
        arguments: {
          type: 'object',
          description: 'Arguments object for the target tool, matching its schema.',
          additionalProperties: true,
        },
      },
      required: ['name', 'arguments'],
      additionalProperties: false,
    },
    async execute(): Promise<InternalToolResult> {
      // Reaching here means the batch-loop intercept did not run. Fail loudly
      // rather than silently no-op'ing.
      return {
        success: false,
        error:
          'clerum__tool_call must be invoked through the dynamic-tools bridge; ' +
          'direct execution is not supported.',
      }
    },
  }
}