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.

13.0 KB
Raw Blame
/**
 * Stop an agent's live engine process and relaunch it in the SAME tmux pane, preserving the pane/agent
 * identity and (best-effort) resuming the same engine conversation.
 *
 * Factored out of cli.ts's `onRestartAgent` the same way deleteAgentFallback.ts factors out delete's
 * kill sequence: a small, dependency-injected core so the kill → respawn → verify → fallback ordering
 * can be exercised without the daemon's registry, tmux, and reconciler wiring. cli.ts owns everything
 * registry-shaped around a call to this function — resolving the session, `agentReconciler.holdRoute` /
 * `releaseRoute`, `registry.updateProcessIdentity`, `clearPaneRemainOnExit`, and `announceSession`.
 */

import type { AgentEngine } from '../engines/types.js'
import type { RegisteredSession, ProcessIdentity } from './registry.js'
import type { TerminateOutcome } from './deleteAgentFallback.js'
import { permissionModeApproves } from './engineLaunch.js'

/**
 * Whether the relaunch approves on its own — from the ROW first, and the live process only for a row
 * that never learned.
 *
 * The row is what create wrote and what discovery keeps in step with the live argv, so it is the
 * answer even once the process is dead or `ps` has failed. Reading the live argv instead was the
 * original design (there was nothing else to read then), and it is what lost the flag: a `ps` that
 * timed out read as "no", and an agent typed into a terminal with the skip-everything flag came back
 * in the auto mode. The mode outranks the boolean — Plan is not a yes — and `buildArgv` reapplies the
 * mode itself; this only settles the yes/no the engines without a mode table launch with.
 */
export async function bypassPermissionFor(
  session: Pick<RegisteredSession, 'permissionMode' | 'bypassPermission' | 'swarmSkill'>,
  probeLive: () => Promise<boolean>,
): Promise<boolean> {
  if (session.permissionMode) return permissionModeApproves(session.permissionMode)
  if (session.bypassPermission !== undefined) return session.bypassPermission
  // A Swarm agent's mode is its person's choice, or none (task #4215). One Harness started in full mode, cleared since,
  // still runs with that flag until it relaunches: read back, it would come back in Auto, which nobody chose.
  if (session.swarmSkill) return false
  return probeLive()
}

export type RestartOutcome =
  | { ok: true; processIdentity: ProcessIdentity; resumed: boolean }
  | { ok: false; detail: string; error?: 'ENGINE_LAUNCH_REFUSED' }

export type RestartAgentReply =
  | { ok: true; session: RegisteredSession; resumed: boolean }
  | { ok: false; error: string; detail?: string }

/** One process replacement per agent, even across clients and different receipt
 * IDs. Stop cancels the work before its next process-changing step. */
export class AgentRestartCoordinator {
  private readonly revisions = new Map<string, number>()
  private sequence = 0
  revision(agentId: string): number {
    let revision = this.revisions.get(agentId)
    if (revision === undefined) { revision = ++this.sequence; this.revisions.set(agentId, revision) }
    return revision
  }
  forget(agentId: string): void { this.revisions.delete(agentId) }
  operation(agentId: string): string | undefined { return this.jobs.get(agentId)?.operation }
  private readonly jobs = new Map<string, { operation: string; variant: string; cancelled: boolean; result: Promise<RestartAgentReply> }>()

  /** [variant] tells apart two asks of the same operation that must not share one launch: the launch words a restart
   *  was given. Only the same variant joins a running one; any other is refused, never answered by a launch that did
   *  not carry its words. */
  run(agentId: string, restart: (current: () => boolean) => Promise<RestartAgentReply>, operation = 'restart', variant = ''): Promise<RestartAgentReply> {
    const existing = this.jobs.get(agentId)
    if (existing) return existing.operation === operation && existing.variant === variant ? existing.result
      : Promise.resolve({ ok: false, error: 'AGENT_BUSY', detail: 'Another lifecycle operation is changing this harness.' })
    if (this.revisions.has(agentId)) this.revisions.set(agentId, ++this.sequence)
    const job = { operation, variant, cancelled: false, result: null! as Promise<RestartAgentReply> }
    const current = () => !job.cancelled && this.jobs.get(agentId) === job
    job.result = Promise.resolve().then(async () => {
      if (!current()) return { ok: false, error: 'AGENT_CHANGED' } as const
      const result = await restart(current)
      return current() ? result : { ok: false, error: 'AGENT_CHANGED' } as const
    }).finally(() => {
      if (this.jobs.get(agentId) === job) this.jobs.delete(agentId)
    })
    this.jobs.set(agentId, job)
    return job.result
  }

  busy(agentId: string): boolean { return this.jobs.has(agentId) }

  cancel(agentId: string): void {
    if (this.revisions.has(agentId)) this.revisions.set(agentId, ++this.sequence)
    const job = this.jobs.get(agentId)
    if (job) job.cancelled = true
  }
}

/** How the relaunch reopens the conversation: resumed, continued in a fork of it, or neither (a fresh one). */
export interface RelaunchArgvOptions { bypassPermission: boolean; resumeSessionId?: string; forkSessionId?: string }

export interface RestartAgentDeps {
  /** False after Stop, replacement, or removal. Checked across every await. */
  isCurrent?: () => boolean
  /** Re-arm `remain-on-exit` before anything is killed — see `tmuxBackend.ts`'s `holdOpen` (the pty host's
   *  `holdOpen` is the same keep). Without this, tmux tears the pane (and, being its only pane, the whole
   *  session) down the instant the old process exits. */
  holdOpen: () => Promise<{ ok: boolean; reason?: string }>
  /** Validate + SIGTERM/SIGKILL the saved process. Same contract as `terminateDeletedAgent`. */
  terminate: (checkAfterMs?: number) => Promise<TerminateOutcome>
  /** `tmux respawn-pane -k` (or the pty host's `respawn`, the same in place) with a fully-built argv. */
  respawn: (argv: string[]) => Promise<{ ok: boolean; reason?: string }>
  /** Why `respawn` would be refused here (a tmux too old for what the relaunch needs), asked before
   *  anything is stopped; null when it would try. Left out, never refused. */
  respawnRefusal?: () => Promise<string | null>
  /** Poll the pane for a recognizable engine process, up to an internal budget. Null on timeout. */
  waitForProcess: () => Promise<ProcessIdentity | null>
  /** Prepare persisted history only once the old writer is confirmed stopped. A failure must
   * preserve the conversation, not enter the fresh-session fallback. */
  prepareResume?: () => void | Promise<void>
  /**
   * Claude only: stop a `claude --bg` job still holding the session this is about to `--resume`
   * (`lib/claudeBackgroundJob.ts`). Run once, after history preparation and before the resume
   * argv is built, so a job that held the jobs store's lock is gone before Claude Code is asked to
   * reopen it. A failure here must not block the restart it exists to unblock, so it is awaited for
   * ordering only, never allowed to fail the restart; implementations swallow their own errors.
   */
  stopConflictingJob?: () => Promise<void>
  /** A [continueInFork] move, once the old writer is stopped: makes the fork ready for its destination and returns its
   *  id, which the relaunch then resumes. A failure falls back to the plain fork: the conversation still continues. */
  prepareFork?: () => Promise<string>
  buildArgv: (opts: RelaunchArgvOptions) => string[]
  /** Why the relaunch [buildArgv] would build is refused on this platform (a Windows batch-file engine whose arguments
   *  cmd.exe would read, lib/windows/launch.ts), asked before anything is stopped; null when it is not. */
  launchRefusal?: (opts: RelaunchArgvOptions) => string | null
  log: (message: string) => void
  /** Keeps the conversation the fresh fallback left as a stopped harness (keepAbandonedConversation.ts). */
  keepAbandoned?: () => void
}

/** Outcomes that mean the old process is confirmed gone — safe to respawn over the pane (or, for a move, to start
 *  the engine in another one: hostMove/moveAgent.ts). `not-ours` and `failed` are NOT here on purpose: never
 *  respawn over a target the kill sequence could not confirm. */
export const KILL_CONFIRMED: ReadonlySet<TerminateOutcome> = new Set(['gone', 'terminated', 'killed'])

/**
 * [session.continueInFork]: the conversation goes on in a fork of it (`codex fork <id>`) instead of being resumed — the
 * relaunch moves it to a provider it cannot be resumed on (`EngineLaunch.providerBoundConversations`). The fork is the
 * whole conversation, so nothing is kept for the one it came from; the agent follows the fork's id when it binds
 * (bind.ts, as a rebound).
 */
export async function restartAgent(
  session: { engine: AgentEngine; sessionId: string; resumeOnly?: true; continueInFork?: true },
  bypassPermission: boolean,
  deps: RestartAgentDeps,
): Promise<RestartOutcome> {
  const changed = { ok: false, detail: 'the harness changed or stopped during restart' } as const
  const current = () => deps.isCurrent?.() !== false
  if (!current()) return changed
  // Before anything is stopped: refused after the kill, the agent was left with no engine at all.
  const refused = await deps.respawnRefusal?.()
  if (refused) return { ok: false, detail: `${refused} Nothing was stopped.` }
  const reopen = (id: string | undefined) => !id ? {} : session.continueInFork ? { forkSessionId: id } : { resumeSessionId: id }
  // The resume relaunch has every argument the fresh fallback has, and more: refused, neither would start.
  const launchRefused = deps.launchRefusal?.({ bypassPermission, ...reopen(session.sessionId) })
  if (launchRefused) return { ok: false, error: 'ENGINE_LAUNCH_REFUSED', detail: `${launchRefused} Nothing was stopped.` }
  if (!current()) return changed
  const armed = await deps.holdOpen()
  if (!current()) return changed
  if (!armed.ok) {
    return { ok: false, detail: armed.reason ?? 'could not re-arm the pane before restart' }
  }

  let outcome: TerminateOutcome
  try { outcome = await deps.terminate() }
  catch (error) {
    return { ok: false, detail: `could not stop the running ${session.engine} session: ${error instanceof Error ? error.message : error}` }
  }
  if (!current()) return changed
  if (!KILL_CONFIRMED.has(outcome)) {
    return { ok: false, detail: `could not confirm the running ${session.engine} process was stopped (${outcome})` }
  }

  const resumeSessionId = session.sessionId || undefined
  if (resumeSessionId && deps.prepareResume) {
    try { await deps.prepareResume() } catch (error) {
      return { ok: false, detail: `could not prepare ${session.engine} session for resume: ${error instanceof Error ? error.message : error}` }
    }
  }
  if (!current()) return changed
  if (resumeSessionId && deps.stopConflictingJob) await deps.stopConflictingJob()
  if (!current()) return changed
  let preparedFork: string | null = null
  if (resumeSessionId && session.continueInFork && deps.prepareFork) {
    try { preparedFork = await deps.prepareFork() } catch (error) {
      deps.log(`[restart] ${session.engine} could not prepare the move, continuing in a plain fork: ${error instanceof Error ? error.message : error}`)
    }
    if (!current()) return changed
  }
  const spawnAndWait = async (withResume: boolean): Promise<ProcessIdentity | null> => {
    if (!current()) return null
    const argv = deps.buildArgv({ bypassPermission, ...(!withResume ? {} : preparedFork ? { resumeSessionId: preparedFork } : reopen(resumeSessionId)) })
    const spawned = await deps.respawn(argv)
    if (!current()) return null
    if (!spawned.ok) {
      deps.log(`[restart] ${session.engine} respawn-pane failed: ${spawned.reason ?? 'unknown reason'}`)
      return null
    }
    return deps.waitForProcess()
  }

  // Attempt a resume relaunch whenever we have a session id to resume, for every engine — an
  // unconfirmed/wrong flag is not fatal because of the fallback below. Engines with no known launch
  // resume flag never spawn a resume argv in the first place (buildArgv's `resumeSessionId` is a no-op
  // when LAUNCH_RESUME_FLAG has no entry for the engine), so `resumed` still degrades correctly.
  let resumed = !!resumeSessionId
  let identity = await spawnAndWait(resumed)
  if (!current()) return changed
  if (!identity && resumed && !session.resumeOnly) {
    // Safe degradation: a working agent with a FRESH session under the same agentId/pane beats a dead
    // pane. Retry once with no resume attempt before giving up entirely.
    deps.log(`[restart] ${session.engine} did not come back up resuming its session — retrying fresh`)
    resumed = false
    identity = await spawnAndWait(false)
  }
  if (!current()) return changed
  if (!identity) {
    return { ok: false, detail: `${session.engine} did not come back up after restart` }
  }
  // The agent works on in a new conversation; the one it was in, which the engine could not reopen, is
  // kept as a stopped harness to read and to resume once it can (round 24). A /clear keeps nothing.
  if (resumeSessionId && !resumed) deps.keepAbandoned?.()
  return { ok: true, processIdentity: identity, resumed }
}