Skip to content

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

TypeScript
6.0 KB
Raw Blame
/**
 * DeferrableToolController — the OUTERMOST LoopController decorator for the
 * dynamic-tool-loading "stable bridge" design (Phase F3.1).
 *
 * When active, it removes all deferrable MCP tools from the advertised
 * `tools[]` array, leaving only the native tools (which include the 3 bridge
 * tools `clerum__tool_search` / `clerum__tool_describe` / `clerum__tool_call`).
 * Deferred MCP tools are reached exclusively through `clerum__tool_call`.
 *
 * Why a decorator (delegate-first composition): the inner chain
 * (`ApprovalController → UnifiedApprovalGateController` for interactive tasks,
 * or a bare `DefaultLoopController` for cron) keeps owning approval and text
 * gating. We only post-process the tool LIST returned by `refreshTools`.
 *
 * Other providers retain the legacy session latch. Codex evaluates its live
 * catalog on every refresh: a cold connection or provider switch must not keep
 * an obsolete threshold decision. Discovery never promotes schemas to tools[].
 *
 * `isNative` membership is decided by the exact `nativeNames` set (Critical:
 * `clerum__*` tools contain `__` but are native), NEVER by a string heuristic.
 */
import { logger } from '../../logger'
import { LoopController } from '../interfaces'
import { ChatMessage, PendingApproval, ToolDefinition } from '../types'
import type { CodexToolPresentation } from './toolPresentationPolicy'

/**
 * Session-scoped read/write of the latched `bridgeActive` decision. Bound to the
 * `Conversation` in production (`dynamicToolsBridgeActive`); tests pass a tiny
 * in-memory object. `get()` returns `undefined` until the first `set()`.
 */
export interface LatchStore {
  get(): boolean | undefined
  set(value: boolean): void
}

export class DeferrableToolController implements LoopController {
  private readonly delegate: LoopController
  private readonly nativeNames: Set<string>
  private readonly enabled: boolean
  private readonly threshold: number
  private readonly latch: LatchStore
  private readonly codexMode?: CodexToolPresentation
  private readonly discoveryBytes: number
  private lastPresentation: string | undefined

  constructor(
    delegate: LoopController,
    nativeNames: Set<string>,
    config: {
      dynamicToolsEnabled: boolean
      dynamicToolsThreshold: number
      codexMode?: CodexToolPresentation
      codexToolDiscoveryBytes?: number
    },
    latch: LatchStore
  ) {
    this.delegate = delegate
    this.nativeNames = nativeNames
    this.enabled = config.dynamicToolsEnabled
    this.threshold = config.dynamicToolsThreshold
    this.latch = latch
    this.codexMode = config.codexMode
    this.discoveryBytes = config.codexToolDiscoveryBytes ?? 32_768
  }

  shouldAccept(content: string, iteration: number): boolean {
    return this.delegate.shouldAccept(content, iteration)
  }

  onTextRejected(content: string, iteration: number): ChatMessage | null {
    return this.delegate.onTextRejected(content, iteration)
  }

  beforeTool(
    toolName: string,
    params: Record<string, unknown>
  ): 'proceed' | 'skip' | { type: 'suspend'; approval: PendingApproval } {
    return this.delegate.beforeTool(toolName, params)
  }

  onExhaustion(iteration: number): string {
    return this.delegate.onExhaustion(iteration)
  }

  async refreshTools(currentTools: ToolDefinition[]): Promise<ToolDefinition[]> {
    // Delegate first so we compose OVER approval's refresh (it currently passes
    // through, but never assume — the inner chain owns the upstream list).
    const upstream = await this.delegate.refreshTools(currentTools)

    // Codex must reevaluate the live catalog after late connections and provider
    // switches. Never reuse another provider's session latch or promote schemas.
    if (this.codexMode) {
      const deferred = upstream.filter(t => !this.nativeNames.has(t.name))
      const discover =
        this.codexMode !== 'direct' &&
        (this.codexMode === 'discovery' ||
          deferred.length > this.threshold ||
          Buffer.byteLength(JSON.stringify(deferred), 'utf8') > this.discoveryBytes)
      const presented = discover ? upstream.filter(t => this.nativeNames.has(t.name)) : upstream
      const measurement = {
        mode: this.codexMode,
        strategy: discover ? 'discovery' : 'direct',
        nativeCount: upstream.length - deferred.length,
        mcpCount: deferred.length,
        presentedCount: presented.length,
        deferredCount: discover ? deferred.length : 0,
      }
      const key = JSON.stringify(measurement)
      if (key !== this.lastPresentation) {
        logger.info(
          { component: 'tool-presentation', ...measurement },
          'Tool presentation selected'
        )
        this.lastPresentation = key
      }
      return presented
    }

    // LATCH (LOCKED #6): compute the bridge decision exactly once per SESSION,
    // from the FIRST observed upstream tool set, and freeze it on the
    // session-scoped store. Later tasks read the same value.
    let bridgeActive = this.latch.get()
    if (bridgeActive === undefined) {
      const deferrableCount = upstream.filter(t => !this.nativeNames.has(t.name)).length
      bridgeActive = this.enabled && deferrableCount > this.threshold
      this.latch.set(bridgeActive)
      // Rollout observability: log ONCE per session, when the latch transitions
      // from unset to assigned — for BOTH outcomes (bridgeActive true or false),
      // NOT on every turn. Surfaces the cold-load decision (whether the bridge
      // engaged, the observed deferrable count, and the threshold) so we can see
      // recomputation visibility.
      logger.info(
        { component: 'deferrable-tools', bridgeActive, deferrableCount, threshold: this.threshold },
        'Legacy session presentation selected'
      )
    }

    // Passthrough — identical to today's behavior (flag off / under threshold).
    if (!bridgeActive) return upstream

    // STABLE SWAP: advertise ONLY natives (which include the 3 bridge tools).
    // Deterministic and session-invariant → `tools[]` byte-stable → cache-safe.
    return upstream.filter(t => this.nativeNames.has(t.name))
  }
}