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.2 KB
Raw Blame
/**
 * Discovery: what the reconciler's scans of the terminal backends and their processes mean for the
 * registry. A process no row owns opens an agent; a row's own process updates it (runtimes, identity,
 * permissions, profile homes, DSH) and wakes a dormant one; a row whose engine exited keeps its
 * conversation or goes dormant; a row whose pane is gone is removed, unless restore never ran.
 *
 * Moved verbatim out of the reconciler's options in `runForeground` (the core boundary, step 10:
 * docs/design/2026-10-03-harnessd.md). The reconciler itself, with what it scans, stays there.
 */
import { externalResumePending } from '../../lib/externalResume.js'
import { paneReadIdentity } from '../transcripts/readIdentity.js'
import { isTerminalEngine } from '../../engines/types.js'
import type { AutonomousDeviceInput } from '../deviceInput.js'
import type { QuestionWatcher } from '../../lib/questionController.js'
import { sameGridAssignment } from '../../lib/gridAssignmentWire.js'
import { sid } from '../../lib/log.js'
import type { registry, RegisteredSession } from '../../lib/registry.js'
import type { SessionInputController } from '../../lib/sessionInput.js'
import type { StoppedAgentStore } from '../../lib/stoppedAgents.js'
import type { DiscoveredTerminalAgent } from '../../lib/terminalAgentDiscovery.js'
import type { TerminalBackendCoordinator } from '../../lib/terminalBackendCoordinator.js'
import { primaryRuntime } from '../../lib/terminalRuntime.js'
import { bypassPermissionActive, permissionModeFromArgv } from '../../lib/processTable.js'

export interface DiscoveryDeps {
  registry: Pick<typeof registry,
    'byRuntimeEngine' | 'openProcessAgent' | 'adoptEngine' | 'updateRuntimes' | 'updateProcessIdentity' | 'setBypassPermission'
    | 'setPermissionMode' | 'setCodexHome' | 'setHermesHome' | 'setDsh' | 'byAgent' | 'setLaunch' | 'setActive'
    | 'terminalAvailable' | 'setTerminalAvailable'>
  attachDsh: (session: RegisteredSession) => void
  forgetSession: (id: string, opts?: { force?: boolean; agentId?: string }) => void
  announceSession: (session: RegisteredSession) => void
  bindObservedAgent: (observed: DiscoveredTerminalAgent) => Promise<void>
  syncRecapPool: () => void
  attachSession: (session: RegisteredSession) => Promise<boolean>
  invalidateTerminalControl: (agentId: string) => void
  input: Pick<SessionInputController, 'forget'>
  deviceInput: Pick<AutonomousDeviceInput, 'forget'>
  questionWatcher: Pick<QuestionWatcher, 'stop'>
  stopHeartbeat: (sessionId: string) => void
  retainExitedSession: (agent: RegisteredSession, announce: boolean) => void
  stoppedAgents: Pick<StoppedAgentStore, 'finishResume'>
  /** Whether restore did not get to this agent this boot (it did not run, or could not look at its row):
   *  its missing pane is then one never rebuilt, not one closed. */
  restoreDegraded: (agentId: string) => boolean
  /** The backend that holds a row's pane, asked whether an unconfirmed start's pane is still starting. */
  terminals: Pick<TerminalBackendCoordinator, 'backendFor'>
}

export function createDiscoveryHandlers({
  registry, attachDsh, forgetSession, announceSession, bindObservedAgent, syncRecapPool, attachSession,
  invalidateTerminalControl, input, deviceInput, questionWatcher, stopHeartbeat, retainExitedSession,
  stoppedAgents, restoreDegraded, terminals,
}: DiscoveryDeps) {
  const onDiscovered = async (observed: DiscoveredTerminalAgent): Promise<void> => {
    const launching = observed.runtimes
      .map((runtime) => registry.byRuntimeEngine(runtime, observed.engine))
      .find((entry) => entry?.launch?.state !== 'ready')
    const opened = registry.openProcessAgent({
      engine: observed.engine,
      runtimes: observed.runtimes,
      primaryRuntimeKey: observed.primaryRuntimeKey,
      cwd: observed.cwd,
      processIdentity: observed.processIdentity,
      gateway: observed.gateway,
      grid: observed.grid,
      codexHome: observed.codexHome,
      dsh: observed.dsh,
    })
    if (!opened) return
    if (opened.entry.dsh) attachDsh(opened.entry)
    if (opened.evicted) {
      console.log(`[discovery] ${observed.primaryRuntimeKey} replaced ${sid(opened.evicted.agentId)}`)
      // ⚠️ THE REGISTRY ALREADY DROPPED IT; NOBODY HAD TOLD THE CLIENTS. That
      // is the whole bug behind "two sessions, one of them frozen": resuming
      // an engine in a pane another agent owned takes the pane away, and an
      // agent with no pane can never be opened again — but the app kept the
      // row until someone hit Reload machines by hand, and opening it landed
      // on TERMINAL FROZEN. This is the same call the hook path already makes
      // for the same situation (see onRegistered below).
      forgetSession(opened.evicted.sessionId || opened.evicted.agentId, {
        force: true,
        agentId: opened.evicted.agentId,
      })
    }

    if (opened.isNew || launching) {
      console.log(`[discovery] ${sid(opened.entry.agentId)} opened · engine=${observed.engine} · terminal=${observed.primaryRuntimeKey}`)
      announceSession(opened.entry)
    }
    await bindObservedAgent(observed)
  }
  const onObserved = async (observed: DiscoveredTerminalAgent, current: RegisteredSession): Promise<void> => {
    if (externalResumePending(current.externalResume)) return
    const wasDormant = !current.active
    // Read BEFORE the update, because the update is what overwrites it. `undefined` means the probe
    // could not look, which never counts as a move — see `probeGridAssignment`'s three answers.
    const gridMoved = observed.grid !== undefined
      && !sameGridAssignment(current.grid ?? null, observed.grid)
    const wasLaunching = current.launch?.state !== undefined && current.launch.state !== 'ready'
    // Somebody typed an engine into a terminal. The row becomes that engine's agent — same id,
    // same pane — and from here on is handled exactly like one the app launched: bound by its
    // hooks, watched for turns, listed on the dial. `adopted` makes the announce below
    // unconditional, since the engine changing is the one fact the app must not miss.
    const adopted = isTerminalEngine(current.engine) && !isTerminalEngine(observed.engine)
      ? registry.adoptEngine(current.agentId, observed.engine, observed.processIdentity)
      : null
    if (adopted) console.log(`[discovery] ${sid(current.agentId)} terminal → ${observed.engine} · ${observed.primaryRuntimeKey}`)
    registry.updateRuntimes(current.agentId, observed.runtimes, observed.primaryRuntimeKey)
    registry.updateProcessIdentity(current.agentId, observed.processIdentity, observed.gateway, observed.grid)
    // The live argv is the truth about the bypass flag, and this is the one place every running
    // agent passes through — so a row written before the flag was persisted at all (or by a build
    // that did not yet) learns it here, before any pane recreation ever needs it.
    // `observed.engine`, not `current.engine`: for a terminal that just adopted one, the row's
    // engine was `terminal` a line ago, which has no bypass flag and would read every launch as "no".
    // Not a Swarm agent's (task #4215): its mode is the one its person chose, or none. One Harness started in full mode
    // before then still runs with that flag until it relaunches, and read back the relaunch would skip permissions again.
    const own = !current.swarmSkill
    if (own) registry.setBypassPermission(current.agentId, bypassPermissionActive(observed.engine, observed.args))
    // And the exact MODE, fill-only: a row that recorded one at create is authoritative, and one
    // that never did (adopted from a terminal, written by an older build, created by a path that
    // passes no mode) learns it from the same argv — so its restart brings back
    // `--dangerously-skip-permissions`, not the auto mode `bypassPermission` alone would pick.
    if (own && !current.permissionMode) {
      const mode = permissionModeFromArgv(observed.engine, observed.args)
      if (mode) registry.setPermissionMode(current.agentId, mode)
    }
    // Same idea for a Codex profile: a row that never learned which CODEX_HOME its process runs
    // under learns it from the process, before the hook path validates a transcript against it.
    // Fill-only — a profile the row already knows is never re-derived.
    if (observed.codexHome && !current.codexHome) registry.setCodexHome(current.agentId, observed.codexHome)
    // …and a Hermes home the same way, when the process names one. A row that learns it here never
    // has to look its session up store by store (openharness#191).
    if (observed.hermesHome && !current.hermesHome) registry.setHermesHome(current.agentId, observed.hermesHome)
    // And the DSH: a row minted by discovery (or written before the field existed) learns it from
    // the process's own `HARNESS_DSH`, and gets its viewer and verdict watch from here on.
    if (observed.dsh && !current.dsh) registry.setDsh(current.agentId, observed.dsh)
    const withDsh = registry.byAgent(current.agentId)
    if (withDsh?.dsh) attachDsh(withDsh)
    // This live process, in this row's own pane, is what "started" means — for a resumed row as
    // much as any other. A resume used to be held back here until its `SessionStart` hook landed,
    // on the grounds that only the hook proves WHICH conversation reopened. Two things were wrong
    // with that. The hook does not always come: measured on machine-remote-1, both resume-only
    // codex rows carried `lastHookAt: 0` while every fresh launch beside them had hooked, and one
    // of them sat at "Starting" for 19 hours over a pane its owner could type in — re-attached and
    // re-announced every 5s for the whole time, because `wasLaunching` stays true for a row that
    // nothing will ever mark ready (openharness#189). And nothing was actually protected by the
    // wait: the wrong-conversation guard in `registry.register` keys on `lastHookAt`, not on this
    // launch state, so it stays armed until the first hook whatever is written here.
    if (wasLaunching) registry.setLaunch(current.agentId, { state: 'ready' })
    await bindObservedAgent(observed)
    if (wasDormant || wasLaunching || adopted) {
      const active = registry.byAgent(current.agentId)
      if (!active) return
      if (!active.sessionId || active.identityHold) {
        syncRecapPool()
        announceSession(active)
        return
      }
      // Not awaited: the attach reads this agent's whole history, and this callback runs inside the
      // reconcile pass whose completion is what publishes `discoveryReady`. One agent's slow store
      // must not hold the pass — or, at boot, the app. The tracker runs a few of these at a time.
      const authority = paneReadIdentity(active)
      void attachSession(active).then((attached) => {
        const latest = registry.byAgent(active.agentId)
        if (paneReadIdentity(latest) !== authority || latest?.identityHold) return
        if (!attached) {
          registry.setActive(active.agentId, false)
          return
        }
        syncRecapPool()
        announceSession(active)
      }).catch((err) => {
        console.error(`[discovery] ${sid(active.agentId)} attach failed:`, err instanceof Error ? err.message : err)
      })
      return
    }
    // An agent that was already awake changed grid under us. Nobody was told: this branch wrote the
    // new assignment into the registry and stopped, so the app went on drawing the old one until
    // its own 60s reconciliation tick happened to notice — a minute of an agent's header naming a
    // grid it had left. The retarget path has always announced (it is the same fact, arriving by a
    // different door); this is the door an engine's own `exec` comes through, which is what an
    // install-then-launch does the moment the install finishes.
    if (!gridMoved) return
    const refreshed = registry.byAgent(current.agentId)
    if (refreshed) announceSession(refreshed)
  }
  const onDormant = async (agent: RegisteredSession, reason: string): Promise<void> => {
    if (!agent.active || agent.launch?.state === 'held') return
    invalidateTerminalControl(agent.agentId)
    input.forget(agent.agentId)
    deviceInput.forget(agent.agentId)
    if (agent.sessionId) {
      questionWatcher.stop(agent.sessionId)
      stopHeartbeat(agent.sessionId)
    }
    // Preserve the conversation's public identity and give the surviving shell its own row.
    // A starting install is not an exited engine; strict uncertain starts keep their reservation.
    if (agent.resumeOnly && agent.launch?.state === 'failed') {
      const runtime = primaryRuntime(agent)
      // No backend to ask is a pane nobody could read: it stays, like one tmux could not answer for.
      const pane = await terminals.backendFor(runtime)?.paneState(runtime) ?? 'unknown'
      // An unconfirmed install/startup can still be about to launch the engine. Do not
      // turn its live shell into permission to start another one. A pane that is gone is the
      // reconciler's to remove, and one tmux could not read says nothing: both stay as they are.
      if (typeof pane === 'string' || (!pane.dead && pane.engineExit == null)) return
    }
    if (agent.launch?.state !== 'starting') {
      retainExitedSession(agent, true)
      if (agent.resumeOnly) stoppedAgents.finishResume(agent.agentId)
      console.log(`[discovery] ${sid(agent.agentId)} retained · ${reason}`)
      return
    }
    registry.setActive(agent.agentId, false)
    console.log(`[discovery] ${sid(agent.agentId)} dormant · ${reason}`)
    announceSession(agent)
  }
  const onRemoved = (agent: RegisteredSession, reason: string): void => {
    // A missing waiting shell does not end the conversation held for preparation/recovery.
    if (agent.launch?.state === 'held') {
      registry.setActive(agent.agentId, false)
      announceSession(agent)
      return
    }
    // A pane absent because RESTORE never ran is not a pane the person closed. Retiring it here
    // would archive a row whose tmux pane was simply never rebuilt, and the person would have to
    // Open each one by hand; keeping it dormant leaves the next daemon — the fixed one — something
    // to restore.
    if (restoreDegraded(agent.agentId)) {
      console.log(`[discovery] ${sid(agent.agentId)} kept · restore did not run this boot · ${reason}`)
      registry.setActive(agent.agentId, false)
      announceSession(agent)
      return
    }
    console.log(`[discovery] ${sid(agent.agentId)} removed · ${reason}`)
    forgetSession(agent.agentId, { force: true })
  }
  const onTerminalAvailability = (agent: RegisteredSession, available: boolean): void => {
    const changed = registry.terminalAvailable(agent.agentId) !== available
    registry.setTerminalAvailable(agent.agentId, available)
    // A shell has no engine process to observe, so nothing else reactivates it after the core's start marked every row
    // dormant: its pane being live (on whichever pty host serves it) is all the evidence there is. Held and failed
    // launches are inactive on purpose.
    const revive = available && isTerminalEngine(agent.engine) && !agent.active
      && agent.launch?.state !== 'held' && agent.launch?.state !== 'failed'
    if (revive) registry.setActive(agent.agentId, true)
    if (available && (changed || revive)) announceSession(agent)
  }
  return { onDiscovered, onObserved, onDormant, onRemoved, onTerminalAvailability }
}