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.

15.0 KB
Raw Blame
import { randomUUID } from 'node:crypto'
import type { LiveState } from '../../engines/facets/live.js'
import type { LiveFrame, LivePage, LivePull } from '../../engines/worker/liveProtocol.js'
import type { RegisteredSession } from '../../lib/registry.js'
import { HOLD_TIMEOUT_MS, type TailHold } from '../../watcher/watcher.js'
import { transcriptReadIdentity } from '../transcripts/readIdentity.js'
import { EngineLiveError, type LiveTransport } from './liveTransport.js'
import type { TranscriptClose } from '../../lib/transcriptControls.js'

interface SessionState {
  ask: LivePull
  identity: string
  epoch: number
  handle: LiveState
}
interface Tail {
  path: string
  dirty: boolean
  running: Promise<void> | null
  timer: ReturnType<typeof setTimeout> | null
  holds: Set<TailHold>
  unheld: Promise<void> | null
  release: (() => void) | null
  moves: number
  offset: number | null
  rewritten: boolean
}
export interface PreparedLive {
  state: SessionState
  parent: SessionState | undefined
  parentEpoch: number | undefined
  moves: number
  page: LivePage
  records: number
  content: boolean
}
export interface LiveSessionDeps {
  handles(engine: string): boolean
  transport: LiveTransport
  bySession(id: string): RegisteredSession | undefined
  frame(session: RegisteredSession, frame: LiveFrame): void
  /** Reduce side evidence before acknowledging the page; the returned commit must be synchronous. */
  prepareFrames?(session: RegisteredSession, frames: readonly LiveFrame[]): Promise<() => boolean>
  reattach(session: RegisteredSession): Promise<unknown>
  hold?(session: RegisteredSession, reason: string): void
  watch(path: string): void
  unwatch(path: string): void
  log?(message: string): void
}

/** Core retains only binding facts and the last accepted checkpoint. Unread events stay on disk. */
export function createLiveSessions(deps: LiveSessionDeps) {
  const states = new Map<string, SessionState>()
  const firstLive = new Map<string, string>()
  const tails = new Map<string, Tail>()
  const retries = new Map<string, ReturnType<typeof setTimeout>>()
  const queues = new Map<string, Promise<void>>()
  const queued = new Map<string, number>()
  const errors = new Map<string, string>()
  let stopped = false
  const valid = (s: SessionState): boolean => !stopped && s.identity === transcriptReadIdentity(deps.bySession(s.ask.session.sessionId))
  const report = (id: string, error: unknown): void => {
    const code = error instanceof Error ? error.message : String(error)
    if (errors.get(id) === code) return
    errors.set(id, code)
    ;(deps.log ?? console.warn)(`[engine] ${id} transcript paused at its acknowledged position · ${code}`)
  }
  const slot = async <T>(engine: string, run: () => Promise<T>): Promise<T> => {
    if ((queued.get(engine) ?? 0) >= 256) throw new EngineLiveError('ENGINE_BUSY')
    queued.set(engine, (queued.get(engine) ?? 0) + 1)
    const before = queues.get(engine) ?? Promise.resolve()
    let release!: () => void
    const current = new Promise<void>(resolve => { release = resolve })
    queues.set(engine, current)
    await before
    try { return await run() } finally {
      queued.set(engine, queued.get(engine)! - 1); release()
      if (queues.get(engine) === current) queues.delete(engine)
    }
  }
  const pull = (ask: LivePull) => slot(ask.session.engine, () => {
    if (stopped) throw new EngineLiveError('ENGINE_UNAVAILABLE')
    return deps.transport.pull(ask)
  })
  // Forget shares the worker's one request slot with pulls. Otherwise activating a replacement can
  // make its first read fail ENGINE_BUSY while the old parser is still being released.
  const forget = (engine: string, token: string): void => {
    void slot(engine, () => deps.transport.forget(engine, token)).catch(() => {})
  }
  const makeState = (session: RegisteredSession, live: boolean, end?: number, closes?: readonly TranscriptClose[]): SessionState => {
    const state: SessionState = { identity: transcriptReadIdentity(session), epoch: 0,
      ask: { token: randomUUID(), session: { agentId: session.agentId, sessionId: session.sessionId,
        engine: session.engine, transcriptPath: session.transcriptPath, cwd: session.cwd, model: session.model,
        cliVersion: session.cliVersion, codexHome: session.codexHome }, cursor: null, fromStart: live,
        replay: false, liveStart: live, ...(end === undefined ? {} : { end }), ...(closes?.length ? { closes } : {}),
        // The stream still installed is the one whose read found the rewrite: its worker knows where.
        ...(tails.get(session.sessionId)?.rewritten ? { rewritten: true, rewrittenFrom: states.get(session.sessionId)?.ask.token } : {}) },
      handle: {
        engine: session.engine,
        // Handles escape prepare only after the worker has supplied a validated cursor.
        get turnOpen() { return state.ask.cursor!.turn.turnOpen },
        snapshot: () => ({ ...state.ask.cursor!.turn }),
        closeTurn(reason) {
          const cursor = state.ask.cursor!
          // An in-flight reply predates this decision and cannot overwrite it. Reconstructing from this
          // checkpoint applies the engine's own close semantics before reading unseen records.
          state.epoch++
          state.ask.cursor = { ...cursor, closed: reason, turn: { ...cursor.turn, turnOpen: false } }
          schedule(session.sessionId)
        },
      },
    }
    return state
  }
  const retry = (session: RegisteredSession): void => {
    const id = session.sessionId, identity = transcriptReadIdentity(session)
    if (stopped || retries.has(id)) return
    retries.set(id, setTimeout(() => {
      retries.delete(id)
      // Retry with the row as it is now. A snapshot from before the runtime learned the CLI version
      // fails the same staleness check every time (2026-10-19: 7 of 42 new Claude agents, once a second).
      const latest = deps.bySession(id)
      if (!latest || identity !== transcriptReadIdentity(latest)) return
      // A copy: the registry mutates rows in place, and the next retry must compare against this attempt's identity.
      const attempt = { ...latest }
      void deps.reattach(attempt).catch(error => { report(id, error); retry(attempt) })
    }, 1_000))
  }
  function schedule(id: string, delay = 40): void {
    const tail = tails.get(id)
    if (!tail || stopped) return
    tail.dirty = true
    if (tail.timer || tail.running || tail.holds.size || tail.offset !== null) return
    tail.timer = setTimeout(() => {
      tail.timer = null
      void pollSession(id).catch(error => { report(id, error); schedule(id, 1_000) })
    }, delay)
  }
  async function pollSession(id: string): Promise<void> {
    const tail = tails.get(id)
    if (!tail || stopped || deps.bySession(id)?.interpretationHold) return
    if (tail.unheld) await tail.unheld
    if (tail.running) return tail.running
    if (tail.offset !== null || tails.get(id) !== tail) return
    tail.dirty = false
    tail.running = (async () => {
      let more = true
      while (more && !stopped && tails.get(id) === tail && !tail.holds.size && tail.offset === null) {
        const state = states.get(id)
        if (!state || !valid(state)) return
        const epoch = state.epoch
        let page: LivePage
        try { page = await pull({ ...state.ask }) }
        catch (error) {
          if (error instanceof EngineLiveError && error.code === 'ENGINE_CONTROL_BOUNDARY_CHANGED'
            && valid(state) && states.get(id) === state && state.epoch === epoch) {
            deps.hold?.(deps.bySession(id)!, 'The transcript no longer matches its cancellation boundary; interpretation is held.')
          }
          if (error instanceof EngineLiveError && error.code === 'ENGINE_TRANSCRIPT_CHANGED') {
            // No cursor from the changed file is accepted. Re-attach under a hold and a new identity.
            // Said once per rewrite, as the legacy tailer says it (core/transcripts/ingest.ts).
            if (!tail.rewritten) (deps.log ?? console.log)(`[engine] ${id} transcript rewritten in place — attaching it again from where it was rewritten`)
            tail.rewritten = true
            const session = deps.bySession(id)
            if (session) retry(session)
          }
          throw error
        }
        if (!valid(state) || states.get(id) !== state || state.epoch !== epoch) return
        const session = deps.bySession(id)!
        if (deps.prepareFrames) {
          const commit = await deps.prepareFrames(session, page.frames)
          if (!valid(state) || states.get(id) !== state || state.epoch !== epoch) return
          if (!commit()) throw new EngineLiveError('ENGINE_STALE_REPLY')
        }
        state.ask.cursor = page.cursor
        errors.delete(id)
        for (const frame of page.frames) {
          try { deps.frame(session, frame) } catch (error) { report(id, error) }
        }
        more = page.more
      }
    })()
    let failed = false
    try { await tail.running } catch (error) { failed = true; tail.dirty = true; throw error } finally {
      tail.running = null
      if (tail.dirty) schedule(id, failed ? 1_000 : 40)
    }
  }
  const removeSession = async (id: string): Promise<void> => {
    firstLive.delete(id)
    const state = states.get(id); states.delete(id)
    if (state) { state.epoch++; forget(state.ask.session.engine, state.ask.token) }
    const tail = tails.get(id); tails.delete(id)
    if (tail) {
      if (tail.timer) clearTimeout(tail.timer)
      for (const hold of [...tail.holds]) hold.release()
      if (![...tails.values()].some(other => other.path === tail.path)) deps.unwatch(tail.path)
    }
    const timer = retries.get(id)
    if (timer) clearTimeout(timer)
    retries.delete(id); errors.delete(id)
  }
  return {
    handles: deps.handles,
    current(session: RegisteredSession): boolean { return states.get(session.sessionId)?.identity === transcriptReadIdentity(session) },
    async prepare(session: RegisteredSession, options: { live: boolean; end?: number; closes?: readonly TranscriptClose[] }, observe: (frame: LiveFrame) => void,
      observePage?: (frames: readonly LiveFrame[]) => Promise<void>): Promise<PreparedLive> {
      // A retry has no original attach flags. Keep first-turn delivery intent until activation;
      // otherwise a failed first prepare turns the user's completed first response into silent history.
      if (options.live) firstLive.set(session.sessionId, transcriptReadIdentity(session))
      const state = makeState(session, firstLive.get(session.sessionId) === transcriptReadIdentity(session), options.end, options.closes)
      const parent = states.get(session.sessionId), parentEpoch = parent?.epoch
      const moves = tails.get(session.sessionId)?.moves ?? 0
      let records = 0, content = false
      try {
        for (;;) {
          const page = await pull(state.ask)
          if (!valid(state)) throw new EngineLiveError('ENGINE_STALE_REPLY')
          if (observePage) {
            await observePage(page.frames)
            if (!valid(state)) throw new EngineLiveError('ENGINE_STALE_REPLY')
          }
          state.ask.cursor = page.cursor; records += page.records; content ||= page.content
          for (const frame of page.frames) observe(frame)
          if (page.prepared) return { state, parent, parentEpoch, moves, page, records, content }
        }
      } catch (error) {
        forget(session.engine, state.ask.token)
        report(session.sessionId, error)
        throw error
      }
    },
    install(prepared: PreparedLive): boolean {
      const { state, parent, parentEpoch, moves } = prepared, id = state.ask.session.sessionId
      if (!valid(state) || states.get(id) !== parent || parent?.epoch !== parentEpoch || (tails.get(id)?.moves ?? 0) !== moves) return false
      states.set(id, state)
      firstLive.delete(id)
      const tail = tails.get(id)
      if (tail) { tail.offset = null; tail.rewritten = false }
      errors.delete(id)
      const timer = retries.get(id)
      if (timer) clearTimeout(timer)
      retries.delete(id)
      if (parent) forget(parent.ask.session.engine, parent.ask.token)
      return true
    },
    discard(prepared: PreparedLive): void {
      forget(prepared.state.ask.session.engine, prepared.state.ask.token)
    },
    retry,
    async follow(session: RegisteredSession): Promise<void> {
      const id = session.sessionId, path = session.transcriptPath
      if (!path || !states.has(id)) return
      const previous = tails.get(id)
      if (previous?.path === path) { schedule(id); return }
      if (previous) {
        tails.delete(id)
        if (previous.timer) clearTimeout(previous.timer)
        for (const hold of [...previous.holds]) hold.release()
        if (![...tails.values()].some(other => other.path === previous.path)) deps.unwatch(previous.path)
      }
      tails.set(id, { path, dirty: false, running: null, timer: null, holds: new Set(), unheld: null,
        release: null, moves: 0, offset: null, rewritten: false })
      deps.watch(path)
      // First-turn delivery follows activation. It never builds one unbounded initialEvents array.
      await pollSession(id).catch(error => { report(id, error); schedule(id, 1_000) })
    },
    changed(path: string): void { for (const [id, tail] of tails) if (tail.path === path) schedule(id) },
    tails(id: string, path: string): boolean { return tails.get(id)?.path === path },
    async hold(id: string, path: string, timeoutMs = HOLD_TIMEOUT_MS): Promise<TailHold | null> {
      const tail = tails.get(id)
      if (!tail || tail.path !== path) return null
      let expired = false, released = false
      let offset = 0
      const hold: TailHold = {
        get offset() { return offset }, get expired() { return expired },
        // Installation already puts the precise new cursor in the session. A released hold cannot
        // move it back after a reset or an explicit setTail changed the transcript underneath it.
        release() {
          if (released) return
          released = true; clearTimeout(timer); tail.holds.delete(hold)
          if (!tail.holds.size) { tail.release?.(); tail.release = null; tail.unheld = null; schedule(id) }
        },
      }
      const timer = setTimeout(() => { expired = true; hold.release() }, timeoutMs)
      if (!tail.holds.size) tail.unheld = new Promise(resolve => { tail.release = resolve })
      tail.holds.add(hold)
      await tail.running?.catch(() => {})
      offset = tail.offset ?? states.get(id)?.ask.cursor?.offset ?? 0
      return hold
    },
    setTail(id: string, offset: number): void {
      const tail = tails.get(id), state = states.get(id)
      if (!tail || !state) return
      state.epoch++; tail.moves++; tail.offset = offset; tail.rewritten = false
      const session = deps.bySession(id)
      if (session) retry(session)
    },
    pollSession,
    async pollAll(): Promise<void> { await Promise.all([...tails.keys()].map(id => pollSession(id).catch(error => { report(id, error); schedule(id, 1_000) }))) },
    removeSession,
    async stop(): Promise<void> {
      stopped = true
      await Promise.all([...new Set([...states.keys(), ...tails.keys(), ...retries.keys(), ...firstLive.keys()])].map(removeSession))
    },
  }
}

export type LiveSessions = ReturnType<typeof createLiveSessions>