Skip to content

armgit / orca

Public Imported from GitHub
0

Orca is the place for working with a fleet of agents (e.g. Grok Bot, Claude Code). Run any coding agent with your own subscription. Available on desktop, mobile and remote runtime.

13.9 KB
Raw Blame
/** Share title semantics between renderer transport processing and main’s per-PTY side-effect tracker. */

import {
  type AgentStatus,
  type AgentIdleStatus,
  clearWorkingIndicators,
  createAgentStatusTracker,
  detectAgentStatusFromTitle,
  extractAllOscTitles,
  isCursorNativeAgentTitle,
  normalizeTerminalTitle,
  shouldSuppressCursorNativeTitle
} from './agent-detection'
import type { ProgramActivityChange } from './agent-status-osc'
import { extractAllOscTitleEntries } from './osc-title-extraction'
import { placeProgramActivityAmongTitles } from './program-status/title-activity-order'
import { createBellDetector } from './terminal-bell-detector'
import {
  INITIAL_MODE_2031_REPLY_SCAN_STATE,
  scanMode2031ReplyDecision
} from './terminal-color-scheme-protocol'
import {
  createTerminalGitHubPRLinkDetector,
  type TerminalGitHubPRLink
} from './terminal-github-pr-link-detector'
import { createOsc133CommandFinishedScanner } from './terminal-osc133-command-finished'

/** Ms of title-less output after a working title before it is cleared. */
export const STALE_WORKING_TITLE_TIMEOUT_MS = 3000

/** Provenance for title/idle facts; `staleWorkingTitleClear` marks facts synthesized by the 3s stale timer — not genuine task completions. */
export type TerminalTitleFactMeta = {
  staleWorkingTitleClear?: boolean
}

/** An idle edge's provenance plus the status the tracker classified, so readers need not re-read the title. */
export type AgentIdleEdgeMeta = TerminalTitleFactMeta & { status?: AgentIdleStatus }

type TerminalTitleTrackerChunkOptions = {
  titleScanData?: string
  mode2031PendingSubscribe?: boolean
  /** The chunk's OSC 7501 activity changes, offsets in `data`; applied in byte order with its titles. */
  programActivity?: readonly ProgramActivityChange[]
}

export type TerminalTitleTrackerCallbacks = {
  /** Fired once per observed OSC title, in byte order — including the synthesized cleared title when the stale-working timer fires. */
  onTitle?: (normalizedTitle: string, rawTitle: string, meta?: TerminalTitleFactMeta) => void
  onAgentBecameIdle?: (title: string, meta?: AgentIdleEdgeMeta) => void
  onAgentBecameWorking?: () => void
  onAgentExited?: () => void
  /** Fired per change in the program's OSC 7501 activity (see applyProgramActivity). */
  onProgramActivity?: (activity: AgentStatus | null) => void
  /** Fired once per chunk containing a real BEL (OSC-aware, cross-chunk escape state), after the chunk's titles (renderer drain order). */
  onBell?: () => void
  /** Complete OSC 133;D with best-effort exit code; fact and byte paths must retire stale agent rows alike. */
  onCommandFinished?: (bestEffortExitCode: number | null) => void
  /** Fired per complete OSC 133;C: the shell exec'd a command, so the pane's foreground changed. */
  onCommandStarted?: () => void
  /** Fired once per newly observed GitHub PR URL (chunk-boundary-safe, deduplicated per tracker). */
  onPrLink?: (link: TerminalGitHubPRLink) => void
  /** Report the chunk-final subscription so hidden views can track it without receiving bytes. */
  onMode2031Subscribe?: () => void
  /** Report chunk-final withdrawal; gated views miss its bytes and would otherwise push theme replies into an unsubscribed shell (#9993). */
  onMode2031Unsubscribe?: () => void
}

export type TerminalTitleTracker = {
  /** Feed one raw PTY chunk; titles are applied synchronously in byte order. */
  handleChunk: (data: string, options?: TerminalTitleTrackerChunkOptions) => void
  /** Parse fabricated spinner title/BEL frames statelessly so they cannot corrupt real cross-chunk escapes. */
  applySyntheticTitleFrame: (frame: string) => void
  /** Seed a mid-session tracker once without callbacks; observed/seeded live state wins. */
  seedInitialTitle: (rawTitle: string) => void
  /** The stream lost the program's OSC 7501 reports (a data gap): titles classify again. */
  endProgramActivity: () => void
  /** Restore the status consumed by the latest exit candidate when process evidence disproves it. */
  restoreLastAgentExit: (confirmedStatus?: AgentStatus) => AgentStatus | null
  /** Last title surfaced through onTitle, after normalization. */
  getLastNormalizedTitle: () => string | null
  /** A thinning transport owns transient scans while bytes may be gapped. Keep title scans; reset transient carries when authority returns. */
  setTransientFactScanningSuppressed: (suppressed: boolean) => void
  /** Enable consumer-only bell, PR-link, and mode-2031 scans without resetting title state. */
  setTransientSideEffectScanningEnabled: (enabled: boolean) => void
  /** Cancel the stale-title timer and clear accumulated tracker state. */
  dispose: () => void
}

export function createTerminalTitleTracker(
  callbacks: TerminalTitleTrackerCallbacks,
  options: { initialTitle?: string } = {}
): TerminalTitleTracker {
  const {
    onTitle,
    onAgentBecameIdle,
    onAgentBecameWorking,
    onAgentExited,
    onProgramActivity,
    onBell,
    onCommandFinished,
    onCommandStarted,
    onPrLink,
    onMode2031Subscribe,
    onMode2031Unsubscribe
  } = callbacks
  let bellDetector = onBell ? createBellDetector() : null
  // Allocate scanners only for consumers so headless serve avoids per-chunk 133/URL scans.
  const commandFinishedScanner =
    onCommandFinished || onCommandStarted
      ? createOsc133CommandFinishedScanner(
          (exitCode) => onCommandFinished?.(exitCode),
          onCommandStarted ? () => onCommandStarted() : undefined
        )
      : null
  let prLinkDetector = onPrLink ? createTerminalGitHubPRLinkDetector() : null
  let transientSideEffectScanningEnabled = true
  let transientFactScanningSuppressed = false
  let mode2031ReplyScanState = INITIAL_MODE_2031_REPLY_SCAN_STATE
  // Seed both title forms to match a tracker that observed the last live title.
  let lastEmittedTitle: string | null =
    options.initialTitle !== undefined ? normalizeTerminalTitle(options.initialTitle) : null
  let staleTitleTimer: ReturnType<typeof setTimeout> | null = null
  // Timer clears are provenance-tagged so silence cannot become a task completion.
  let applyingStaleWorkingTitleClear = false
  const initialAgentStatusTitle =
    options.initialTitle !== undefined && !isCursorNativeAgentTitle(options.initialTitle)
      ? options.initialTitle
      : undefined
  const agentTracker =
    onAgentBecameIdle || onAgentBecameWorking || onAgentExited
      ? createAgentStatusTracker(
          (title, status) => {
            onAgentBecameIdle?.(title, {
              status,
              ...(applyingStaleWorkingTitleClear ? { staleWorkingTitleClear: true } : {})
            })
          },
          onAgentBecameWorking,
          onAgentExited,
          initialAgentStatusTitle
        )
      : null

  function clearStaleTitleTimer(): void {
    if (staleTitleTimer) {
      clearTimeout(staleTitleTimer)
      staleTitleTimer = null
    }
  }

  function applyObservedTitle(rawTitle: string): void {
    // Why: cursor-agent re-emits its bare native title mid-turn; passing it through would stomp Orca's synthesized spinner state.
    if (isCursorNativeAgentTitle(rawTitle)) {
      if (shouldSuppressCursorNativeTitle(lastEmittedTitle)) {
        return
      }
      // Hookless Cursor needs its literal identity once; null status must not be interpreted as an agent exit (#10258).
      lastEmittedTitle = normalizeTerminalTitle(rawTitle)
      onTitle?.(lastEmittedTitle, rawTitle)
      return
    }
    lastEmittedTitle = normalizeTerminalTitle(rawTitle)
    onTitle?.(lastEmittedTitle, rawTitle)
    agentTracker?.handleTitle(rawTitle)
  }

  function applyProgramActivity(activity: AgentStatus | null): void {
    agentTracker?.handleProgramActivity(activity)
    onProgramActivity?.(activity)
  }

  function handleChunk(data: string, options: TerminalTitleTrackerChunkOptions = {}): void {
    const titleScanData = options.titleScanData ?? data
    // Why: hot path — scan for the OSC introducer once and share it with the bell detector's fast-path gate.
    const containsOscIntroducer = data.includes('\x1b]')
    // Feed every contiguous chunk to preserve OSC state; suppressed bytes may be gapped.
    const containsBell =
      bellDetector && !transientFactScanningSuppressed
        ? bellDetector.chunkContainsBell(data, { containsOscIntroducer })
        : false
    // Process every title in byte order or coalescing hides working → idle transitions (#1083).
    const titles = titleScanData.includes('\x1b]') ? extractAllOscTitleEntries(titleScanData) : []
    // Title ends move into `data`'s offsets: titleScanData is the previous scan tail plus `data`.
    const tailLength = titleScanData.length - data.length
    const activity = options.programActivity
      ? placeProgramActivityAmongTitles(
          titles.map((entry) => entry.end - tailLength),
          options.programActivity
        )
      : []
    let activityIndex = 0
    const applyActivityBefore = (titleIndex: number): void => {
      while (activityIndex < activity.length && activity[activityIndex].beforeTitle <= titleIndex) {
        applyProgramActivity(activity[activityIndex].activity)
        activityIndex += 1
      }
    }
    if (titles.length > 0) {
      clearStaleTitleTimer()
      titles.forEach((entry, index) => {
        applyActivityBefore(index)
        applyObservedTitle(entry.title)
      })
    }
    applyActivityBefore(titles.length)
    if (
      titles.length === 0 &&
      // Why: an agent exiting without resetting its title leaves a stale spinner; title-less output while working arms the 3s clear timer.
      data.length > 0 &&
      lastEmittedTitle !== null &&
      detectAgentStatusFromTitle(lastEmittedTitle) === 'working'
    ) {
      clearStaleTitleTimer()
      staleTitleTimer = setTimeout(() => {
        staleTitleTimer = null
        if (lastEmittedTitle && detectAgentStatusFromTitle(lastEmittedTitle) === 'working') {
          const cleared = clearWorkingIndicators(lastEmittedTitle)
          lastEmittedTitle = cleared
          // Why: tag timer-synthesized facts so downstream distinguishes a merely-paused agent from a genuine working→idle completion.
          applyingStaleWorkingTitleClear = true
          try {
            onTitle?.(cleared, cleared, { staleWorkingTitleClear: true })
            agentTracker?.handleTitle(cleared)
          } finally {
            applyingStaleWorkingTitleClear = false
          }
        }
      }, STALE_WORKING_TITLE_TIMEOUT_MS)
    }
    // Fact order (matches renderer drain): titles → command-finished → pr-link → 2031-subscribe → bell; bell last.
    if (!transientFactScanningSuppressed) {
      commandFinishedScanner?.scan(data)
      if (prLinkDetector) {
        for (const link of prLinkDetector(data)) {
          onPrLink?.(link)
        }
      }
      if (transientSideEffectScanningEnabled && (onMode2031Subscribe || onMode2031Unsubscribe)) {
        const previousMode2031ReplyScanState = options.mode2031PendingSubscribe
          ? { ...mode2031ReplyScanState, pendingSubscribe: true }
          : mode2031ReplyScanState
        const result = scanMode2031ReplyDecision(previousMode2031ReplyScanState, data)
        mode2031ReplyScanState = result.state
        if (result.decision === 'subscribed') {
          onMode2031Subscribe?.()
        } else if (result.decision === 'unsubscribed') {
          onMode2031Unsubscribe?.()
        }
      }
    }
    if (containsBell) {
      onBell?.()
    }
  }

  function applySyntheticTitleFrame(frame: string): void {
    // Stateless parsing cannot mint/swallow bells around a real split OSC.
    const titles = extractAllOscTitles(frame)
    if (titles.length > 0) {
      clearStaleTitleTimer()
      for (const title of titles) {
        applyObservedTitle(title)
      }
    }
    // Use a fresh bell detector for the permission BEL outside the fabricated title.
    if (
      transientSideEffectScanningEnabled &&
      onBell &&
      createBellDetector().chunkContainsBell(frame)
    ) {
      onBell()
    }
    // Skip transient scanners: fabricated titles must not disturb their real-stream carry.
  }

  return {
    handleChunk,
    applySyntheticTitleFrame,
    endProgramActivity: () => applyProgramActivity(null),
    seedInitialTitle(rawTitle: string): void {
      if (lastEmittedTitle !== null || !rawTitle) {
        return
      }
      lastEmittedTitle = normalizeTerminalTitle(rawTitle)
      // Cursor’s literal seeds identity only; null status would make the next real frame look like an exit.
      if (!isCursorNativeAgentTitle(rawTitle)) {
        agentTracker?.seedTitle(rawTitle)
      }
    },
    restoreLastAgentExit(confirmedStatus?: AgentStatus): AgentStatus | null {
      return agentTracker?.restoreLastExit(confirmedStatus) ?? null
    },
    getLastNormalizedTitle: () => lastEmittedTitle,
    setTransientFactScanningSuppressed(suppressed: boolean): void {
      if (suppressed === transientFactScanningSuppressed) {
        return
      }
      transientFactScanningSuppressed = suppressed
      if (!suppressed) {
        // Cross-chunk carry predates the gapped span; reset it so stale state can't swallow real bells or mint phantom facts.
        bellDetector?.reset()
        commandFinishedScanner?.reset()
        mode2031ReplyScanState = INITIAL_MODE_2031_REPLY_SCAN_STATE
        if (prLinkDetector) {
          prLinkDetector = createTerminalGitHubPRLinkDetector()
        }
      }
    },
    setTransientSideEffectScanningEnabled(enabled: boolean): void {
      if (enabled === transientSideEffectScanningEnabled) {
        return
      }
      transientSideEffectScanningEnabled = enabled
      bellDetector?.reset()
      bellDetector = enabled && onBell ? createBellDetector() : null
      prLinkDetector = enabled && onPrLink ? createTerminalGitHubPRLinkDetector() : null
      mode2031ReplyScanState = INITIAL_MODE_2031_REPLY_SCAN_STATE
    },
    dispose(): void {
      clearStaleTitleTimer()
      agentTracker?.reset()
      bellDetector?.reset()
      commandFinishedScanner?.reset()
      mode2031ReplyScanState = INITIAL_MODE_2031_REPLY_SCAN_STATE
    }
  }
}