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.

7.3 KB
Raw Blame
/**
 * Forgetting a session: release a mutable session binding (the agent stays, its session goes), or
 * remove a process-owned agent everywhere — archived as stopped, and every per-session store the core
 * keeps let go of, so a daemon that runs for days does not grow with every session it ever saw.
 *
 * Moved verbatim out of `runForeground` (the core boundary, step 10: docs/design/2026-10-03-harnessd.md).
 */
import { removePendingCursorTasks } from '../engines/cursorTasks.js'
import type { CursorTranscriptDiscovery } from '../../engines/cursor/discovery.js'
import type { CursorSubagentManager } from '../../engines/cursor/subagent.js'
import type { AutonomousDeviceInput } from '../deviceInput.js'
import type { TurnRecaps } from '../turns/recaps.js'
import type { ShortTurnGuard } from '../turns/shortTurnGuard.js'
import { sid } from '../../lib/log.js'
import { sameProcessIdentity } from '../../lib/terminalRuntime.js'
import type { RegisteredSession, registry } from '../../lib/registry.js'
import type { RuntimeProfileManager } from '../../lib/runtimeProfile.js'
import type { SessionInputController } from '../../lib/sessionInput.js'
import type { StoppedAgentStore } from '../../lib/stoppedAgents.js'
import type { Watcher } from '../../watcher/watcher.js'
import type { SessionNormalizers } from '../transcripts/normalizers.js'
import type { RelaunchMarks } from '../transcripts/relaunch.js'
import type { ConversationOwners } from './conversationOwners.js'

type Frame = { type: string; payload: Record<string, unknown> }

export interface ForgetDeps {
  onRemoved?: (agentId: string) => void
  /** One owner per conversation, stopped harnesses included (conversationOwners.ts). */
  owners?: Pick<ConversationOwners, 'settleSaved'>
  registry: Pick<typeof registry, 'resolve' | 'unbindSession' | 'removeAgent' | 'remove'>
  stoppedAgents: Pick<StoppedAgentStore, 'save'>
  syncRecapPool: () => void
  normalizers: Pick<SessionNormalizers, 'forget'>
  forgetAttach: (sessionId: string) => void
  turnStartedAt: Map<string, number>
  /** The short-turn guard's count and hold for each session (turns/shortTurnGuard.ts): gone with the session. */
  shortTurns?: Pick<ShortTurnGuard, 'forget'>
  /** Each agent's kept prompt (turns/funnel.ts), by agent: gone with the agent. */
  prompts: Map<string, string>
  /** Attach's two per-session marks (core/transcripts/attach.ts). */
  neverFoldedHistory: Set<string>
  replayedFirstTurn: Set<string>
  relaunchMarks?: Pick<RelaunchMarks, 'forget'>
  clearAgyIdleWatch: (sessionId: string) => void
  cursorDiscovery: Pick<CursorTranscriptDiscovery, 'remove'>
  cursorSubagents: Pick<CursorSubagentManager, 'forget'>
  runtimeProfiles: Pick<RuntimeProfileManager, 'forget'>
  watcher: Pick<Watcher, 'removeSession'>
  stopHeartbeat: (sessionId: string) => void
  input: Pick<SessionInputController, 'forget'>
  deviceInput: Pick<AutonomousDeviceInput, 'forget'>
  detachDsh: (agentId: string) => void
  mirror: Pick<TurnRecaps, 'forget'>
  /** The app (`send`) and the dial (`sendCommander`). */
  clients: { send(frame: Frame): void; sendCommander(frame: Frame): void }
  dataDir: string
}

export function createForgetSession({
  registry, stoppedAgents, syncRecapPool, normalizers, forgetAttach, turnStartedAt, prompts, neverFoldedHistory, replayedFirstTurn, relaunchMarks,
  clearAgyIdleWatch, cursorDiscovery, cursorSubagents, runtimeProfiles, watcher, stopHeartbeat, input,
  deviceInput, detachDsh, mirror, clients, dataDir, onRemoved, owners, shortTurns,
}: ForgetDeps) {
  /** Release a mutable session binding, or remove the process-owned agent everywhere. */
  const forgetSession = (
    id: string,
    opts: { force?: boolean; keepAgent?: boolean; agentId?: string; captured?: RegisteredSession } = {},
  ): void => {
    const doomed = registry.resolve(id)
    const sessionId = doomed?.sessionId || id
    // Clients key on the AGENT id. Normally it is read off the entry, but an
    // agent already removed from the registry cannot be looked up — and
    // announcing its sessionId instead is silently useless: the app takes
    // payload.agentId verbatim, matches nothing, and leaves the dead row on
    // screen. Callers who know the id pass it.
    const announceId = doomed?.agentId ?? opts.agentId ?? sessionId

    console.log(opts.keepAgent
      ? `[agent] ${sid(announceId)} released session ${sid(sessionId)}`
      : `[agent] ${sid(announceId)} forgotten`)

    if (!opts.keepAgent && doomed) {
      const captured = opts.captured
      if (captured && (captured.agentId !== doomed.agentId || captured.engine !== doomed.engine
        || captured.registeredAt !== doomed.registeredAt || doomed.sessionId && captured.sessionId !== doomed.sessionId
        || captured.processIdentity && (!sameProcessIdentity(captured.processIdentity, doomed.processIdentity)
          || captured.processIdentity.executable !== doomed.processIdentity?.executable))) {
        throw new Error('The harness changed before its captured conversation could be retained.')
      }
      // Stop may prove a parent path while the live row still names an overwritten child.
      // Preserve that capture through this last archive, including intervening hook saves.
      stoppedAgents.save(captured ? { ...doomed, sessionId: captured.sessionId, transcriptPath: captured.transcriptPath,
        hermesHome: captured.hermesHome, boundAt: captured.boundAt, source: captured.source } : doomed)
    }
    if (opts.keepAgent) registry.unbindSession(sessionId)
    else if (doomed) registry.removeAgent(doomed.agentId)
    else registry.remove(sessionId)
    // No longer running, its last record may still hold a conversation another harness took meanwhile: the
    // save keeps a known one through an unbound row (StoppedAgentStore.save). One owner each from here on.
    if (!opts.keepAgent && doomed) {
      try { owners?.settleSaved(doomed.agentId) }
      catch (error) { console.warn(`[agent] ${sid(doomed.agentId)} could not settle who owns its conversation: ${error instanceof Error ? error.message : error}`) }
    }
    syncRecapPool()
    normalizers.forget(sessionId)
    forgetAttach(sessionId)
    turnStartedAt.delete(sessionId)
    shortTurns?.forget(sessionId)
    neverFoldedHistory.delete(sessionId)
    // Both sets are per-session and must die with it: left behind they grow without bound in a daemon
    // that runs for days, and a session forgotten then re-registered under the same id would inherit a
    // stale "already replayed" and lose a first turn it was entitled to.
    replayedFirstTurn.delete(sessionId)
    relaunchMarks?.forget(sessionId)
    clearAgyIdleWatch(sessionId)
    cursorDiscovery.remove(sessionId)
    cursorSubagents.forget(sessionId)
    void removePendingCursorTasks(dataDir, sessionId)
    runtimeProfiles.forget(sessionId)
    void watcher.removeSession(sessionId)
    stopHeartbeat(sessionId)
    input.forget(announceId)
    deviceInput.forget(announceId)
    if (!opts.keepAgent) { detachDsh(announceId); onRemoved?.(announceId); prompts.delete(announceId) }
    mirror.forget(sessionId) // aborts any in-flight recap + clears busy; KEEPS the persisted summary
    if (opts.keepAgent) return
    clients.send({ type: 'agent_deleted', payload: { agentId: announceId, retained: !!doomed } }) // web tab
    clients.sendCommander({ type: 'agent_deleted', payload: { agentId: announceId } })
  }
  return forgetSession
}