orca/src/main/runtime/runtime-notifier-contract.ts

import type {
  RuntimeEditorTabReveal,
  RuntimeFileOpenPosition
} from '../../shared/runtime-file-contracts'
import type { AgentLaunchPaneVerdictEvent } from '../../shared/agent-launch-pane-verdict'
import type { SleepingAgentLaunchConfig } from '../../shared/agent-session-resume'
import type {
  AgentLaunchTabPublished,
  AgentLaunchTabViewerRule,
  AgentLaunchTabPublishRequest
} from '../../shared/agent-launch-tab-publication'
import type { TerminalPaneSplitSource } from '../../shared/feature-education-telemetry'
import type { TerminalRevealIdentity } from '../../shared/terminal-reveal-identity'
import type { TerminalPaneRevealTarget } from '../../shared/terminal-pane-reveal'
import type { TuiAgent } from '../../shared/tui-agent'
import type { RuntimeNavigationTarget } from '../../shared/runtime-navigation'
import type { ClientHostedBrowserRowsEvent } from '../../shared/client-hosted-browser-rows'
import type {
  WorktreeBaseStatusEvent,
  WorktreeRemoteBranchConflictEvent
} from '../../shared/worktree/base-ref-drift-types'
import type { CreateWorktreeResult } from '../../shared/worktree/create-types'
import type { WorktreeStartupLaunch } from '../../shared/worktree/launch-types'
import type {
  RuntimeBrowserDriverState,
  RuntimeMobileSessionTabMove,
  RuntimeTerminalDriverState,
  RuntimeTerminalPresentation
} from '../../shared/runtime-types'

type DriverState = RuntimeTerminalDriverState

export type RuntimeNotifier = {
  automationsChanged?(payload: {
    selector?: { kind: 'self' } | { kind: 'ssh'; targetId: string } | { kind: 'orphan' }
    reason?: 'definition' | 'run' | 'usage'
  }): void
  worktreesChanged(
    repoId: string,
    renamed?: { oldWorktreeId: string; newWorktreeId: string },
    // Why: false for metadata-only changes (sort order) that leave Git scan results valid.
    options?: { invalidateGitScans?: boolean }
  ): void
  worktreeBaseStatus?(event: WorktreeBaseStatusEvent): void
  worktreeRemoteBranchConflict?(event: WorktreeRemoteBranchConflictEvent): void
  reposChanged(): void
  activateWorktree(
    repoId: string,
    worktreeId: string,
    setup?: CreateWorktreeResult['setup'],
    startup?: WorktreeStartupLaunch,
    defaultTabs?: CreateWorktreeResult['defaultTabs'],
    providesInitialSurface?: boolean
  ): void
  createTerminal(
    worktreeId: string,
    opts: {
      command?: string
      cwd?: string
      env?: Record<string, string>
      title?: string
      presentation?: RuntimeTerminalPresentation
    }
  ): void
  revealTerminalSession?(
    worktreeId: string,
    opts: {
      ptyId: string
      title?: string | null
      cwd?: string
      launchConfig?: SleepingAgentLaunchConfig
      launchToken?: string
      launchAgent?: TuiAgent
      viewMode?: 'terminal' | 'chat'
      targetGroupId?: string
      afterTabId?: string
      shellOverride?: string
      activate?: boolean
      presentation?: RuntimeTerminalPresentation
      surfaceOwner?: false
      agentLaunchViewer?: AgentLaunchTabViewerRule
      tabId?: string
      leafId?: string
      splitFromLeafId?: string
      splitDirection?: 'horizontal' | 'vertical'
      splitTelemetrySource?: TerminalPaneSplitSource
      focus?: boolean
      expectedProcessIdentity?: {
        terminalHandle: string
        incarnationId: string
      }
    }
  ):
    | Promise<{ tabId: string; title?: string | null; identity?: TerminalRevealIdentity }>
    | { tabId: string; title?: string | null; identity?: TerminalRevealIdentity }
    | void
  /** Shows an agent launch's tab before its process exists; the pane attaches when it does. */
  publishAgentLaunchTab?(
    request: Omit<AgentLaunchTabPublishRequest, 'requestId'>
  ): Promise<AgentLaunchTabPublished>
  /** A launch pane's fate, for the window to keep on its tab or act on. */
  agentLaunchPaneVerdict?(event: AgentLaunchPaneVerdictEvent): void
  resolveLegacyWorkerTerminalRecovery?(
    paneKey: string,
    resolution: 'adopted' | 'exited' | 'rolled_back',
    ptyId?: string
  ): void
  /** The fence lives in the workspace session, which a live renderer only re-reads at startup. */
  splitTerminal(
    tabId: string,
    paneRuntimeId: number,
    opts: {
      direction: 'horizontal' | 'vertical'
      command?: string
      worktreeId?: string
      sourceLeafId?: string
      telemetrySource?: TerminalPaneSplitSource
      newLeafId?: string
    }
  ): void
  /** `recordInteraction: false` marks a title the host applied, not one the user typed. */
  renameTerminal(tabId: string, title: string | null, options?: { recordInteraction: false }): void
  /** False when the window could not be reached; absent on notifiers that predate pane titles. */
  setPaneTitle?(tabId: string, leafId: string, title: string | null): boolean
  focusTerminal(tabId: string, worktreeId: string, leafId?: string | null): void
  /** Raises the window onto a pane it shows; resolves false when the window does not know the worktree. */
  revealTerminalPane?(target: TerminalPaneRevealTarget): Promise<boolean>
  focusEditorTab?(tabId: string, worktreeId: string): void
  closeSessionTab?(tabId: string, worktreeId: string): void | Promise<void>
  moveSessionTab?(worktreeId: string, move: RuntimeMobileSessionTabMove): void
  /**
   * Acts only on the host's own window: 'host'/'all' move it, 'caller'/'clients' open without moving
   * it, absent keeps the original switch. Paired clients are never navigated (intended; 'all' == 'host').
   */
  openFile?(
    worktreeId: string,
    filePath: string,
    relativePath: string,
    runtimeEnvironmentId?: string | null,
    navigation?: RuntimeNavigationTarget,
    position?: RuntimeFileOpenPosition
  ): void
  /** Layout-owner builds: shows a tab main already wrote for a file it opened. */
  revealEditorTab?(reveal: RuntimeEditorTabReveal): void
  openDiff?(
    worktreeId: string,
    filePath: string,
    relativePath: string,
    staged: boolean,
    runtimeEnvironmentId?: string | null,
    navigation?: RuntimeNavigationTarget
  ): void
  /** Closes the whole tab. */
  closeTerminal(tabId: string): void
  /** Drops one split pane main already closed; never closes its tab. */
  closeTerminalPane?(tabId: string, leafId: string): void
  closeTerminalTab?(
    tabId: string,
    options?: { localPtyTeardownOwnedExternally?: boolean; force?: boolean }
  ): Promise<void>
  sleepWorktree(worktreeId: string): void
  // Why: a phone opening a worktree wakes its slept agents by asking the host
  // renderer to run its own navigation-free wake (experimental agent sleep);
  // the runtime has no in-memory sleeping records or wake authority. Optional to
  // match the many renderer-backed notifier methods only the real bridge wires.
  resumeSleepingAgents?(worktreeId: string): void
  terminalFitOverrideChanged(
    ptyId: string,
    mode: 'mobile-fit' | 'remote-desktop-fit' | 'desktop-fit',
    cols: number,
    rows: number
  ): void
  // Why: presence-based lock signal — desktop renderer mounts the lock
  // banner when `driver.kind === 'mobile'` and unmounts otherwise. The
  // structured payload (vs a `locked: boolean`) carries the active mobile
  // actor's clientId so the renderer can disambiguate multi-phone scenarios
  // and so a future write coordinator can use the same signal as scheduling
  // input. See docs/mobile-presence-lock.md.
  terminalDriverChanged(ptyId: string, driver: DriverState): void
  nativeChatLaunchDraftResolved?(
    tabId: string,
    resolution: { text: string; createdAt: number }
  ): void
  browserDriverChanged?(browserPageId: string, driver: RuntimeBrowserDriverState): void
  browserRemoteViewersChanged?(browserPageId: string, hasRemoteViewers: boolean): void
  clientHostedBrowserRowsChanged?(event: ClientHostedBrowserRowsEvent): void
}