Skip to content

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

TypeScript
14.5 KB
Raw Blame
// mcp-host/src/progress/sseProgressReporter.ts
import type { Safety } from '../core/interfaces.js'
import type { TaskLifecycle } from '../lifecycle/taskLifecycle.js'
import type { TransitionEvent } from '../lifecycle/types.js'
import { projectApprovalInputPreview } from './approvalInputPreview'
import type {
  LlmInProgressEvent,
  OutputPreview,
  ProgressEvent,
  ProgressReporter,
  SuspendedEvent,
  TerminalEvent,
  ThinkingEvent,
  ToolCompleteEvent,
  ToolProgressEvent,
  ToolStartEvent,
} from './types.js'

export class SseProgressReporter implements ProgressReporter {
  private subscribers = new Set<(event: ProgressEvent) => void>()
  private completed = false
  public completedAt: number = Infinity

  // Terminal events are buffered so late subscribers get an immediate replay.
  // This handles the race where the LLM fails fast (~2s) before the desktop
  // app's SSE connection is established.
  private terminalBuffer: ProgressEvent[] = []

  // P1 - approval stuck and lost response: sticky replay of the last
  // non-terminal `suspended` event. The desktop SSE bridge reconnects invisibly
  // to the tracker (up to 3 attempts) and re-subscribes here; if a transient
  // blip falls AFTER emitSuspended published, the live suspended state would be
  // lost forever (only terminal events were replayed). We keep the last
  // suspended event so a late/re-connected subscriber can rebuild the live gate
  // state. Holds the SAME redacted payload published live (server-derived
  // displayName via getDisplayName — never the raw tool_name or args).
  private lastSuspended: ProgressEvent | undefined = undefined

  private lifecycleUnsubscribe: (() => void) | null = null

  // safety is the SSE redaction chokepoint; required so callers can't silently opt out. Tests pass NoopSafety from core/safety.
  constructor(
    public readonly taskId: string,
    lifecycle: TaskLifecycle | undefined,
    private readonly safety: Safety
  ) {
    if (lifecycle) this.subscribeToLifecycle(lifecycle)
  }

  // Phase D.2: subscribe to all three terminal transitions and emit a single
  // typed 'terminal' event for each. Legacy reportCancelled/reportError/complete
  // public methods are removed — all terminal emission flows through here.
  private subscribeToLifecycle(lifecycle: TaskLifecycle): void {
    const handler = (ev: TransitionEvent) => {
      try {
        if (ev.taskId !== this.taskId) return
        if (ev.to === 'completed' || ev.to === 'failed' || ev.to === 'cancelled') {
          this.emitTerminal({
            taskId: this.taskId,
            status: ev.to,
            reason: ev.reason,
            error: ev.error,
          })
        }
      } catch (err) {
        // Invariant I11: TaskLifecycle subscribers MUST be exception-safe.
        // A throw here would halt Node's EventEmitter.emit() and stall
        // other subscribers (e.g., AgentStateMachine's executor.abort() dispatcher).
        console.error('[SseProgressReporter] lifecycle handler raised', {
          taskId: this.taskId,
          err,
        })
      }
    }
    lifecycle.on('transition', handler)
    this.lifecycleUnsubscribe = () => lifecycle.off('transition', handler)
  }

  private emitTerminal(data: TerminalEvent): void {
    if (this.completed) return
    const safe = this.redactTerminal(data)
    const event: ProgressEvent = { type: 'terminal', data: safe }
    this.terminalBuffer.push(event)
    this.publish(event)
    this.completed = true
    this.completedAt = Date.now()
  }

  /**
   * Clean up subscription. Call when reporter is no longer needed.
   */
  dispose(): void {
    this.lifecycleUnsubscribe?.()
    this.lifecycleUnsubscribe = null
  }

  subscribe(handler: (event: ProgressEvent) => void): () => void {
    this.subscribers.add(handler)
    // Replay buffered terminal events for late subscribers
    for (const event of this.terminalBuffer) {
      try {
        handler(event)
      } catch {
        /* swallow */
      }
    }
    // replay the sticky suspended state so a late/re-connected subscriber
    // can render the live approval gate instead of being stuck on "Connecting".
    // Guarded by !this.completed (mirrors the per-event completed guards) so a
    // terminal task never replays a stale suspended; lastSuspended is also
    // cleared once execution resumes past the gate (see reportToolStart /
    // reportLlmInProgress).
    if (!this.completed && this.lastSuspended) {
      try {
        handler(this.lastSuspended)
      } catch {
        /* swallow */
      }
    }
    return () => {
      this.subscribers.delete(handler)
    }
  }

  reportToolStart(event: ToolStartEvent): void {
    if (this.completed) return
    // P1: a tool start AFTER a suspend means the gate was resolved and the loop
    // resumed (the approved tool is now executing). Drop the sticky suspended so
    // a late subscriber never sees an already-resolved approval.
    this.lastSuspended = undefined
    const safe = this.redactToolStart(event)
    this.publish({ type: 'tool_start', data: { ...safe, taskId: this.taskId } })
  }

  reportToolComplete(event: ToolCompleteEvent): void {
    if (this.completed) return
    const safe = this.redactToolComplete(event)
    this.publish({ type: 'tool_complete', data: { ...safe, taskId: this.taskId } })
  }

  reportToolProgress(event: ToolProgressEvent): void {
    if (this.completed) return
    const safe = this.redactToolProgress(event)
    this.publish({ type: 'tool_progress', data: { ...safe, taskId: this.taskId } })
  }

  reportThinking(event: ThinkingEvent): void {
    // Reserved — when implementing, redact event.summary via redactString to keep boundary coverage.
    void event
  }

  reportLlmInProgress(event: LlmInProgressEvent): void {
    if (this.completed) return
    // P1: LLM back in progress after a suspend means the gate resolved and the
    // loop fed the tool result back to the model. Clear the sticky suspended.
    this.lastSuspended = undefined
    this.publish({ type: 'llm_in_progress', data: { ...event, taskId: this.taskId } })
  }

  // P1-1: takes only the server-derived displayName (not the raw tool_name).
  // U5: `options` is ADDITIVE — absent → the legacy 'approval_required' gate,
  // byte-identical to before. reason==='connect_required' carries the oauth
  // mcpServerName so the desktop can open the connect flow.
  emitSuspended(
    displayName: string,
    requestId: string,
    options?: {
      reason?: 'approval_required' | 'connect_required'
      mcpServerName?: string
      toolName?: string
      parameters?: Record<string, unknown>
    }
  ): void {
    if (this.completed) return
    const reason = options?.reason ?? 'approval_required'
    const data: SuspendedEvent = { taskId: this.taskId, requestId, displayName, reason }
    if (reason === 'connect_required') {
      if (options?.mcpServerName) data.mcpServerName = options.mcpServerName
    }
    if (reason === 'approval_required' && options?.toolName && options.parameters) {
      const toolName = options.toolName
      const preview = projectApprovalInputPreview(
        toolName,
        options.parameters,
        text => this.safety.sanitizeOutput(toolName, text).content
      )
      if (preview) data.inputPreview = preview
    }
    const event: ProgressEvent = { type: 'suspended', data }
    // P1: store the exact redacted payload we publish live so late/re-connected
    // subscribers can replay it (see subscribe). displayName is already the
    // server-derived name from getDisplayName — never the raw tool_name/args.
    this.lastSuspended = event
    this.publish(event)
  }

  // Boundary redaction helpers: idempotent re-pass over upstream sanitize in toolUseLoop.
  private redactString(toolName: string, value: string | undefined): string | undefined {
    if (!value) return value
    return this.safety.sanitizeOutput(toolName, value).content
  }

  private redactToolStart(e: ToolStartEvent): ToolStartEvent {
    return {
      ...e,
      intentSummary: this.redactString(e.toolName, e.intentSummary) ?? e.intentSummary,
      inputPreview: this.redactString(e.toolName, e.inputPreview),
    }
  }

  private redactPreview(
    toolName: string,
    preview: OutputPreview | undefined
  ): OutputPreview | undefined {
    if (!preview) return preview
    return {
      ...preview,
      headLines: preview.headLines.map(l => this.redactString(toolName, l) ?? l),
      tailLines: preview.tailLines.map(l => this.redactString(toolName, l) ?? l),
    }
  }

  private redactMetadata(toolName: string, value: unknown): unknown {
    if (typeof value === 'string') return this.redactString(toolName, value) ?? value
    if (Array.isArray(value)) return value.map(item => this.redactMetadata(toolName, item))
    if (!value || typeof value !== 'object') return value
    const output: Record<string, unknown> = {}
    for (const [key, child] of Object.entries(value as Record<string, unknown>)) {
      output[key] = this.redactMetadata(toolName, child)
    }
    return output
  }

  private redactToolComplete(e: ToolCompleteEvent): ToolCompleteEvent {
    return {
      ...e,
      errorSummary: this.redactString(e.toolName, e.errorSummary),
      outputPreview: this.redactPreview(e.toolName, e.outputPreview),
      metadata: this.redactMetadata(e.toolName, e.metadata) as Record<string, unknown> | undefined,
    }
  }

  private redactToolProgress(e: ToolProgressEvent): ToolProgressEvent {
    return {
      ...e,
      outputPreview: this.redactPreview(e.toolName, e.outputPreview),
    }
  }

  private redactTerminal(e: TerminalEvent): TerminalEvent {
    if (!e.error) return e
    const redactedMessage = this.redactString('__terminal__', e.error.message) ?? e.error.message
    return {
      ...e,
      error: { ...e.error, message: redactedMessage },
    }
  }

  private publish(event: ProgressEvent): void {
    for (const handler of this.subscribers) {
      try {
        handler(event)
      } catch {
        // Swallow subscriber errors
      }
    }
  }
}

/**
 * TTL for completed reporters. 5 minutes matches the RPC JWT token lifetime,
 * ensuring the Desktop App can always connect to a stream for tasks that finished
 * within the current auth window. Previously 60s, which caused "temporarily
 * unavailable" errors when the stream connected even slightly late.
 */
const REPORTER_TTL_MS = 5 * 60 * 1000

type Waiter = {
  resolve: (reporter: SseProgressReporter) => void
  timer: ReturnType<typeof setTimeout>
}

/**
 * Registry that stores SseProgressReporter instances keyed by taskId.
 *
 * Extends plain Map storage with:
 * - TTL-based cleanup (reporters are evicted `REPORTER_TTL_MS` after completion)
 * - `waitFor(taskId, timeoutMs)` — returns a Promise that resolves when the
 *   reporter for `taskId` becomes available. This eliminates the race condition
 *   where the Desktop App opens the progress stream before the agent dequeues
 *   the task and creates its reporter.
 */
class ProgressReporterRegistry {
  private store = new Map<string, SseProgressReporter>()
  private waiters = new Map<string, Waiter[]>()

  set(id: string, reporter: SseProgressReporter): void {
    this.store.set(id, reporter)

    // Wake any waiters blocked on this taskId
    const pending = this.waiters.get(id)
    if (pending) {
      this.waiters.delete(id)
      for (const waiter of pending) {
        clearTimeout(waiter.timer)
        waiter.resolve(reporter)
      }
    }
  }

  get(id: string): SseProgressReporter | undefined {
    this.cleanup()
    return this.store.get(id)
  }

  delete(id: string): boolean {
    return this.store.delete(id)
  }

  /**
   * Wait for a reporter to appear in the registry.
   *
   * If the reporter already exists, resolves immediately.
   * Otherwise blocks until `set(taskId, ...)` is called or `timeoutMs` elapses.
   * Returns `undefined` on timeout.
   */
  waitFor(taskId: string, timeoutMs: number = 30_000): Promise<SseProgressReporter | undefined> {
    this.cleanup()
    const existing = this.store.get(taskId)
    if (existing) return Promise.resolve(existing)

    return new Promise<SseProgressReporter | undefined>(resolve => {
      const timer = setTimeout(() => {
        // Timeout — remove this waiter and resolve with undefined
        const list = this.waiters.get(taskId)
        if (list) {
          const idx = list.findIndex(w => w.resolve === resolve)
          if (idx >= 0) list.splice(idx, 1)
          if (list.length === 0) this.waiters.delete(taskId)
        }
        resolve(undefined)
      }, timeoutMs)

      const waiter: Waiter = { resolve, timer }
      const list = this.waiters.get(taskId)
      if (list) {
        list.push(waiter)
      } else {
        this.waiters.set(taskId, [waiter])
      }
    })
  }

  /** For testing — returns all entries after cleanup. */
  entries(): Array<[string, SseProgressReporter]> {
    this.cleanup()
    return Array.from(this.store.entries())
  }

  private cleanup(): void {
    const now = Date.now()
    for (const [id, reporter] of this.store) {
      if (now - reporter.completedAt > REPORTER_TTL_MS) {
        reporter.dispose() // C1: remove lifecycle listener before drop
        this.store.delete(id)
      }
    }
  }
}

export const progressReporterRegistry = new ProgressReporterRegistry()

/**
 * Idempotent get-or-create for the SSE progress reporter of a task.
 *
 * Returns the existing registered reporter when one is already present
 * (the normal executor path), otherwise constructs one, registers it — which
 * wakes any `waitFor(taskId)` blocked on the stream endpoint — and returns it.
 *
 * Used by BOTH the executor (`TaskExecutor.ensureProgressReporter`) and the
 * canonical failure path (`AgentStateMachine.handleTaskFailure`), so a task
 * that fails BEFORE the executor is ever created (e.g. a budget deny or a null
 * `llmProvider`) still has a reporter subscribed to the lifecycle when the
 * terminal transition fires. Without it the terminal SSE event is lost and the
 * stream waits the full `waitFor` timeout (~180s) — the "Agent is thinking"
 * hang (§5.3.1 of the token-budgets design).
 *
 * CALLER GUARD: only call this when a terminal lifecycle transition is still
 * pending. Registering a reporter for an already-terminal task leaves it with
 * `completedAt=Infinity` (its lifecycle handler never fires) so the TTL sweep
 * never evicts it — a reporter + lifecycle-listener leak.
 */
export function ensureReporter(
  taskId: string,
  lifecycle: TaskLifecycle | undefined,
  safety: Safety
): SseProgressReporter {
  const existing = progressReporterRegistry.get(taskId)
  if (existing) return existing
  const reporter = new SseProgressReporter(taskId, lifecycle, safety)
  progressReporterRegistry.set(taskId, reporter)
  return reporter
}