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.

20.3 KB
Raw Blame
/** Eager state/control owner; native interpretation is supplied by engine facets. */
import { parseRuntimeProfile } from './runtimeProfileWire.js'
export { parseRuntimeProfile } from './runtimeProfileWire.js'
import type { RegisteredSession } from './registry.js'
import type { RuntimeFor, RuntimeProfile, RuntimeModelOption, RuntimeState, RuntimeField, RuntimeControl, RuntimeCatalogModel } from '../engines/facets/runtime.js'
import type { InlineRuntimeContext, InlineRuntimeReader } from '../engines/facets/inlineRuntime.js'
export type { RuntimeProfile, RuntimeModelOption, RuntimeState, RuntimeField } from '../engines/facets/runtime.js'
import { encodeRuntimeProfile, fillConfiguredEffort, record, showEffort, stripAnsi, transcriptFields, RUNTIME_EFFORTS } from '../engines/kit/runtime.js'
export { encodeRuntimeProfile, runtimeModelLabel } from '../engines/kit/runtime.js'
import { engineNow, isOtherEngine, loadEngine } from '../engines/inProcess.js'
import { processIdentityKey } from './terminalRuntime.js'

const blankState = (): RuntimeState => ({ model: null, effort: null, mode: 'unknown', cliVersion: null, observedAt: null })

/** Where a session's runtime state starts before its transcript is read. */
function freshState(session: RegisteredSession): RuntimeState {
  return {
    ...blankState(),
    // Registries written by older builds can hold a non-string model; treat it as unknown instead of
    // letting it reach claudeAliasForModel and abort startup.
    model: typeof session.model === 'string' ? session.model : null,
    cliVersion: session.cliVersion,
  }
}

interface StateWaiter {
  check: () => boolean
  resolve: (matched: boolean) => void
  timer: NodeJS.Timeout
}

const EFFORTS = RUNTIME_EFFORTS
const CHANGE_DEBOUNCE_MS = 120
const readIdentity = (session: RegisteredSession): string => JSON.stringify([session.agentId, session.sessionId,
  session.engine, session.cwd, session.transcriptPath, session.codexHome, session.hermesHome,
  session.model, session.cliVersion, session.boundAt, session.tmuxPane, session.primaryRuntimeKey, session.runtimes,
  session.active, session.evidenceRevision, !!session.identityHold, session.processIdentity ? processIdentityKey(session.engine, session.processIdentity) : undefined])
const copyControl = (control: RuntimeControl | undefined): RuntimeControl | undefined => control && {
  ...control, target: { ...control.target },
}

export class RuntimeProfileState {
  constructor(private readonly runtimeFor: RuntimeFor,
    private readonly resolve?: (agentId: string) => RegisteredSession | undefined) {}
  private readonly states = new Map<string, RuntimeState>()
  private readonly controls = new Map<string, RuntimeControl>()
  private readonly waiters = new Map<string, Set<StateWaiter>>()
  private readonly changeTimers = new Map<string, NodeJS.Timeout>()
  private readonly readers = new Map<string, InlineRuntimeReader>()
  private readonly failedReaders = new Set<string>()
  private readonly versions = new WeakMap<RuntimeState, number>()
  private readonly configReads = new WeakMap<RuntimeState, object>()
  private suppressNotifications = 0
  onChanged: ((sessionId: string) => void) | null = null

  private version(state: RuntimeState): number { return this.versions.get(state) ?? 0 }
  private accepted(state: RuntimeState): void { this.versions.set(state, this.version(state) + 1) }
  private authoritative(state: RuntimeState): void {
    this.accepted(state)
    // Core confirmation/control revokes queued reads as well as reads already in flight.
    this.configReads.set(state, {})
  }
  private currentSession(session: RegisteredSession, identity = readIdentity(session)): RegisteredSession | undefined {
    const current = this.resolve ? this.resolve(session.agentId) : session
    return current && !current.identityHold && readIdentity(current) === identity && readIdentity(session) === identity ? current : undefined
  }

  private observe(context: InlineRuntimeContext): InlineRuntimeContext {
    // A repeated authoritative value is still newer evidence. Track writes, not value differences;
    // ignored transcript records must not starve a pending config read during a long answer.
    const track = <T extends object>(value: T): T => new Proxy(value, { set: (target, key, next) => {
      this.accepted(context.state)
      return Reflect.set(target, key, next)
    } })
    return { ...context, state: track(context.state), control: context.control && track(context.control) }
  }

  private keep(engine: string, module: { createRuntimeProfileReader?: () => InlineRuntimeReader }): InlineRuntimeReader | null {
    const existing = this.readers.get(engine)
    if (existing) return existing
    if (this.failedReaders.has(engine)) return null
    try {
      const reader = module.createRuntimeProfileReader?.()
      if (!reader || reader.engine !== engine) throw new Error('runtime reader is missing or belongs to another engine')
      this.readers.set(engine, reader)
      return reader
    } catch (error) {
      this.failedReaders.add(engine)
      console.warn(`[runtime-profile] ${engine} reader unavailable:`, error instanceof Error ? error.message : String(error))
      return null
    }
  }

  private readerNow(engine: string): InlineRuntimeReader | null {
    if (!isOtherEngine(engine)) return null
    const module = engineNow(engine, 'its profile was read')
    if (!module) return null
    return this.keep(engine, module)
  }

  private async reader(engine: string): Promise<InlineRuntimeReader | null> {
    if (!isOtherEngine(engine)) return null
    const module = await loadEngine(engine)
    if (!module) return null
    return this.keep(engine, module)
  }

  private context(session: RegisteredSession, silent: boolean): InlineRuntimeContext {
    const state = this.state(session.sessionId)
    const identity = readIdentity(session)
    return { session, state, control: this.controls.get(session.sessionId),
      refreshConfig: (override) => {
        const read = this.configReads.get(state)
        // Finish accepting the synchronous observation before starting its dependent config read.
        queueMicrotask(() => {
          if (this.states.get(session.sessionId) === state && this.currentSession(session, identity)
            && this.configReads.get(state) === read) {
            void this.ingestConfig(session, override ?? silent).catch(() => undefined)
          }
        })
      } }
  }

  private observed(session: RegisteredSession, before: string | null, silent: boolean): boolean {
    const after = this.selectedModel(session)
    this.wake(session.sessionId)
    if (!silent && this.suppressNotifications === 0 && before !== after && !this.controls.has(session.sessionId)) this.scheduleChanged(session.sessionId)
    return before !== after
  }

  ingest(session: RegisteredSession, rawLine: string, silent = false): boolean {
    const current = this.currentSession(session)
    if (!current) return false
    session = current
    let raw: Record<string, unknown> | null
    try { raw = record(JSON.parse(rawLine)) } catch { return false }
    if (!raw) return false
    const before = this.selectedModel(session)
    const runtime = this.runtimeFor(session.engine)
    const context = this.observe(this.context(session, silent))
    if (runtime) runtime.transcript(context, raw)
    else this.readerNow(session.engine)?.transcript?.(context, raw)
    return this.observed(session, before, silent)
  }

  ingestPane(session: RegisteredSession, paneText: string, silent = false): boolean {
    const current = this.currentSession(session)
    if (!current) return false
    session = current
    const before = this.selectedModel(session)
    const runtime = this.runtimeFor(session.engine)
    const context = this.observe(this.context(session, silent))
    const text = stripAnsi(paneText)
    if (runtime) runtime.pane(context, text)
    else if (this.readerNow(session.engine)?.pane?.(context, text) === false) return false
    return this.observed(session, before, silent)
  }

  /** Capture and consume one observation under the binding and authority that requested it. */
  async capturePane(session: RegisteredSession, capture: (id: string, historyLines?: number) => Promise<string | null>,
    historyLines?: number, silent = false): Promise<string | null> {
    if (this.unbound(session.sessionId) || !this.currentSession(session)) return null
    const id = session.sessionId, identity = readIdentity(session)
    const state = this.state(id), version = this.version(state)
    const text = await capture(session.agentId, historyLines)
    if (!text || this.states.get(id) !== state || this.version(state) !== version || !this.currentSession(session, identity)) return null
    this.ingestPane(session, text, silent)
    return text
  }

  async ingestConfig(session: RegisteredSession, silent = false): Promise<boolean> {
    if (this.unbound(session.sessionId) || !this.currentSession(session)) return false
    const state = this.state(session.sessionId), version = this.version(state)
    const identity = readIdentity(session), token = {}
    const control = this.controls.get(session.sessionId)
    this.configReads.set(state, token)
    const current = () => this.states.get(session.sessionId) === state && this.version(state) === version
      && this.configReads.get(state) === token && !!this.currentSession(session, identity)
      && this.controls.get(session.sessionId) === control
    const runtime = this.runtimeFor(session.engine)
    const reader = runtime ? null : await this.reader(session.engine)
    if (!current() || (!runtime?.configuredEffort && !reader?.config)) return false
    const before = this.selectedModel(session)
    const context = { ...this.context(session, silent), session: { ...session }, state: { ...state }, control: copyControl(control) }
    if (runtime?.configuredEffort) fillConfiguredEffort(context.state, await runtime.configuredEffort(context.session))
    else if (!await reader!.config!(context)) return false
    // An optional reader cannot publish into a forgotten/rebound row or replace newer evidence.
    if (!current()) return false
    Object.assign(state, context.state)
    if (control) Object.assign(control, context.control)
    this.accepted(state)
    return this.observed(session, before, silent)
  }

  supportsControl(session: RegisteredSession): boolean {
    return !session.gateway && (this.runtimeFor(session.engine)?.supportsControl(session) ?? false)
  }

  effortAllowed(session: RegisteredSession, model: string, effort: string, listed: readonly string[] | null): boolean {
    return this.runtimeFor(session.engine)?.effortAllowed?.(model, effort, listed) ?? false
  }

  hydrate(session: RegisteredSession, rawLines: string[]): void {
    if (this.unbound(session.sessionId) || !this.currentSession(session)) return
    this.states.set(session.sessionId, freshState(session))
    for (const line of rawLines) this.ingest(session, line, true)
  }

  beginHydrate(session: RegisteredSession): {
    ingest(rawLine: string): void
    commit(): void
    config?(): Promise<void>
    commitWith?(install: () => boolean): boolean
  } {
    const previous = this.state(session.sessionId), version = this.version(previous)
    const identity = readIdentity(session), control = this.controls.get(session.sessionId)
    const stagedSession = { ...session }, stagedControl = copyControl(control)
    const staged = freshState(session)
    let committed = false, failed = false
    const current = () => !committed && !failed && !this.unbound(session.sessionId)
      && this.states.get(session.sessionId) === previous && this.version(previous) === version
      && !!this.currentSession(session, identity) && this.controls.get(session.sessionId) === control
    const commitWith = (install: () => boolean): boolean => {
      if (!current() || !install()) return false
      committed = true
      this.currentSession(session, identity)!.cliVersion = stagedSession.cliVersion
      if (control) Object.assign(control, stagedControl)
      this.states.set(session.sessionId, staged)
      this.wake(session.sessionId)
      return true
    }
    return {
      ingest: (rawLine) => {
        if (!current()) return
        let raw: Record<string, unknown> | null
        try { raw = record(JSON.parse(rawLine)) } catch { return }
        if (!raw) return
        this.runtimeFor(stagedSession.engine)?.transcript({ session: stagedSession, state: staged, control: stagedControl }, raw)
      },
      config: async () => {
        if (!current()) return
        try {
          const runtime = this.runtimeFor(stagedSession.engine)
          if (runtime?.configuredEffort) fillConfiguredEffort(staged, await runtime.configuredEffort(stagedSession))
          else if (!runtime) {
            const reader = await this.reader(stagedSession.engine)
            if (current()) await reader?.config?.({ session: stagedSession, state: staged, control: stagedControl, refreshConfig: () => {} })
          }
        } catch (error) { failed = true; throw error }
      },
      commitWith,
      commit: () => { commitWith(() => true) },
    }
  }

  transcriptFields(session: RegisteredSession, rawLine: string): RuntimeField[] {
    return transcriptFields(this.runtimeFor(session.engine), session, rawLine)
  }

  getState(sessionId: string): RuntimeState {
    return { ...this.state(sessionId) }
  }

  async withoutChangeEvents<T>(operation: () => Promise<T>): Promise<T> {
    this.suppressNotifications++
    try { return await operation() } finally { this.suppressNotifications-- }
  }

  selectedModel(session: RegisteredSession): string | null {
    if (this.unbound(session.sessionId)) return null
    const state = this.states.get(session.sessionId)
    if (!state?.model) return null
    const adapter = this.runtimeFor(session.engine)
    if (adapter) return adapter.selectedModel(session, state)
    const model = state.model
    const effort = state.effort
    if (!effort) return null
    return encodeRuntimeProfile({
      sessionId: session.agentId,
      engine: session.engine,
      model,
      effort,
    })
  }

  beginControl(session: RegisteredSession, target: RuntimeProfile): boolean {
    if (this.controls.has(session.sessionId)) return false
    const before = this.selectedModel(session)
    const current = parseRuntimeProfile(before)
    this.controls.set(session.sessionId, {
      target,
      before,
      modelConfirmed: current?.model === target.model,
      effortConfirmed: current?.effort === target.effort,
    })
    this.authoritative(this.state(session.sessionId))
    return true
  }

  cancelControl(sessionId: string): void {
    const control = this.controls.get(sessionId)
    this.controls.delete(sessionId)
    const state = this.states.get(sessionId)
    if (state) this.authoritative(state)
    this.wake(sessionId)
    if (control) this.scheduleChanged(sessionId)
  }

  finishControl(session: RegisteredSession): void {
    this.controls.delete(session.sessionId)
    const state = this.states.get(session.sessionId)
    if (state) this.authoritative(state)
    this.wake(session.sessionId)
    this.scheduleChanged(session.sessionId)
  }

  confirmEffort(sessionId: string, effort: string): void {
    if (!EFFORTS.has(effort)) return
    const state = this.state(sessionId)
    showEffort(state, effort)
    this.authoritative(state)
    const control = this.controls.get(sessionId)
    if (control) control.effortConfirmed = control.target.effort === effort
    this.wake(sessionId)
  }

  confirmControlProfile(target: RuntimeProfile): void {
    const state = this.state(target.sessionId)
    state.model = target.model
    showEffort(state, target.effort)
    this.authoritative(state)
    const control = this.controls.get(target.sessionId)
    if (control?.target.id === target.id) {
      control.modelConfirmed = true
      control.effortConfirmed = true
    }
    this.wake(target.sessionId)
  }

  waitForModel(sessionId: string, timeoutMs: number): Promise<boolean> {
    return this.waitFor(sessionId, () => this.controls.get(sessionId)?.modelConfirmed === true, timeoutMs)
  }

  waitForProfile(sessionId: string, timeoutMs: number): Promise<boolean> {
    return this.waitFor(sessionId, () => {
      const control = this.controls.get(sessionId)
      return control?.modelConfirmed === true && control.effortConfirmed === true
    }, timeoutMs)
  }

  forget(sessionId: string): void {
    this.states.delete(sessionId)
    this.controls.delete(sessionId)
    const timer = this.changeTimers.get(sessionId)
    if (timer) clearTimeout(timer)
    this.changeTimers.delete(sessionId)
    for (const waiter of this.waiters.get(sessionId) ?? []) {
      clearTimeout(waiter.timer)
      waiter.resolve(false)
    }
    this.waiters.delete(sessionId)
    // Native cleanup is optional and cannot interrupt the caller's eager tail/input/turn cleanup.
    const readers = [...this.readers.values()]
    queueMicrotask(() => {
      if (this.states.has(sessionId)) return
      for (const reader of readers) {
        try { reader.forget?.(sessionId) }
        catch (error) { console.warn(`[runtime-profile] ${reader.engine} cleanup failed:`, error instanceof Error ? error.message : String(error)) }
      }
    })
  }

  async modelsForSessions(sessions: RegisteredSession[]): Promise<RuntimeModelOption[]> {
    const groups = await Promise.all(sessions.map((session) => this.modelsForSession(session)))
    return groups.flat()
  }

  async modelsForSession(session: RegisteredSession): Promise<RuntimeModelOption[]> {
    // Display-only through a gateway: the empty catalogue IS the mechanism (see the note above), so web
    // renders a static chip and the device picker closes instead of offering a list we cannot enumerate.
    if (session.gateway) return []
    return this.runtimeFor(session.engine)?.models(session, this.states.get(session.sessionId)) ?? []
  }

  private unbound(sessionId: string): boolean {
    return !sessionId
  }

  private state(sessionId: string): RuntimeState {
    if (this.unbound(sessionId)) return blankState()
    let state = this.states.get(sessionId)
    if (!state) {
      state = blankState()
      this.states.set(sessionId, state)
    }
    return state
  }

  async codexCatalog(session: RegisteredSession): Promise<RuntimeCatalogModel[]> {
    return this.runtimeFor(session.engine)?.catalog?.(session) ?? []
  }

  private scheduleChanged(sessionId: string): void {
    const previous = this.changeTimers.get(sessionId)
    if (previous) clearTimeout(previous)
    this.changeTimers.set(sessionId, setTimeout(() => {
      this.changeTimers.delete(sessionId)
      if (!this.controls.has(sessionId)) this.onChanged?.(sessionId)
    }, CHANGE_DEBOUNCE_MS))
  }

  private waitFor(sessionId: string, check: () => boolean, timeoutMs: number): Promise<boolean> {
    if (check()) return Promise.resolve(true)
    return new Promise((resolve) => {
      const waiter: StateWaiter = {
        check,
        resolve,
        timer: setTimeout(() => {
          this.waiters.get(sessionId)?.delete(waiter)
          resolve(false)
        }, timeoutMs),
      }
      const set = this.waiters.get(sessionId) ?? new Set<StateWaiter>()
      set.add(waiter)
      this.waiters.set(sessionId, set)
    })
  }

  private wake(sessionId: string): void {
    const set = this.waiters.get(sessionId)
    if (!set) return
    for (const waiter of [...set]) {
      if (!waiter.check()) continue
      clearTimeout(waiter.timer)
      set.delete(waiter)
      waiter.resolve(true)
    }
    if (set.size === 0) this.waiters.delete(sessionId)
  }

  cursorTarget(sessionId: string, profileId: string) {
    const reader = this.readerNow('cursor')
    return reader?.engine === 'cursor' ? reader.target(sessionId, profileId) : null
  }

  devinTarget(sessionId: string, profileId: string) {
    const reader = this.readerNow('devin')
    return reader?.engine === 'devin' ? reader.target(sessionId, profileId) : null
  }

  hermesTarget(sessionId: string, profileId: string) {
    const reader = this.readerNow('hermes')
    return reader?.engine === 'hermes' ? reader.target(sessionId, profileId) : null
  }

  commandcodeTarget(sessionId: string, profileId: string) {
    const reader = this.readerNow('commandcode')
    return reader?.engine === 'commandcode' ? reader.target(sessionId, profileId) : null
  }

  async opencodeCatalog() {
    const reader = await this.reader('opencode')
    return reader?.engine === 'opencode' ? reader.catalog() : []
  }

  async kiloCatalog() {
    const reader = await this.reader('kilo')
    return reader?.engine === 'kilo' ? reader.catalog() : []
  }

}