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.

7.5 KB
Raw Blame
/** Private, pull-driven live transcript protocol. A cursor acknowledges the previous complete page. */
import type { LiveEvent } from '../kit/events.js'
import type { LiveTurn } from '../facets/live.js'
import type { RegisteredSession } from '../../lib/registry.js'
import { record, sessionEvent } from './protocol.js'
import type { RuntimeRecord } from '../facets/runtime.js'
import { runtimeRecord } from './runtimeProtocol.js'
import type { TranscriptClose } from '../../lib/transcriptControls.js'

export const LIVE_VERSION = 1
export const LIVE_CAPABILITIES = 'engine_live_capabilities'
export const LIVE_PREPARE = 'engine_live_prepare'
export const LIVE_READ = 'engine_live_read'
export const LIVE_PART = 'engine_live_part'
export const LIVE_CLOSE = 'engine_live_close'
export const LIVE_FORGET = 'engine_live_forget'
export const LIVE_WAIT_MS = 15_000
export const LIVE_PAGE_BYTES = 1024 * 1024
/** Match the legacy tailer's small-rewrite replay limit; larger rewrites hydrate from their end. */
export const LIVE_HISTORY_BYTES = 32 * 1024 * 1024
/** A single record may exceed a page; transfer it in bounded fragments, never a giant socket frame. */
export const LIVE_RESULT_BYTES = 64 * 1024 * 1024
export const LIVE_PART_BYTES = 256 * 1024
export const LIVE_CACHE_BYTES = 128 * 1024 * 1024
export const LIVE_CACHE_SESSIONS = 256
export const LIVE_IN_FLIGHT = 1

export type LiveSession = Pick<RegisteredSession, 'agentId' | 'sessionId' | 'engine' | 'transcriptPath'
  | 'codexHome' | 'cwd' | 'model' | 'cliVersion'>

/** Bytes at the cursor, including file identity. Appends do not change it; replacement/truncation does. */
export interface LiveStamp { device: number; inode: number; bytes: number; digest: string }
export interface LiveCursor {
  /** Changes even for empty polls: acknowledging an empty page permits observing later appends. */
  serial: number
  /** The frozen end used to choose the original parser window. Recovery folds that same window,
   * including later accepted turns, preserving thinking ids, tool links and continuing goals. */
  origin: number
  offset: number
  turn: LiveTurn
  /** Core's explicit cancellation/relaunch closure, which is not necessarily present in the file. */
  closed: false | 'cancel' | 'abandoned' | 'hook'
  /** A frozen attach end while staging; null once this cursor belongs to a live tail. */
  prepareEnd: number | null
  /** A first turn emitted after activation may include its final complete, unterminated record. */
  completeUntil: number | null
  /** A rewritten file's existing records replay as history, even across pages or worker restart. */
  historyUntil?: number
  stamp: LiveStamp | null
}
export interface LiveFrame {
  raw: string
  /** Compact, engine-private profile evidence; core forwards it without interpreting vendor fields. */
  runtime?: RuntimeRecord | null
  /** Profile metadata can begin before the turn's parser window. */
  profile: boolean
  observe: boolean
  events: LiveEvent[]
  failure?: string
  replay: boolean
  turn: LiveTurn
}
export interface LivePage {
  frames: LiveFrame[]
  cursor: LiveCursor
  /** Attach reached its frozen end; later appends belong to a subsequent live read. */
  prepared?: true
  failed?: true
  content: boolean
  more: boolean
  records: number
  turnFrom: number
  profileFrom: number
  end: number
  lastStarted: LiveEvent | null
}

export function liveTurn(value: unknown): value is LiveTurn {
  return record(value) && typeof value.identity === 'string' && value.identity.length <= 512
    && typeof value.turnOpen === 'boolean' && typeof value.continued === 'boolean'
}
export function liveStamp(value: unknown): value is LiveStamp | null {
  return value === null || (record(value) && Number.isSafeInteger(value.device) && Number.isSafeInteger(value.inode)
    && typeof value.bytes === 'number' && Number.isInteger(value.bytes) && value.bytes > 0 && value.bytes <= 512
    && typeof value.digest === 'string' && /^[a-f0-9]{64}$/.test(value.digest))
}
export function liveCursor(value: unknown): value is LiveCursor {
  return record(value) && Number.isSafeInteger(value.serial) && (value.serial as number) >= 0
    && Number.isSafeInteger(value.origin) && (value.origin as number) >= 0
    && typeof value.offset === 'number' && Number.isSafeInteger(value.offset) && value.offset >= 0
    && liveTurn(value.turn) && [false, 'cancel', 'abandoned', 'hook'].includes(value.closed as false | string)
    && (value.prepareEnd === null || (typeof value.prepareEnd === 'number' && Number.isSafeInteger(value.prepareEnd) && value.prepareEnd >= value.offset))
    && (value.completeUntil === null || (typeof value.completeUntil === 'number' && Number.isSafeInteger(value.completeUntil) && value.completeUntil >= value.offset))
    && (value.historyUntil === undefined || (typeof value.historyUntil === 'number' && Number.isSafeInteger(value.historyUntil) && value.historyUntil > value.offset))
    && liveStamp(value.stamp)
}

export function liveEvent(value: unknown): value is LiveEvent {
  if (sessionEvent(value)) return true
  if (!record(value) || !record(value.payload)) return false
  const p = value.payload
  if (value.type === 'turn_started') return typeof p.userMessage === 'string'
  if (value.type === 'turn_ended') return p.aborted === undefined || p.aborted === true
  return value.type === 'subagent_finished' && typeof p.id === 'string' && typeof p.status === 'string'
    && (p.summary === undefined || typeof p.summary === 'string')
}

export function livePage(value: unknown): value is LivePage {
  if (!record(value) || !liveCursor(value.cursor) || !Array.isArray(value.frames)) return false
  if (![value.records, value.turnFrom, value.profileFrom, value.end].every(n => typeof n === 'number' && Number.isSafeInteger(n) && n >= 0)) return false
  return (value.end as number) >= value.cursor.offset && (value.profileFrom as number) <= (value.turnFrom as number)
    && typeof value.content === 'boolean' && typeof value.more === 'boolean' && (value.prepared === undefined || (value.prepared === true && value.cursor.prepareEnd === null))
    && (value.failed === undefined || value.failed === true)
    && (value.lastStarted === null || (liveEvent(value.lastStarted) && value.lastStarted.type === 'turn_started'))
    && value.frames.every(f => record(f) && typeof f.raw === 'string' && typeof f.profile === 'boolean'
      && typeof f.observe === 'boolean' && typeof f.replay === 'boolean' && liveTurn(f.turn)
      && (f.runtime === undefined || f.runtime === null || runtimeRecord(f.runtime))
      && (f.failure === undefined || typeof f.failure === 'string') && Array.isArray(f.events) && f.events.every(liveEvent))
}

export interface LivePull {
  token: string
  session: LiveSession
  /** Null only for the first page of an attach. Each later cursor acknowledges the previous page. */
  cursor: LiveCursor | null
  fromStart: boolean
  replay: boolean
  /** Activate an empty parser first, then stream the first turn with ordinary bounded live pages. */
  liveStart?: boolean
  /** Rebuild after replacement/truncation; stream a small rewritten file as history after activation. */
  rewritten?: boolean
  /** The stream whose read found the file rewritten. Its records up to where that read found them are
   *  history and the rest are live, as the legacy tailer placed the boundary when it noticed the rewrite.
   *  A worker that never saw that read, or a file changed again since, hydrates as `rewritten` alone. */
  rewrittenFrom?: string
  end?: number
  /** Eager core decisions retained across parser reconstruction, in native byte order. */
  closes?: readonly TranscriptClose[]
}