Skip to content

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

TypeScript
25.0 KB
Raw Blame
import * as fs from 'fs'
import * as path from 'path'
import type { CronScheduler } from '../../agent/cronScheduler'
import { createGetCapabilitiesTool } from '../../capabilities/getCapabilitiesTool'
import {
  BRIDGE_TOOL_NAMES,
  createToolCallTool,
  createToolDescribeTool,
  createToolSearchTool,
} from '../../capabilities/toolCatalogTools'
import {
  buildGfsCopyTools,
  buildGfsReadTools,
  buildGfsWriteTools,
  referencedFilePins,
} from '../../internalTools/gfs'
import { createGfscClient, getGfsToolScopes } from '../../internalTools/gfsClient'
import type { GfsDownloadStore } from '../../internalTools/gfsDownloadStore'
import type { LlmProvider } from '../../llm/registryCore'
import type { McpManager } from '../../mcp/manager'
import type { IncomingMessage } from '../../server'
import type { McpTool } from '../../types'
import { checkToolArguments } from '../../workflow/argumentGate'
import { resolveInternalTools } from '../../workflow/internalTools'
import { boilerplateTexts } from '../../workflow/officeBoilerplate'
import { printedForms } from '../../workflow/toolText'
import type { InternalToolDefinition } from '../../workflow/types'
import {
  type CallerOutputLookup,
  callerOutputUnavailableMessage,
  resolveCallerOutputDir,
} from '../../workspace/callerOutputs'
import { ScopedWorkspace } from '../../workspace/scopedWorkspace'
import type { Workspace } from '../../workspace/service'
import type { AttachmentReadLedger } from '../attachments/attachmentReadBudget'
import { type ExecutionContext, NativeToolConfig, Tool, ToolRegistry } from '../interfaces'
import { BasicSafety } from '../safety/safety'
import type { SessionSearchService } from '../sessionSearch'
import type { SpilloverStorage } from '../spillover'
import { ToolDefinition, ToolOutput } from '../types'
import { AttachmentReadTool } from './attachmentRead'
import { CronManageTool } from './cronManage'
import { FileReadTool } from './fileRead'
import { FileWriteTool } from './fileWrite'
import { buildGeneratedArtifactAttachment } from './generatedArtifactAttachments'
import { HttpRequestTool } from './httpRequest'
import { JsonTransformTool } from './jsonTransform'
import {
  MemorySearchTool,
  MemoryTreeTool,
  PersistentMemoryReadTool,
  PersistentMemoryWriteTool,
} from './memory'
import { SessionSearchTool } from './sessionSearch'
import { ShellTool } from './shell'
import { SpilloverReadTool } from './spilloverRead'
import { SystemInfoTool } from './systemInfo'
import { createWorkflowTools } from './workflow'
import type { WorkflowCallerContext } from './workflowShared'

const CHAT_HIDDEN_INTERNAL_TOOL_NAMES = new Set([
  'clerum__list_workflows',
  'clerum__read_workflow',
  'clerum__trigger_workflow',
])

/** Tools that write a document into the caller's outputs directory. */
const GENERATOR_PREFIX = 'clerum__generate_'

/** Whether `file`, links resolved, sits directly in `dir`. */
function directlyInside(file: string, dir: string): boolean {
  try {
    return fs.realpathSync(path.dirname(file)) === dir && !fs.lstatSync(file).isSymbolicLink()
  } catch {
    return false
  }
}

/** Adapter: wraps an InternalToolDefinition as a native Tool for use in chat mode. */
class InternalToolAdapter implements Tool {
  constructor(
    private readonly def: InternalToolDefinition,
    private readonly outputDir: string,
    private readonly attachmentOptions: {
      maxBytes: number
      secretEntriesProvider?: () => Array<{ name: string; value: string }>
    },
    /**
     * For a generator: the caller's own outputs directory, verified on each
     * call (callerOutputs.ts). It replaces `outputDir`; when it cannot be
     * verified the call writes nothing.
     */
    private readonly callerOutputs?: () => CallerOutputLookup
  ) {}
  name(): string {
    return this.def.name
  }
  description(): string {
    return this.def.description
  }
  parametersSchema(): Record<string, unknown> {
    return this.def.parameters
  }
  requiresSanitization(): boolean {
    return false
  }
  requiresApproval(): boolean {
    return false
  }
  traceDescriptor() {
    return { kind: 'internal_tool' as const, sourceRef: 'mcp-host' }
  }

  joinsAbortSettlement(): boolean {
    return this.def.name === 'clerum__gfs_download' || this.def.name === 'clerum__gfs_read'
  }
  async execute(params: Record<string, unknown>, context?: ExecutionContext): Promise<ToolOutput> {
    const start = Date.now()
    // The schema check a workflow step runs, before anything is resolved or
    // written: a call it rejects creates no folder, file or attachment.
    const checked = checkToolArguments(this.def, params)
    if (!checked.ok) {
      return { content: `Error: ${checked.error}`, duration_ms: Date.now() - start, is_error: true }
    }
    let outputDir = this.outputDir
    if (this.callerOutputs) {
      const resolved = this.callerOutputs()
      if (!('dir' in resolved)) {
        const code = 'failureCode' in resolved ? resolved.failureCode : 'ENOENT'
        return {
          content: `Error: ${callerOutputUnavailableMessage(code)}`,
          duration_ms: Date.now() - start,
          is_error: true,
        }
      }
      outputDir = resolved.dir
    }
    try {
      const result = await this.def.execute(checked.input, outputDir, {
        signal: context?.signal,
        timeoutMs: context?.timeoutMs,
        visualInput: context?.visualInput,
      })
      // Query-style tools (e.g. clerum__get_capabilities) return text via
      // result.content; file-generation tools return an artifact and we
      // synthesize a message from it. Errors take precedence over both.
      const content = result.success
        ? (result.content ??
          `File generated: ${result.artifact?.name ?? 'output'} (${
            result.artifact?.format ?? 'unknown'
          })`)
        : `Error: ${result.error ?? 'Unknown error'}`
      // The file must be where the caller's folder is now; a folder swapped
      // during the call must not route the file to anyone else.
      if (
        this.callerOutputs &&
        result.success &&
        result.artifact &&
        !directlyInside(result.artifact.path, outputDir)
      ) {
        return {
          content: `Error: ${callerOutputUnavailableMessage('EEXIST')}`,
          duration_ms: Date.now() - start,
          is_error: true,
        }
      }
      const format = result.success ? result.artifact?.format : undefined
      // Office packages carry the generator's own text; a protected value
      // found only there is left to the payload check (officeBoilerplate).
      const packageBoilerplate =
        (format === 'docx' || format === 'xlsx' || format === 'pptx') &&
        (this.attachmentOptions.secretEntriesProvider?.().length ?? 0) > 0
          ? await boilerplateTexts(format)
          : undefined
      const attachment =
        result.success && result.artifact
          ? buildGeneratedArtifactAttachment({
              sourceTool: this.def.name,
              artifact: result.artifact,
              outputDir,
              maxBytes: this.attachmentOptions.maxBytes,
              // The file shows the arguments as the generator prints them, so a
              // secret split by a tag or an escape is checked whole too, and
              // anything else it shows that they do not spell (chart labels).
              sourcePayload: [params, printedForms(params), result.shownText ?? []],
              secretEntriesProvider: this.attachmentOptions.secretEntriesProvider,
              packageBoilerplate,
              shownText: result.shownText,
              writtenSha256: result.writtenSha256,
            })
          : null
      const images = result.success
        ? (result.images?.map(image => ({
            id: `gfs-${image.source.resourceId}-${image.source.version}`,
            kind: 'image' as const,
            mimeType: image.mimeType,
            encoding: 'base64' as const,
            dataBase64: image.dataBase64,
            filename: image.source.name,
            width: image.width,
            height: image.height,
            sizeBytes: image.sizeBytes,
            sourceTool: this.def.name,
            visualSource: image.source,
          })) ?? [])
        : []
      const attachments = [...(attachment ? [attachment] : []), ...images]
      return {
        content,
        duration_ms: Date.now() - start,
        is_error: !result.success,
        attachments: attachments.length ? attachments : undefined,
      }
    } catch (err) {
      return {
        content: `Error: ${err instanceof Error ? err.message : String(err)}`,
        duration_ms: Date.now() - start,
        is_error: true,
      }
    }
  }
}

/**
 * Registry for all native tools.
 *
 * Native tools use plain names (no serverName__ prefix).
 * This is merged with MCP tools via CompositeToolRegistry in Phase 4.
 * Resolution order: native first (Risk 3.5.6).
 */
export class NativeToolRegistry implements ToolRegistry {
  private readonly tools = new Map<string, Tool>()

  constructor(
    config: NativeToolConfig,
    conversationId: string,
    cronScheduler?: CronScheduler,
    sourceMessage?: IncomingMessage,
    workspace?: Workspace,
    dynamicEnvProvider?: () => Record<string, string>,
    // Order note: both `workflowCallerContextOverride` and `attachmentOptions`
    // keep dev's positions (slots 7 and 8) so dev's positional call sites stay
    // valid; the session-persistence params (spillover/sessionSearch) are
    // appended after them (slots 9/10). No call site passes spillover/sessionSearch
    // positionally except taskExecutor, which is updated to match.
    workflowCallerContextOverride?: WorkflowCallerContext | null,
    attachmentOptions?: {
      maxBytes?: number
      secretEntriesProvider?: () => Array<{ name: string; value: string }>
      /**
       * C15/C16 — the turn-owned read ledger. Required (with
       * `contextWindowTokens`) whenever a file attachment registers
       * `clerum__attachment_read`: the tool refuses to run without an exact
       * measurement and a bound, so a missing ledger must fail here, at
       * registration, instead of mid-turn.
       */
      ledger?: AttachmentReadLedger
      /** C15/C16 — effective context window the ledger derives its envelope from. */
      contextWindowTokens?: number
    },
    spilloverStorage?: SpilloverStorage,
    sessionSearchService?: SessionSearchService,
    // F2 (dynamic-tool-loading): the MCP manager backs the read-only
    // discovery meta-tools (clerum__tool_search / clerum__tool_describe).
    // Appended as a trailing optional dep so existing positional call sites
    // stay valid; only taskExecutor passes it.
    mcpManager?: McpManager,
    // F3/F4 (dynamic-tool-loading) + #1003: which concerns need the 3 bridge
    // tools. `mcpDiscovery` is the MCP presentation decision (Codex/Grok mode
    // or the legacy flag) and only counts when an McpManager is wired;
    // `nativeDiscovery` is native `auto`, which needs the bridge even without
    // MCP. With both false nothing is registered, so tools[] is byte-identical
    // to a host without discovery and no discovery guidance is emitted (it
    // gates on clerum__tool_search). Constant per host/session, so it is
    // cache-safe. Trailing optional; only taskExecutor passes it.
    discovery?: { mcpDiscovery: boolean; nativeDiscovery: boolean },
    // §13 (stateless agents): the ACTIVE LLM provider steers shell_exec
    // credential-slot stripping — only the active provider's credential env
    // var survives into the child env. Appended as a trailing optional so
    // existing positional call sites stay valid; only taskExecutor passes it.
    activeLlmProvider?: LlmProvider,
    gfsDownload?: {
      /** Omitted when the Host has no download store or it is unavailable; delivery then fails closed. */
      store?: GfsDownloadStore
      /** True only for attended, policy-eligible, healthy workspace delivery. */
      deliveryAvailable: boolean
      callerIdentity: string
      callerWorkspacePath?: string
      retentionOwnerId?: string
    },
    // The caller's verified root (`<host>/users/<key>`). The document
    // generators write under its reserved outputs directory; without it they
    // refuse to write, never falling back to a folder shared by the Host.
    // Trailing optional; only taskExecutor passes it.
    callerOutputRoot?: string
  ) {
    // A Host-owned GFS store establishes a trusted caller binding even when
    // memory is disabled. In that mode file tools never fall back to the shared
    // Host root; if the caller root cannot be verified they are omitted.
    // Without that Host store, preserve the legacy memory/shared-root behavior.
    const fileToolsRoot =
      gfsDownload !== undefined
        ? gfsDownload.callerWorkspacePath
        : workspace instanceof ScopedWorkspace
          ? workspace.userRootPath
          : config.workspacePath
    if (fileToolsRoot !== undefined) this.register(new FileReadTool(fileToolsRoot))
    // NOTE (residual): FileWriteTool writes via raw fs and bypasses
    // WorkspaceService.write → scanWriteContent. So a `file_write` to
    // `daily/*` / `MEMORY.md` is NOT injection-scanned. It is scoped to the
    // per-user root (F1c), and neither MEMORY.md nor private memory feed the
    // system prompt (F5: memory is read via tools, not injected) — so the blast
    // radius is self-injection of the user's own daily snapshot (low). Closing
    // it (route memory/daily-class file_write through WorkspaceService) is future
    // hardening, independent of F5.
    if (fileToolsRoot !== undefined) this.register(new FileWriteTool(fileToolsRoot))
    // A Host-owned GFS store binds the shell to the verified caller root. The
    // shell never calls the store itself (#1019): it only re-verifies that the
    // caller root is still canonical before each command.
    this.register(
      new ShellTool(
        gfsDownload ? gfsDownload.callerWorkspacePath : config.workspacePath,
        config.shellTimeout,
        config.envAllowlist,
        dynamicEnvProvider,
        activeLlmProvider,
        gfsDownload !== undefined
      )
    )
    this.register(new HttpRequestTool(config.httpAllowlist))
    this.register(new SystemInfoTool())
    this.register(new JsonTransformTool())

    // Memory tools: persistent (filesystem), requires workspace.
    if (workspace) {
      this.register(new MemorySearchTool(workspace))
      this.register(new PersistentMemoryWriteTool(workspace))
      this.register(new PersistentMemoryReadTool(workspace))
      this.register(new MemoryTreeTool(workspace))
    }

    if (cronScheduler) {
      this.register(
        new CronManageTool(cronScheduler, sourceMessage, config.statelessLifecycle === true)
      )
    }

    const gfsEnv = {
      get: (key: string): string | undefined => process.env[key],
    }
    const gfsScopes = getGfsToolScopes(gfsEnv)
    if (gfsScopes && gfsScopes.size > 0) {
      const gfsClient = createGfscClient(gfsEnv, { maxRetryWaitMs: config.toolTimeout })
      const gfsTools = [
        ...(gfsScopes.has('gfs.read')
          ? buildGfsReadTools(gfsClient, {
              referencedFiles: referencedFilePins(sourceMessage?.fileReferenceResolutions),
              downloadStore: gfsDownload?.deliveryAvailable ? gfsDownload.store : undefined,
              callerIdentity: gfsDownload?.callerIdentity,
              callerWorkspacePath: gfsDownload?.callerWorkspacePath,
              retentionOwnerId: gfsDownload?.retentionOwnerId,
            })
          : []),
        ...(gfsScopes.has('gfs.write') ? buildGfsWriteTools(gfsClient) : []),
        ...(gfsScopes.has('gfs.read') && gfsScopes.has('gfs.write')
          ? buildGfsCopyTools(gfsClient)
          : []),
      ]
      for (const tool of gfsTools) {
        // GFS tools write no artifact, so they get no output directory.
        this.register(new InternalToolAdapter(tool, '', { maxBytes: 52_428_800 }))
      }
    }

    // T1.5 — `clerum__spillover_read` reads back blobs persisted out-of-band
    // by `executeSingleTool`. Only registered when the host wires a real
    // `SpilloverStorage` (i.e. spillover feature is enabled).
    if (spilloverStorage) {
      this.register(new SpilloverReadTool(spilloverStorage))
    }

    // T3.1 — `clerum__session_search` lets the LLM recall past messages of
    // the same user. Requires both a `SessionSearchService` (needs SQLite
    // store + FTS5) AND a `sourceMessage` so `userId` is derivable
    // server-side. Cron-triggered turns without an origin message do not
    // get the tool — same gating as `CronManageTool`.
    if (sessionSearchService && sourceMessage) {
      this.register(new SessionSearchTool(sessionSearchService, sourceMessage))
    }

    // #666 — `clerum__attachment_read` reads the `kind:'file'` attachments of
    // the message that started this turn. Only registered when there is one.
    if (sourceMessage?.attachments?.some(a => a.kind === 'file')) {
      const maxBytes = config.attachmentTextReadMaxBytes
      if (maxBytes === undefined) {
        throw new Error(
          'NativeToolConfig.attachmentTextReadMaxBytes is required for file attachments'
        )
      }
      const ledger = attachmentOptions?.ledger
      const contextWindowTokens = attachmentOptions?.contextWindowTokens
      if (!ledger || contextWindowTokens === undefined) {
        throw new Error(
          'NativeToolConfig attachment read wiring requires a turn ledger and contextWindowTokens for file attachments'
        )
      }
      // The tool declares itself spillover-exempt: a page is bounded by
      // `maxBytes`, so the loop ships it inline whether or not this turn has
      // spillover storage (#678).
      // Pages are redacted against the whole text with the same rules and
      // ConfigStore secrets the loop's tool-output sanitizer applies.
      const redactor = new BasicSafety(attachmentOptions?.secretEntriesProvider)
      this.register(
        new AttachmentReadTool(sourceMessage, maxBytes, { contextWindowTokens, ledger, redactor })
      )
    }

    const envGetter = (key: string): string | undefined => {
      const fromStore = dynamicEnvProvider?.()[key]
      if (typeof fromStore === 'string' && fromStore.length > 0) return fromStore
      return process.env[key]
    }

    // Broker URL/token come from pod env, not mutable Host ConfigStore env.
    const workflowEnvGetter = (key: string): string | undefined => process.env[key]

    if (
      workflowEnvGetter('MCP_HOST_GATEWAY_URL') &&
      (workflowEnvGetter('MCP_HOST_WORKFLOW_CONTROL_TOKEN_FILE') ||
        workflowEnvGetter('MCP_HOST_WORKFLOW_CONTROL_TOKEN'))
    ) {
      const targetUserId = sourceMessage?.channelType === 'rpc' ? sourceMessage.sender.trim() : ''
      const targetTeamId =
        sourceMessage?.channelType === 'rpc' && typeof sourceMessage.metadata?.teamId === 'string'
          ? sourceMessage.metadata.teamId.trim()
          : ''
      const sourceConversationId =
        sourceMessage?.channelType === 'rpc' && typeof sourceMessage.threadId === 'string'
          ? sourceMessage.threadId.trim()
          : ''
      const sourceMessageContent = sourceMessage?.content || ''
      const sourceMessageId =
        sourceMessage?.channelType === 'rpc' && typeof sourceMessage.messageId === 'string'
          ? sourceMessage.messageId.trim()
          : ''
      const rpcWorkflowCallerContext =
        targetUserId || targetTeamId
          ? {
              ...(targetUserId ? { targetUserId } : {}),
              ...(targetTeamId ? { targetTeamId } : {}),
              ...(sourceConversationId ? { conversationId: sourceConversationId } : {}),
              originChannelType: 'rpc' as const,
              ...(sourceMessageId ? { sourceMessageId } : {}),
              ...(sourceMessageContent ? { sourceMessageContent } : {}),
            }
          : null
      const workflowCallerContext =
        workflowCallerContextOverride === undefined
          ? rpcWorkflowCallerContext
          : workflowCallerContextOverride
      const canExposeWorkflowTools =
        !sourceMessage || sourceMessage.channelType === 'rpc' || Boolean(workflowCallerContext)
      if (canExposeWorkflowTools) {
        for (const tool of createWorkflowTools({
          getEnv: workflowEnvGetter,
          workflowCallerContext,
        })) {
          this.register(tool)
        }
      }
    }

    // Register internal file-generation/context tools. Workflow recipe control is exposed
    // through workflow_* tools in chat mode so Desktop-owned user/team context can stay hidden.
    // Only the generators write files, each into the caller's own folder;
    // the other internal tools take no output directory.
    const outputDir = ''
    const callerOutputs = (): CallerOutputLookup =>
      callerOutputRoot
        ? resolveCallerOutputDir(callerOutputRoot, { create: true })
        : { failureCode: 'ENOENT' }
    const resolvedAttachmentOptions = {
      maxBytes: attachmentOptions?.maxBytes ?? 52_428_800,
      secretEntriesProvider: attachmentOptions?.secretEntriesProvider,
    }
    // #592: resolveInternalTools() drops the clerum__context_files_* tools when no
    // SharedFileSystem is mounted (Context references none, or this is a recipe
    // runtime that can't mount SFS at all) so the agent never sees dead tools.
    for (const tool of resolveInternalTools()) {
      if (CHAT_HIDDEN_INTERNAL_TOOL_NAMES.has(tool.name)) continue
      this.register(
        new InternalToolAdapter(
          tool,
          outputDir,
          resolvedAttachmentOptions,
          tool.name.startsWith(GENERATOR_PREFIX) ? callerOutputs : undefined
        )
      )
    }

    // clerum__get_capabilities is a query-style internal tool that exposes
    // presence booleans + static hints to the LLM. Routes through
    // ConfigStore via dynamicEnvProvider when available; falls back to
    // process.env when no provider is supplied (e.g. dev mode).
    this.register(
      new InternalToolAdapter(
        createGetCapabilitiesTool(envGetter),
        outputDir,
        resolvedAttachmentOptions
      )
    )

    // F2/F3/F4 (dynamic-tool-loading): read-only discovery meta-tools + the
    // execution bridge. They query the live catalog on demand and never put
    // schemas into the announced tools[] array.
    // Registered when MCP discovery needs them (an McpManager is wired — the
    // tool-name listing registry in main.ts and tests omit it — AND the MCP
    // presentation enables the bridge; LOCKED #5: default OFF) or when native
    // `auto` needs them (#1003; no McpManager required). Otherwise none of
    // these 3 tools are registered, so tools[] is byte-identical to today and
    // the presence-gated discovery guidance is not emitted by either prompt path.
    const mcpDiscovery = Boolean(mcpManager && discovery?.mcpDiscovery)
    const nativeDiscovery = discovery?.nativeDiscovery === true
    if (mcpDiscovery || nativeDiscovery) {
      // Single catalog. Without native discovery it is exactly the MCP catalog.
      // With it (#1003), every non-bridge native is appended under the `native`
      // pseudo-server so a deferred native can be searched and described, and
      // MCP entries whose name collides with ANY native (bridge tools included)
      // are dropped, because the registry routes such a name to the native.
      // Read lazily: desktop tools are registered after construction and MCP
      // servers connect late.
      const getCatalog = (): McpTool[] => {
        const mcpTools = mcpManager?.getAllTools() ?? []
        if (!nativeDiscovery) return mcpTools
        const allNatives = this.listDefinitions()
        const nativeNames = new Set(allNatives.map(def => def.name))
        const natives = allNatives.filter(def => !BRIDGE_TOOL_NAMES.has(def.name))
        return [
          ...mcpTools.filter(tool => !nativeNames.has(tool.name)),
          ...natives.map(def => ({
            name: def.name,
            description: def.description,
            inputSchema: def.parameters,
            serverName: 'native',
          })),
        ]
      }
      this.register(
        new InternalToolAdapter(
          createToolSearchTool(getCatalog, { nativeTargets: nativeDiscovery }),
          outputDir,
          resolvedAttachmentOptions
        )
      )
      this.register(
        new InternalToolAdapter(
          createToolDescribeTool(getCatalog),
          outputDir,
          resolvedAttachmentOptions
        )
      )
      // F3 (dynamic-tool-loading): the execution bridge. Registered as a native
      // so it appears in tools[] and in `nativeNames`; its real handling is the
      // intercept at the top of `executeToolCalls`. The adapter's `execute` is a
      // safety net that errors if the intercept is bypassed.
      this.register(
        new InternalToolAdapter(
          createToolCallTool({ nativeTargets: nativeDiscovery }),
          outputDir,
          resolvedAttachmentOptions
        )
      )
    }
  }

  get(name: string): Tool | null {
    return this.tools.get(name) ?? null
  }

  listDefinitions(): ToolDefinition[] {
    const defs = Array.from(this.tools.values()).map(tool => ({
      name: tool.name(),
      description: tool.description(),
      parameters: tool.parametersSchema(),
    }))
    return defs
  }

  register(tool: Tool): void {
    this.tools.set(tool.name(), tool)
  }
}