Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

8.0 KB
Raw Blame
/**
 * Terminal control: reading a pane and typing, submitting and sending keys to it, through a control
 * lease: a short one that lapses after 15 s of quiet, or one pinned for as long as a caller holds the
 * pane (a question being answered, a sequence of keys). A pinned lease that stops validating is not
 * quietly replaced: every later action on that pane fails until it is unpinned, so a sequence never
 * continues in a pane that changed under it.
 *
 * Moved verbatim out of `runForeground` (the core boundary, step 2: docs/design/2026-10-03-harnessd.md).
 */
import type { RegisteredSession } from '../../lib/registry.js'
import type { TerminalBackendCoordinator } from '../../lib/terminalBackendCoordinator.js'
import { TERMINAL_LEASE_REFUSED, terminalActionNotStarted, type SubmitOptions, type TerminalActionResult } from '../../lib/terminalTypes.js'
import { paneReadIdentity } from '../transcripts/readIdentity.js'

export type TerminalControlBackend = Pick<TerminalBackendCoordinator,
  'acquireLease' | 'validateLease' | 'capture' | 'captureLease' | 'submitText' | 'submitTextLease'
  | 'submitTextForLease' | 'typeLiteralLease' | 'sendLegacyKeyLease' | 'validate'>

export interface TerminalControlDeps {
  /** The agent a target names: its agent id, session id or pane. */
  resolve: (target: string) => RegisteredSession | undefined
  terminals: TerminalControlBackend
}

export function createTerminalControl({ resolve, terminals }: TerminalControlDeps) {
  const terminalSession = (target: string): RegisteredSession | undefined => resolve(target)
  const controlLeases = new Map<string, { lease: Awaited<ReturnType<typeof terminals.acquireLease>> & { state: 'succeeded' }; expiresAt: number }>()
  const pinnedControls = new Set<string>()
  const invalidControls = new Set<string>()
  const CONTROL_LEASE_IDLE_MS = 15_000
  const leasedTerminal = async (session: RegisteredSession): Promise<Extract<Awaited<ReturnType<typeof terminals.acquireLease>>, { state: 'succeeded' }> | null> => {
    const pinned = pinnedControls.has(session.agentId)
    if (pinned && invalidControls.has(session.agentId)) return null
    const current = controlLeases.get(session.agentId)
    if (current && (pinned || current.expiresAt > Date.now())) {
      if (!await terminals.validateLease(current.lease.value, session)) {
        controlLeases.delete(session.agentId)
        if (pinned) invalidControls.add(session.agentId)
        return null
      }
      current.expiresAt = Date.now() + CONTROL_LEASE_IDLE_MS
      return current.lease
    }
    controlLeases.delete(session.agentId)
    const acquired = await terminals.acquireLease(session)
    if (acquired.state !== 'succeeded') return null
    const value = { lease: acquired, expiresAt: Date.now() + CONTROL_LEASE_IDLE_MS }
    controlLeases.set(session.agentId, value)
    return acquired
  }
  const pinTerminalControl = (target: string): (() => void) | null => {
    const session = terminalSession(target)
    if (!session || pinnedControls.has(session.agentId)) return null
    pinnedControls.add(session.agentId)
    invalidControls.delete(session.agentId)
    return () => {
      pinnedControls.delete(session.agentId)
      invalidControls.delete(session.agentId)
      controlLeases.delete(session.agentId)
    }
  }
  const invalidateTerminalControl = (agentId: string): void => {
    controlLeases.delete(agentId)
    if (pinnedControls.has(agentId)) invalidControls.add(agentId)
  }
  const captureTerminal = async (target: string, historyLines?: number): Promise<string | null> => {
    const session = terminalSession(target)
    if (!session) return null
    // Registry rows (including their runtime/process objects) can change in place while tmux reads.
    // Copy the identity before yielding so no caller interprets an old pane as the new conversation.
    const agentId = session.agentId, identity = paneReadIdentity(session)
    const current = () => paneReadIdentity(resolve(agentId)) === identity
    const pinned = pinnedControls.has(session.agentId)
    if (pinned && invalidControls.has(session.agentId)) return null
    let activeLease = controlLeases.get(session.agentId)
    if (activeLease && !pinned && activeLease.expiresAt <= Date.now()) {
      controlLeases.delete(session.agentId)
      activeLease = undefined
    }
    const leased = activeLease || pinned ? await leasedTerminal(session) : null
    if ((activeLease || pinned) && !leased) return null
    if (!current()) return null
    const result = leased
      ? await terminals.captureLease(leased.value, { historyLines })
      : await terminals.capture(session, { historyLines })
    return result.state === 'succeeded' && current() ? result.value : null
  }
  const terminalActionSucceeded = (result: Awaited<ReturnType<typeof terminals.submitText>>): boolean =>
    result.state === 'succeeded'
  const submitTerminalAction = async (target: string, text: string, options?: SubmitOptions): Promise<TerminalActionResult> => {
    const session = terminalSession(target)
    if (!session) return terminalActionNotStarted('terminal agent is unavailable')
    const lease = await leasedTerminal(session)
    if (!lease) return terminalActionNotStarted(TERMINAL_LEASE_REFUSED)
    if (options?.allowed && !options.allowed()) return terminalActionNotStarted('terminal control revoked')
    const result = pinnedControls.has(session.agentId)
      ? await terminals.submitTextLease(lease.value, text, options)
      : await terminals.submitTextForLease(session, lease.value, text, options)
    if (result.state !== 'succeeded' && pinnedControls.has(session.agentId)) invalidateTerminalControl(session.agentId)
    return result
  }
  const submitTerminal = async (target: string, text: string, options?: SubmitOptions): Promise<boolean> => {
    return terminalActionSucceeded(await submitTerminalAction(target, text, options))
  }
  const typeTerminal = async (target: string, text: string): Promise<boolean> => {
    const session = terminalSession(target)
    if (!session) return false
    const lease = await leasedTerminal(session)
    if (!lease) return false
    const succeeded = terminalActionSucceeded(await terminals.typeLiteralLease(lease.value, text))
    if (!succeeded && pinnedControls.has(session.agentId)) invalidateTerminalControl(session.agentId)
    return succeeded
  }
  const keyTerminalAction = async (target: string, key: string, allowed?: () => boolean): Promise<TerminalActionResult> => {
    const session = terminalSession(target)
    if (!session) return terminalActionNotStarted('terminal session is unavailable')
    const lease = await leasedTerminal(session)
    if (!lease) return terminalActionNotStarted(TERMINAL_LEASE_REFUSED)
    if (allowed && !allowed()) return terminalActionNotStarted('terminal control revoked')
    const result = await terminals.sendLegacyKeyLease(lease.value, key)
    if (result.state !== 'succeeded' && pinnedControls.has(session.agentId)) invalidateTerminalControl(session.agentId)
    return result
  }
  const keyTerminal = async (target: string, key: string, allowed?: () => boolean): Promise<boolean> => {
    return terminalActionSucceeded(await keyTerminalAction(target, key, allowed))
  }
  const validateTerminal = async (session: RegisteredSession): Promise<boolean> =>
    (await terminals.validate(session)).state === 'alive'
  /**
   * Whether a session's terminal is known to be gone: the agent is dormant, tmux has no such pane, or
   * another process is in it. Not the same question as `validateTerminal`, which is the one to ask before
   * writing to a pane: a probe that could not answer (it timed out, or the process table could not be
   * read) is no reason to write, and no evidence either that the terminal is gone.
   */
  const terminalGone = async (session: RegisteredSession): Promise<boolean> =>
    (await terminals.validate(session)).state === 'gone'
  return {
    pinnedControls, pinTerminalControl, invalidateTerminalControl, captureTerminal, submitTerminalAction,
    submitTerminal, typeTerminal, keyTerminalAction, keyTerminal, validateTerminal, terminalGone,
  }
}

export type TerminalControl = ReturnType<typeof createTerminalControl>