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.

17.8 KB
Raw Blame
/**
 * The engines' own hooks: which registered agent a hook belongs to, what a SessionEnd means, and
 * installing every engine's hooks so they call this daemon.
 *
 * Moved verbatim out of `runForeground` (the core boundary, step 12: docs/design/2026-10-03-harnessd.md).
 */
import { engineHooks } from '../../engines/hooks.js'
import { sessionStoreContracts } from '../../engines/sessionStoreContracts.js'
import { chooseHookAgent, type HookServerHandlers } from '../../hookServer.js'
import { confirmHomes, recoverEngineHomes } from '../../lib/engineHomes.js'
import { createHomeAdoptions } from './homeAdoptions.js'
import * as nativeHooks from '../../engines/nativeHooks.js'
import type { NativeHookOptions } from '../../engines/kit/nativeLocations.js'
import type { OpencodeLaunchSnapshot } from '../../engines/launchControl.js'
import { sid } from '../../lib/log.js'
import type { registry, RegisteredSession } from '../../lib/registry.js'
import { validTerminalRuntime } from '../../lib/registry.js'
import { processRows } from '../../lib/terminalAgentDiscovery.js'
import type { ProcessRow } from '../../lib/processTable.js'
import { sameProcessIdentity } from '../../lib/terminalRuntime.js'
import type { TerminalAgentReconciler } from '../../lib/terminalAgentReconciler.js'
import type { TerminalRuntimeRef } from '../../lib/terminalTypes.js'

type ResolveHookAgent = NonNullable<HookServerHandlers['resolveHookAgent']>

export interface EngineHookDeps {
  /** Only the core's short pane dispatch/commit, never service preparation or an engine watch. */
  panePending?: (agentId: string) => Promise<unknown> | undefined
  /** A tmux hint names a tmux pane; without tmux there is nothing it can point at. */
  tmuxBackend: unknown
  /** A ptyhost hint names a pane of the Harness PTY host; without that backend there is nothing it can point at. */
  ptyHostBackend?: unknown
  agentReconciler: Pick<TerminalAgentReconciler, 'triggerHint' | 'trigger'>
  registry: Pick<typeof registry, 'byRuntimeEngine' | 'byAgent'>
  syncSession: (row: RegisteredSession) => void
}

/**
 * The longest a hook waits for the agent on its pane to record the process it came from. Every relaunch
 * starts its engine before it records it: a resume looks for the process every 250ms, a create or a
 * fork backs off to 750ms, and a restart finds it the same way and then probes it, twice over when it
 * falls back to a new conversation (two 8s discovery budgets, swap.ts). The hook itself is answered
 * before the wait (`onWait`): its client gives up on a reply after 500ms and then writes the registry
 * itself (hook/notify.mjs), so only the daemon's record waits.
 */
export const PROCESS_RECORD_WAIT_MS = 20_000
/** How often a waiting hook reads the rows on its panes again: memory, not a process table. */
const PROCESS_RECORD_POLL_MS = 100

type HookQuery = Parameters<ResolveHookAgent>[0]

/** Which agent holds a pane, and the process it has recorded: what a waiting hook watches change. */
const recordKey = (session: RegisteredSession | undefined): string =>
  session ? `${session.agentId}\u0000${session.processIdentity?.pid ?? ''}\u0000${session.processIdentity?.startMarker ?? ''}` : ''

export function createEngineHooks(deps: EngineHookDeps) {
  const { ptyHostBackend, agentReconciler, registry, panePending, syncSession } = deps
  /**
   * The agents on the hinted panes: those whose recorded process the caller descends from, the rest,
   * and of the rest those with no live process recorded at all (none yet, or one that has exited).
   * `ancestry` is the hook's own process and those it descends from, read as the hook arrived
   * (`resolveHookAgent`); `table`, the process table to judge the recorded processes by, else a new read.
   */
  const matchCaller = async (resolved: TerminalRuntimeRef[], engine: HookQuery['engine'], ancestry: ReadonlyMap<number, ProcessRow>, table?: ProcessRow[]) => {
    const rows = table ?? await processRows()
    if (!rows) return null
    const recordedAlive = (session: RegisteredSession): boolean => {
      const recorded = session.processIdentity
      return !!recorded && rows.some((row) => sameProcessIdentity(row, recorded))
    }
    const callerBelongsTo = (session: RegisteredSession): boolean => {
      const expectedPid = session.processIdentity?.pid
      const original = expectedPid && ancestry.get(expectedPid)
      return !!original && sameProcessIdentity(original, session.processIdentity)
    }
    const candidates = new Map<string, RegisteredSession>()
    /**
     * Agents the hint points at whose ancestry we could NOT confirm.
     *
     * Caller ancestry is the strongest evidence and stays the first choice, but it assumes every engine
     * spawns its hook from inside its own process tree — and Cursor does not. Measured on both
     * backends: `agent` in a pane registers fine, then every one of its hooks is rejected because the
     * process that POSTs is not a descendant of the pane's engine, so no session ever binds.
     *
     * Keep that exception specific to Cursor. A delayed hook from an exited process can still name
     * a pane now owned by its replacement; the pane and hook credential alone cannot prove that a
     * Codex (or other engine's) old transcript belongs to the new process.
     */
    const onHintedRuntime = new Map<string, RegisteredSession>()
    const unrecorded: RegisteredSession[] = []
    for (const runtime of resolved) {
      const live = registry.byRuntimeEngine(runtime, engine)
      if (!live) continue
      // The caller resumes after this async function returns. Capture at the
      // ancestry check, before that continuation can observe a replacement row.
      const candidate = structuredClone(live)
      if (callerBelongsTo(candidate)) candidates.set(candidate.agentId, candidate)
      else {
        onHintedRuntime.set(candidate.agentId, candidate)
        // A reused PID is positive evidence of another process, not an unrecorded launch.
        if (!recordedAlive(candidate) && !ancestry.has(candidate.processIdentity?.pid ?? 0)) unrecorded.push(candidate)
      }
    }
    return { candidates, onHintedRuntime, unrecorded }
  }

  /** Resolves when the row on any of these panes records another process (or another agent takes the
   *  pane), or when the wait is over. */
  const recordChanged = async (resolved: TerminalRuntimeRef[], engine: HookQuery['engine']): Promise<void> => {
    const before = resolved.map((runtime) => recordKey(registry.byRuntimeEngine(runtime, engine)))
    // On the monotonic clock: a wall clock stepped forward (a wake, an NTP correction: round 29) ended
    // the wait at its next poll and dropped the hook, and one stepped back kept it polling for the step.
    const deadline = performance.now() + PROCESS_RECORD_WAIT_MS
    while (performance.now() < deadline) {
      await new Promise((resolve) => setTimeout(resolve, PROCESS_RECORD_POLL_MS))
      if (resolved.some((runtime, i) => recordKey(registry.byRuntimeEngine(runtime, engine)) !== before[i])) return
    }
  }

  const resolveHookAgent: ResolveHookAgent = async ({ engine, runtimeHints, callerPid, onWait }) => {
    if (!callerPid) return null
    // Who the hook came from, read as it arrives. On Linux dash keeps its `sh -c` as the hook's parent, a
    // shell that exits with the hook (its 500ms, or `onWait`'s answer); read after the reconcile pass or
    // the wait, the ancestry stopped at a pid already gone and a restart's new conversation was never
    // bound (e2e/updates.e2e.ts). macOS's /bin/sh is a bash that execs the hook: never seen there.
    const arrival = processRows().then(rows => rows?.map(row => ({ ...row })) ?? null)
    const resolved: TerminalRuntimeRef[] = []
    for (const hint of runtimeHints ?? []) {
      if (hint.backend === 'tmux') { if (deps.tmuxBackend) resolved.push({ backend: 'tmux', paneId: hint.paneId }) }
      else {
        // Held to the registry's own rule for a ptyhost runtime (`p<n>` instance, `%<n>` pane): a hint that is
        // not one is ignored, as a hint for a backend that is not configured is.
        const runtime = { backend: 'ptyhost' as const, instance: hint.instance, paneId: hint.paneId }
        if (ptyHostBackend && validTerminalRuntime(runtime)) resolved.push(runtime)
      }
    }
    // A pass that outran its deadline has not yet opened the agent a hook from a new engine belongs to.
    let overdue = false
    for (const runtime of resolved) if (!await agentReconciler.triggerHint(runtime, engine)) overdue = true

    let table = await arrival
    // A `ps` already running (processRows shares it) may predate the hook's process; the next read has it.
    if (table && !table.some((row) => row.pid === callerPid)) table = await processRows()
    if (!table) return null
    const parents = new Map(table.map(row => [row.pid, row]))
    const ancestry = new Map<number, ProcessRow>()
    for (let pid = callerPid; pid > 0 && !ancestry.has(pid);) {
      const row = parents.get(pid)
      if (!row) break
      ancestry.set(pid, { ...row })
      pid = row.parentPid
    }

    let found = (await matchCaller(resolved, engine, ancestry, table))!
    let choice = chooseHookAgent([...found.candidates.values()], [...found.onHintedRuntime.values()], engine)
    // Every relaunch starts its engine before it records the new process — create, fork, resume, a
    // restart and the new conversation it falls back to, a retarget — so a SessionStart in between came
    // from a pid no agent had yet, and was dropped. A resumed Codex agent then never showed its turns
    // (round 23), and a restart's new conversation was never bound (round 24). While the agent on the
    // hook's pane has no live process recorded, the hook now waits for it to record one, and is matched
    // again against that: one rule for every relaunch, with nothing for any of them to remember to do.
    // So does one that came while discovery was too slow to open its agent: the agent appearing on the
    // pane is a change of its record too.
    if (!choice.agent && choice.reason === 'none' && (found.unrecorded.length || overdue)) {
      onWait?.()
      await recordChanged(resolved, engine)
      const again = await matchCaller(resolved, engine, ancestry)
      if (!again) return null
      found = again
      choice = chooseHookAgent([...found.candidates.values()], [...found.onHintedRuntime.values()], engine)
    }
    // Cursor may admit a unique runtime without recorded ancestry. A hook from the engine just
    // dispatched there must not rewrite its row before that pane operation has committed its route.
    // Acknowledge now so the hook client never falls back to writing the registry itself.
    for (;;) {
      const pending = choice.agent && panePending?.(choice.agent.agentId)
      if (!pending) break
      onWait?.()
      try { await pending } catch { return null }
      const again = await matchCaller(resolved, engine, ancestry)
      if (!again) return null
      found = again
      choice = chooseHookAgent([...found.candidates.values()], [...found.onHintedRuntime.values()], engine)
    }
    const { candidates } = found
    if (choice.agent) {
      if (choice.reason === 'runtime') {
        console.log(`[hooks] ${engine} hook accepted on runtime evidence alone`
          + ` · agent=${sid(choice.agent.agentId)} · caller=${callerPid} is outside that engine's process tree`)
      }
      return choice.agent
    }
    // Say WHY, once per rejected hook. "no_matching_engine_process" alone sent two people down the
    // wrong path already: the interesting question is never "did it match" but which of the three
    // gates closed — no runtime resolved from the hint, no registered agent on that runtime, or the
    // hook's own process is not a descendant of the engine we registered.
    const onRuntime = resolved.map((runtime) => registry.byRuntimeEngine(runtime, engine)).filter(Boolean)
    console.log(`[hooks] unmatched ${engine} hook · hints=${(runtimeHints ?? []).map((hint) => `${hint.backend}:${hint.paneId}`).join(',') || 'none'}`
      + ` · resolvedRuntimes=${resolved.length} · agentsOnRuntime=${onRuntime.length}`
      + ` · callerPid=${callerPid}${onRuntime.length && !candidates.size ? ' · caller is not a descendant of that engine process' : ''}`
      + `${candidates.size > 1 ? ` · ambiguous (${candidates.size} candidates)` : ''}`)
    return null
  }

  // SessionEnd describes the mutable engine session, never process lifetime. Reconcile now; discovery
  // decides whether the agent still exists from terminal inventory + ps.
  const onSessionEnd = (_sessionId: string, _reason: string | undefined): void => {
    void agentReconciler.trigger()
  }
  const onAdmissionHeld = (id: string, reason: string | undefined): void => {
    const row = registry.byAgent(id)
    if (!row) return
    if (reason) row.admissionHold = reason
    else delete row.admissionHold
    syncSession(row)
  }
  return { resolveHookAgent, onSessionEnd, onAdmissionHeld }
}

/**
 * OpenCode's plugin, installed again before an OpenCode spawn (core/agents/create.ts): OpenCode may have moved
 * from 1.x to 2.x under a running daemon, and its new TUI must not find the old server plugin. Installation
 * never depends on loading its optional interpreter.
 */
export async function installOpencodePluginBeforeSpawn(port: number, snapshot?: OpencodeLaunchSnapshot): Promise<boolean> {
  return await (snapshot ? nativeHooks.installOpencodePlugin(port, snapshot) : nativeHooks.installOpencodePlugin(port)) !== false
}

export interface InstallEngineHooksOptions {
  /** Only these engines' hooks (`HOOK_INSTALL_ENGINES`); every engine's when absent. */
  only?: ReadonlySet<string> | null
  /** The daemon's own environment, for the homes it moves; `process.env` when absent. */
  environment?: NodeJS.ProcessEnv
  /** The login shell's environment, when it has been read (`warmLoginShellEnvironment`). */
  loginShell?: Promise<NodeJS.ProcessEnv>
}

/**
 * The other engines' declarations are installed in their original order, without an optional import.
 */
const OTHER_INSTALLERS: Array<[string, (port: number, options: NativeHookOptions) => void | boolean | Promise<unknown>]> = [
  ['cursor', nativeHooks.installCursorHooks],
  ['opencode', (port, options) => nativeHooks.installOpencodePlugin(port, undefined, options)],
  ['kilo', nativeHooks.installKiloPlugin],
  ['pi', nativeHooks.installPiExtension],
  // A self-update refreshes plugin files here; running engine processes pick them up according to each
  // vendor's own plugin reload lifecycle.
  ['amp', nativeHooks.installAmpPlugin],
  ['hermes', (port, options) => nativeHooks.installHermesHooks(port, undefined, options)],
  ['devin', nativeHooks.installDevinHooks],
  ['commandcode', nativeHooks.installCommandCodeHooks],
  ['grok', nativeHooks.installGrokHooks],
  ['agy', nativeHooks.installAgyHooks],
  ['copilot', nativeHooks.installCopilotHooks],
]

/**
 * Install every engine's hooks with the port the local server actually bound.
 *
 * One vendor at a time, each behind its own guard: these write into thirteen different settings
 * files owned by thirteen different CLIs, and one that is malformed, read-only or mid-write is not
 * a reason for the other twelve to go uninstalled — let alone for the daemon not to come up.
 *
 * Core starts this after readiness. Every launch separately confirms the hooks it
 * needs; an unrelated vendor's disk or version probe cannot delay control. The
 * controller is returned immediately so shutdown can revoke every pending write.
 * `settled` observes this initial pass, never readiness. It does not reject.
 */
export function installEngineHooks(port: number, options: InstallEngineHooksOptions = {}): { close(): void; settled: Promise<void> } {
  const pending: Promise<void>[] = []
  const hookStep = (vendor: string, install: () => void | boolean | Promise<unknown>): void => {
    if (options.only && !options.only.has(vendor)) return
    const failed = (error: unknown) => {
      console.warn(`[hooks] ${vendor} install skipped · ${error instanceof Error ? error.message : error}`)
    }
    try {
      const result = install()
      if (result === false) failed('native hook preparation is unavailable')
      else if (result && typeof result !== 'boolean') pending.push(result.then(answer => {
        if (answer === false) failed('native hook preparation is unavailable')
      }, failed))
    } catch (error) { failed(error) }
  }
  // The homes the person moved (lib/engineHomes.ts, by each engine's declared session store) get the hooks
  // too: every one adopted before, those the daemon's own environment names, and those of the login shell
  // every engine is launched through once it has been read. That read is never waited on (cli.ts), so an
  // engine started in the first seconds of a daemon's very first start with a moved home may miss its first hook.
  const adoptions = createHomeAdoptions({
    read: recoverEngineHomes,
    confirm: confirmHomes,
    install: async (engine, home) => {
      if (options.only && !options.only.has(engine)) return
      if (!await engineHooks[engine].installIn(port, home, { current: adoptions.current })) throw new Error(`${sessionStoreContracts[engine].product} hook preparation is unavailable`)
      console.log(`[hooks] ${sessionStoreContracts[engine].product} hooks installed in its adopted home`)
    },
    held: reason => {
      if (reason) console.warn(`[hooks] home adoption held · ${reason}`)
      else console.log('[hooks] home adoption recovered')
    },
  })
  adoptions.submit(options.environment ?? process.env)
  void options.loginShell?.then(adoptions.submit, error => console.warn(`[hooks] login-shell homes unavailable · ${error instanceof Error ? error.message : error}`))
  const nativeOptions = { current: adoptions.current }
  for (const [engine, hooks] of Object.entries(engineHooks)) hookStep(engine, () => hooks.install(port, nativeOptions))
  for (const [vendor, install] of OTHER_INSTALLERS) hookStep(vendor, () => install(port, nativeOptions))
  return { close: adoptions.close, settled: Promise.all(pending).then(() => {}) }
}