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.

12.7 KB
Raw Blame
import { nextQueryCandidate, parsePtyStartupQuery } from './pty-startup-query'
import { PtyOwnerColorQueryReplies } from './pty-owner-color-query-replies'
import { TerminalKittyKeyboardModeTracker } from './terminal-kitty-keyboard-mode-tracker'
import type { PtyOwnerBackend } from './pty-owner-backend'
import { PtyStartupReplyDelivery } from './pty-startup-reply-delivery'
import { deliverTerminalQueryReplyPayload } from './terminal-query-reply-delivery'
import {
  combinePtyIngressSourceSpans,
  slicePtyIngressSourceSpan,
  type PtyIngressEmission,
  type PtyIngressSourceSpan,
  type PtyStartupIngressOperation,
  type PtyStartupIngressOptions
} from './pty-startup-ingress-contract'

export {
  PTY_STARTUP_INGRESS_VERSION,
  parsePtyStartupIngressIntent
} from './pty-startup-ingress-intent'
export type { PtyStartupIngressIntent } from './pty-startup-ingress-intent'
export type { PtyIngressEmission, PtyStartupIngressOptions } from './pty-startup-ingress-contract'

// Allow relay jitter before releasing torn echoes raw (#12112). Next reads/snapshot barriers usually end the wait;
// only one projection’s echo-shaped bytes on an idle pane are exposed to this guess.
const ECHO_CONTINUATION_HOLD_MS = 500
// Why a default: every PTY has a startup window, because it bounds the long echo watch.
const DEFAULT_STARTUP_WINDOW_MS = 5_000

/** Serialize source classification after shell-ready preprocessing; emit each accepted range once. Own all lifetime OSC 10/11
 * queries here and strip them so viewers cannot answer twice; a launcher-pinned PTY's OSC 4/12 and ?996n too. Only Kitty
 * authority expires with startup. */
export class PtyStartupIngress {
  private readonly colorQueries: PtyOwnerColorQueryReplies
  private readonly ownerBackend: PtyOwnerBackend
  private readonly delivery: PtyStartupReplyDelivery
  private readonly onEmission: (emission: PtyIngressEmission) => void
  private readonly operations: PtyStartupIngressOperation[] = []
  private processing = false
  private closed = false
  /** Kitty authority closes with startup; a launcher-pinned PTY's appearance queries stay owned for life. */
  private readonly scope: { kitty: boolean; appearance: boolean }
  private readonly kittyModes = new TerminalKittyKeyboardModeTracker()
  private rawHighWater = 0
  private queryPending: PtyIngressSourceSpan | null = null
  private echoPending: PtyIngressSourceSpan | null = null
  private echoHoldTimer: ReturnType<typeof setTimeout> | null = null
  private queryHoldTimer: ReturnType<typeof setTimeout> | null = null
  private deadlineTimer: ReturnType<typeof setTimeout> | null = null

  constructor(options: PtyStartupIngressOptions) {
    this.colorQueries = new PtyOwnerColorQueryReplies(options.intent, options.resolveHostColors)
    this.ownerBackend = options.ownerBackend ?? 'posix-pty'
    this.delivery = new PtyStartupReplyDelivery(
      this.ownerBackend,
      options.write,
      Date.now() + (options.intent?.deadlineMs ?? DEFAULT_STARTUP_WINDOW_MS)
    )
    this.onEmission = options.onEmission
    this.scope = {
      kitty: options.intent?.kittyKeyboardProtocol === true,
      appearance: this.colorQueries.ownsAppearance
    }
    if (options.intent && this.scope.kitty) {
      this.deadlineTimer = setTimeout(
        () => this.enqueue({ kind: 'expire' }),
        Math.max(0, options.intent.deadlineMs)
      )
      this.deadlineTimer.unref?.()
    }
  }

  get acceptedRawSequence(): number {
    return this.rawHighWater
  }

  accept(data: string): void {
    if (this.closed || data.length === 0) {
      return
    }
    const rawStartSeq = this.rawHighWater
    this.rawHighWater += data.length
    this.enqueue({
      kind: 'data',
      chunk: { data, rawStartSeq, rawEndSeq: this.rawHighWater }
    })
  }

  closeQueryAuthority(): number {
    this.enqueue({ kind: 'close-query' })
    return this.rawHighWater
  }

  snapshotBarrier(): number {
    this.enqueue({ kind: 'snapshot' })
    return this.rawHighWater
  }

  answerLiveQueryReply(reply: string): boolean {
    return !this.closed && reply.length > 0
      ? deliverTerminalQueryReplyPayload(reply, this.delivery)
      : false
  }

  drainAndClose(): number {
    this.enqueue({ kind: 'teardown' })
    return this.rawHighWater
  }

  private enqueue(operation: PtyStartupIngressOperation): void {
    if (this.closed) {
      return
    }
    this.operations.push(operation)
    if (this.processing) {
      return
    }
    this.processing = true
    try {
      let next: PtyStartupIngressOperation | undefined
      while ((next = this.operations.shift())) {
        this.applyOperation(next)
      }
    } finally {
      this.processing = false
    }
  }

  private applyOperation(operation: PtyStartupIngressOperation): void {
    switch (operation.kind) {
      case 'data':
        this.processEchoSpan(operation.chunk)
        return
      case 'close-query':
        // Only Kitty authority closes; lifetime color replies and already-written echoes remain owner responsibilities.
        this.scope.kitty = false
        if (this.colorQueries.releasesTornCsi(this.queryPending?.data)) {
          this.releaseQueryPending()
        }
        return
      case 'expire':
        this.scope.kitty = false
        this.releasePendingInSourceOrder(false)
        this.clearDeadline()
        return
      case 'snapshot':
      case 'release-echo':
        this.releasePendingInSourceOrder(false)
        return
      case 'release-query':
        this.releaseQueryPending()
        return
      case 'teardown':
        this.scope.kitty = false
        this.releasePendingInSourceOrder(true)
        this.delivery.close()
        this.clearDeadline()
        this.clearQueryHold()
        this.closed = true
    }
  }

  /** Charge once per read in finally, after matching: complete echoes get their arriving read, and early-returning
   * partial candidates still age out. Never recharge carried bytes on every subsequent read. */
  private processEchoSpan(span: PtyIngressSourceSpan): void {
    try {
      this.classifyRead(span)
    } finally {
      this.delivery.chargeEchoSearch(span.data.length)
    }
  }

  private classifyRead(span: PtyIngressSourceSpan): void {
    let input = combinePtyIngressSourceSpans(this.takeEchoPending(), span)

    while (this.delivery.hasExpectedEcho && input.data.length > 0) {
      const match = this.delivery.matchEcho(input.data)
      if (match.kind !== 'complete') {
        // Echoes follow/coalesce with real shell output; emit the prefix now and retain only the candidate tail across reads.
        if (match.kind === 'partial') {
          const tail = slicePtyIngressSourceSpan(input, match.offset)
          if (match.offset > 0) {
            this.processQuerySpan(slicePtyIngressSourceSpan(input, 0, match.offset))
          }
          // Keep a query ahead of echo only while the combined candidate stays viable, including partial terminators.
          // BEL-led readline echoes can complete real queries; disproven candidates must release before the echo (#12112).
          // ConPTY’s ESC-stripped echo may remain query-shaped, but leaking it is preferable to withholding ESC and timing out.
          if (this.queryPending) {
            const resolved = combinePtyIngressSourceSpans(this.queryPending, tail)
            if (parsePtyStartupQuery(resolved.data, 0, this.scope).kind !== 'none') {
              this.processQuerySpan(tail)
              return
            }
            // Unlike ordinary ConPTY barrier release, combined candidate+tail is now disproven as a query; release it unconditionally.
            this.releaseQueryPending()
          }
          this.echoPending = tail
          this.armEchoHold()
          return
        }
        break
      }
      if (match.offset > 0) {
        this.processQuerySpan(slicePtyIngressSourceSpan(input, 0, match.offset))
      }
      // Release torn candidates before suppressed ranges so raw sequence accounting stays aligned.
      this.releaseQueryPending()
      const echoEnd = match.offset + match.length
      this.emit(slicePtyIngressSourceSpan(input, match.offset, echoEnd), true, '')
      input = slicePtyIngressSourceSpan(input, echoEnd)
    }

    if (input.data.length > 0) {
      this.processQuerySpan(input)
    }
  }

  private processQuerySpan(span: PtyIngressSourceSpan): void {
    const input = combinePtyIngressSourceSpans(this.queryPending, span)
    this.queryPending = null
    this.clearQueryHold()
    const suppressConptyQuery = this.ownerBackend === 'windows-conpty'

    let scanOffset = 0
    let emittedOffset = 0
    while (scanOffset < input.data.length) {
      const candidateIndex = nextQueryCandidate(input.data, scanOffset, this.scope)
      if (candidateIndex === -1) {
        this.emit(slicePtyIngressSourceSpan(input, emittedOffset), false)
        return
      }
      const query = parsePtyStartupQuery(input.data, candidateIndex, this.scope)
      if (query.kind === 'none') {
        scanOffset = candidateIndex + 1
        continue
      }
      if (query.kind === 'partial') {
        if (candidateIndex > emittedOffset) {
          this.emit(slicePtyIngressSourceSpan(input, emittedOffset, candidateIndex), false)
        }
        const candidate = slicePtyIngressSourceSpan(input, candidateIndex)
        if (this.colorQueries.holdsCandidate(candidate.data)) {
          this.queryPending = candidate
          this.armQueryHold()
        } else {
          this.emit(candidate, false)
        }
        return
      }

      if (candidateIndex > emittedOffset) {
        this.emit(slicePtyIngressSourceSpan(input, emittedOffset, candidateIndex), false)
      }
      const querySpan = slicePtyIngressSourceSpan(input, candidateIndex, query.endIndex)
      // What stands in for an answered query: nothing, or a mixed OSC's SETs for the viewers.
      const replacement =
        query.kind === 'kitty'
          ? this.delivery.answer(`\x1b[?${this.kittyModes.flags}u`, 'owner')
            ? ''
            : null
          : this.colorQueries.answer(query, (reply) => this.delivery.answer(reply, 'owner'))
      if (query.kind === 'kitty' && replacement !== null) {
        this.scope.kitty = false
      }
      // A failed write passes the query on, except under ConPTY, whose ESC-stripped
      // echo of a downstream reply would leak into a cooked shell (#9651).
      const seen = query.kind === 'appearance'
      if (replacement !== null || (suppressConptyQuery && query.kind !== 'kitty')) {
        this.emit(querySpan, true, replacement ?? this.colorQueries.forwardedSets(query), seen)
      } else {
        this.emit(querySpan, false, querySpan.data, seen)
      }
      scanOffset = query.endIndex
      emittedOffset = query.endIndex
    }
  }

  private releaseQueryPending(): void {
    const pending = this.queryPending
    this.queryPending = null
    this.clearQueryHold()
    if (pending) {
      this.emit(pending, false)
    }
  }

  /** Release query before echo defensively: it would own earlier bytes, though current classification never arms both.
   * Retain torn colors across barriers unless explicitly included: viewers lack reply authority, so only hold timeout/teardown ends them. */
  private releasePendingInSourceOrder(includeColorQuery: boolean): void {
    if (includeColorQuery || this.colorQueries.releasesTornCsi(this.queryPending?.data)) {
      this.releaseQueryPending()
    }
    const pending = this.takeEchoPending()
    if (pending) {
      this.emit(pending, false)
    }
  }

  private takeEchoPending(): PtyIngressSourceSpan | null {
    const pending = this.echoPending
    this.echoPending = null
    if (this.echoHoldTimer) {
      clearTimeout(this.echoHoldTimer)
      this.echoHoldTimer = null
    }
    return pending
  }

  private armEchoHold(): void {
    if (this.echoHoldTimer) {
      return
    }
    this.echoHoldTimer = setTimeout(
      () => this.enqueue({ kind: 'release-echo' }),
      ECHO_CONTINUATION_HOLD_MS
    )
    this.echoHoldTimer.unref?.()
  }

  /** Why: a torn candidate that never completes must not withhold output indefinitely. */
  private armQueryHold(): void {
    this.queryHoldTimer ??= setTimeout(
      () => this.enqueue({ kind: 'release-query' }),
      ECHO_CONTINUATION_HOLD_MS
    )
    this.queryHoldTimer.unref?.()
  }

  private clearQueryHold(): void {
    clearTimeout(this.queryHoldTimer ?? undefined)
    this.queryHoldTimer = null
  }

  /** `seen`: the owner already recorded these bytes' colour SETs while answering them in order. */
  private emit(span: PtyIngressSourceSpan, transformed: boolean, data = span.data, seen = false) {
    if (this.scope.kitty) {
      this.kittyModes.scan(data)
    }
    if (!seen) {
      this.colorQueries.observe(data)
    }
    this.onEmission({ data, rawStartSeq: span.rawStartSeq, rawEndSeq: span.rawEndSeq, transformed })
  }

  private clearDeadline(): void {
    clearTimeout(this.deadlineTimer ?? undefined)
    this.deadlineTimer = null
  }
}