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.5 KB
Raw Blame
import { isBuddy } from './buddies.js'
import { isCrew } from './crew.js'
import { MACHINE_FRESH_MS, productManagerOn, teamAccountPool, teamWorkCheck, type MachineObservation } from './machines.js'
import { activeWork, type Agent, type RemovedSession, type SuperTabState } from './model.js'
import { agentProjectId, canReadProject, isConfidential, ledProject, onTeamAccount, projectsOf } from './projects.js'
import { barredFromTeamWritten } from './teamWritten.js'

// Huy, 2026-11-02: four agents closed on their machine sat under Idle for hours, each in the machine's stopped list, because
// only an agent's own host removed it, and only after a stop was asked for. A session closed by hand never asked. Now the
// report that shows a session gone removes its agent (docs/plans/2026-11-02-closed-agents-leave-list-plan.md).

/** How long an agent not listed running stays before its machine, still reporting, removes it without a stopped list. */
export const DOWN_REMOVE_MS = 15 * 60_000
/** The most records of removed agents one machine keeps, the oldest going first, and how long one lasts. */
export const REMOVED_KEPT = 50
export const REMOVED_KEEP_MS = 30 * 24 * 60 * 60_000
/** How long an agent whose session is listed stopped stays first: a host mid-restart, or an agent changing its session, lists
 *  one stopped for a moment before it is back (security reviews of #2569). */
export const STOPPED_REMOVE_MS = 30_000

/** Whether [target] could ever leave this way: not a coordinator, a Buddy, a Regular agent, crew (its host reopens it in place,
 *  crew.ts), one kept or being stopped. A Regular agent is its person's, as a Buddy is: removed, it never came back, since its own
 *  chat made it confidential and it has no project to restore into (task #4218). Its person stops it. */
const removable = (state: SuperTabState, target: Agent): boolean =>
  !isBuddy(target) && !target.regular && !isCrew(target) && target.workDecision !== 'keep' && target.workDecision !== 'stop' && !ledProject(state, target.id)

/** Whether [report] proves [target]'s session stopped: listed stopped and, for a reservation a resume renewed, stopped in that
 *  very generation, since an older host lists the earlier run stopped and cannot say which. */
const provedStopped = (state: SuperTabState, target: Agent, report: Pick<MachineObservation, 'stoppedHarnessIds' | 'stoppedReservations'>): boolean => {
  if (!report.stoppedHarnessIds.includes(target.harnessId)) return false
  const reservation = state.harnessReservations?.find(r => r.machineId === target.machineId && r.harnessId === target.harnessId)
  return !reservation || !reservation.renewed || !!report.stoppedReservations?.some(r => r.harnessId === target.harnessId && r.generation === reservation.generation)
}

/** Whether [target]'s machine, reading now, proves its idle cleanup closed its session: a fresh reading that lists it closed
 *  and stopped, not running. Such an agent takes no task (commands.ts work.assign): on 11-04 the idle cleanup closed Tern on
 *  the Mac Studio and the PM assigned it six seconds later, so the task was lost at once (task #2744). A session merely
 *  listed stopped may be a Change agent before its rebind, or a host mid-restart, and keeps taking work (review of #2953). */
export function sessionClosed(state: SuperTabState, target: Agent, now: number): boolean {
  const reading = state.machines?.find(m => m.machineId === target.machineId)?.observation
  return !!reading && now - reading.receivedAt <= MACHINE_FRESH_MS && !reading.runningHarnessIds.includes(target.harnessId)
    && !!reading.closedHarnessIds?.includes(target.harnessId) && provedStopped(state, target, reading)
}

/**
 * The agents of [machineId] that [report], arriving now over the reading in [state], shows closed: not listed running, down
 * for a while, and either proved stopped (the proof the slot count accepts, machines.ts machineSlots; STOPPED_REMOVE_MS) or
 * not listed for DOWN_REMOVE_MS while the machine's other sessions still run. The last reading must be fresh and not list
 * them running either, so one report after a silence never removes anyone, and a report whose running list is empty never
 * removes by time (a fault in the host's listing would empty a whole machine). Never a coordinator (a project's end is the
 * only removal that takes one), a Buddy or a Regular agent (its person stops it), an agent someone chose to keep: it stays, shown as closed, or
 * one being stopped: its host closes it and takes it out (commands.ts agent.remove). Whether a task is still held is judged by
 * removeClosedAgents, after the loss of tasks.
 */
export function closedAgents(state: SuperTabState, machineId: string, report: Pick<MachineObservation, 'runningHarnessIds' | 'stoppedHarnessIds' | 'stoppedReservations'>, now: number): Agent[] {
  const previous = state.machines?.find(m => m.machineId === machineId)?.observation
  const fresh = previous && now - previous.receivedAt <= MACHINE_FRESH_MS ? previous : undefined
  if (!fresh) return []
  return state.agents.filter(target => {
    if (target.machineId !== machineId || report.runningHarnessIds.includes(target.harnessId) || fresh.runningHarnessIds.includes(target.harnessId)) return false
    if (!removable(state, target)) return false
    if (!target.downSince) return false
    const down = now - Date.parse(target.downSince)
    if (report.stoppedHarnessIds.includes(target.harnessId)) return down >= STOPPED_REMOVE_MS && provedStopped(state, target, report)
    return down >= DOWN_REMOVE_MS && report.runningHarnessIds.length > 0 && fresh.runningHarnessIds.length > 0
  })
}

/** The record that its host closes the session of a removed agent: a confidential session in a Team account keeps the account
 *  for its project until the host confirms the close, which it does once the session's data there is deleted (security re-check
 *  2 of #2089). The close also frees the session's slot (commands.ts agent.sessionClosed). Written before the agent leaves its
 *  groups, which decide whether the session is confidential. */
export function recordClosing(state: SuperTabState, target: Agent, now: number): void {
  if (state.closingSessions?.some(c => c.agentId === target.id && c.harnessId === target.harnessId)) return
  const held = onTeamAccount(state, target) && isConfidential(state, target) ? { heldFor: agentProjectId(state, target), since: now } : {}
  // Its machine part outlives the Buddy-only record while this closes: it stays as private as the record (read/changes.ts).
  const hidden = state.machines?.some(m => m.machineId === target.machineId && m.buddyOnly) ? { buddyOnly: true as const } : {}
  ;(state.closingSessions ??= []).push({ agentId: target.id, machineId: target.machineId, harnessId: target.harnessId, machineOwnerId: target.machineOwnerId, ...held, ...hidden })
}

/** Removes those of [closed] that hold no task now: from the agents and from every group's members and leads, as commands.ts
 *  removeAgent does, with the close order its host needs. A task just lost keeps its agent until its Lead hands it on or
 *  cancels it (it is still fenced and told by name, liveness.ts); the next report removes the agent then. The removed agents,
 *  for the caller to cancel what waits for them. */
export function removeClosedAgents(state: SuperTabState, closed: Agent[], now: number): Agent[] {
  const holding = new Set(state.conversations.filter(group => activeWork(group) || group.assignment?.status === 'lost').map(group => group.assignment!.agentId))
  const removed = closed.filter(target => !holding.has(target.id))
  if (!removed.length) return []
  for (const target of removed) recordClosing(state, target, now)
  const gone = new Set(removed.map(target => target.id))
  for (const target of removed) keepRecord(state, target, now)
  state.agents = state.agents.filter(target => !gone.has(target.id))
  for (const group of state.conversations) {
    group.agentIds = group.agentIds.filter(id => !gone.has(id))
    if (group.leadId && gone.has(group.leadId)) group.leadId = null
  }
  return removed
}

/** What a removal restores from if the session reopens (task #2131), unless the agent is meant to stay gone: someone asked it to stop,
 *  or its session held private chats, which purge deletes. Only what it was, not how it was doing: down, stopping, lost, noticed. */
function keepRecord(state: SuperTabState, target: Agent, now: number): void {
  const others = (state.removedSessions ?? []).filter(r => r.machineId !== target.machineId || r.harnessId !== target.harnessId)
  // An older record of this session goes either way: it would undo the stop or the purge this removal stands for.
  if (target.workDecision === 'stop' || target.confidential || isConfidential(state, target)) {
    if (state.removedSessions) state.removedSessions = others
    return
  }
  const { downSince: _down, lostTask: _lost, releaseId: _release, idleStop: _idle, idleNoticedAt: _noticed, workDecision: _decision,
    switchRequest: _switch, switchLanded: _landed, modelRequest: _model, alerting: _alerting, ...agent } = target
  const mine = others.filter(r => r.machineId === target.machineId)
  const over = mine.length + 1 - REMOVED_KEPT
  const dropped = new Set(over > 0 ? [...mine].sort((a, b) => a.removedAt - b.removedAt).slice(0, over) : [])
  state.removedSessions = [...others.filter(r => !dropped.has(r)), { machineId: target.machineId, harnessId: target.harnessId, agent,
    groupIds: state.conversations.filter(group => group.agentIds.includes(target.id)).map(group => group.id),
    leadOf: state.conversations.filter(group => group.leadId === target.id).map(group => group.id), removedAt: now }]
}

/** This machine's unexpired records of sessions [running] lists again, for the report to read their groups before restoring them. */
export const reopened = (state: SuperTabState, machineId: string, running: readonly string[], now: number): RemovedSession[] =>
  (state.removedSessions ?? []).filter(r => r.machineId === machineId && running.includes(r.harnessId) && now - r.removedAt < REMOVED_KEEP_MS)

/** What a restore's rules read outside the Swarm's state: sessions registered in another Swarm by now, and the machines
 *  commands.ts agent.add's team rules read (store.ts teamMachines, otherWorkspaceMachines). */
export interface RestoreFacts { elsewhere: ReadonlySet<string>; teamMachines: readonly string[]; otherWorkspaceMachines: readonly string[] }

/**
 * Why [record] may not come back as it was, by a fixed word, or null. The rules a person's add takes (commands.ts agent.add, whose
 * session record and share the caller checks after this), each read from the state this write loaded, as any of it may have
 * changed since: its machine's Team account may serve another project now, and that machine may no longer take a teammate's.
 */
export function restoreRefusal(state: SuperTabState, record: RemovedSession, machineOwnerId: string, now: number, facts: RestoreFacts): string | null {
  const { agent } = record
  // The record names its own session; a machine reports only its own, and a report is the only way here.
  if (agent.machineId !== record.machineId || agent.harnessId !== record.harnessId || agent.machineOwnerId !== machineOwnerId) return 'not-this-machine'
  if (state.agents.some(a => a.id === agent.id || (a.machineId === record.machineId && a.harnessId === record.harnessId))) return 'already-listed'
  if (facts.elsewhere.has(record.harnessId)) return 'in-another-swarm'
  if (state.closingSessions?.some(c => c.machineId === record.machineId && c.harnessId === record.harnessId && c.heldFor)) return 'team-held'
  // Its contributor may be another person, on a machine shared with them: they must still be here, and the share must hold.
  const contributor = state.people.find(p => p.id === agent.contributorId)
  if (!contributor || contributor.generation !== agent.membershipGeneration || contributor.role === 'viewer') return 'contributor-changed'
  const project = projectsOf(state).find(p => p.id === agentProjectId(state, agent))
  if (!project || !canReadProject(state, { kind: 'person', userId: contributor.id, email: contributor.email }, project)) return 'project-ended'
  if (teamAccountPool(state.machines?.find(m => m.machineId === record.machineId))) {
    const held = productManagerOn(state, record.machineId)
    if (held && held !== project.id) return 'team-other-project'
  }
  return teamWorkCheck(state, record.machineId, agent.contributorId, project) ? 'team-work' : null
}

/**
 * Brings back the agents of [machineId] whose sessions [running] lists again and the caller [allowed], from the records their
 * removal kept, and drops the records that came due or were refused. Called only with a report already proved to be this machine's;
 * no command reaches it. An agent comes back only to the open groups of its own project it was in: never a private chat, since who
 * may read there is not its to decide again, nor a task marked Team-written while it was away, unless it runs in a Team account.
 * The restored agents.
 */
export function restoreSessions(state: SuperTabState, machineId: string, running: readonly string[], now: number,
  allowed: ReadonlySet<string>, reserve: (harnessId: string) => void): Agent[] {
  const records = state.removedSessions
  if (!records?.length) return []
  const restored: Agent[] = []
  const projectChats = new Set(projectsOf(state).map(p => p.leadConversationId))
  const left = records.filter(record => {
    if (record.machineId !== machineId) return true
    if (now - record.removedAt >= REMOVED_KEEP_MS) return false
    if (!running.includes(record.harnessId)) return true
    if (!allowed.has(record.harnessId)) return false
    state.agents.push(record.agent)
    reserve(record.harnessId)
    // Back before its host closed it: the session stays open, as when a person adds it back (commands.ts agent.add). A close held for
    // a Team account was refused: that account stays held until its host confirms (restoreRefusal, `team-held`).
    state.closingSessions = state.closingSessions?.filter(c => c.machineId !== record.machineId || c.harnessId !== record.harnessId)
    if (!state.closingSessions?.length) delete state.closingSessions
    for (const group of state.conversations) {
      if (group.archived || group.dormant || group.kind || group.audience || (state.projects && group.projectId !== record.agent.projectId)) continue
      if (barredFromTeamWritten(state, group, record.agent)) continue
      if (record.leadOf.includes(group.id) && !group.leadId) group.leadId = record.agent.id
      // A project chat holds only its coordinator among agents (#2207): a member there comes back to it only as its coordinator.
      if (projectChats.has(group.id) && group.leadId !== record.agent.id) continue
      if (record.groupIds.includes(group.id) && !group.agentIds.includes(record.agent.id)) group.agentIds.push(record.agent.id)
    }
    restored.push(record.agent)
    return false
  })
  if (left.length !== records.length) state.removedSessions = left
  return restored
}

/** The next time a report of [machineId] could remove an agent, after those it just judged: its reports skip the full load
 *  until then (machineReports.ts), so a stopped list that stays the same still removes its agent when its wait ends. */
export function nextRemovalAt(state: SuperTabState, machineId: string, now: number): number | undefined {
  const stopped = state.machines?.find(m => m.machineId === machineId)?.observation?.stoppedHarnessIds ?? []
  const ends = state.agents.filter(a => a.machineId === machineId && a.downSince && removable(state, a))
    .map(a => Date.parse(a.downSince!) + (stopped.includes(a.harnessId) ? STOPPED_REMOVE_MS : DOWN_REMOVE_MS))
    .filter(end => end > now)
  return ends.length ? Math.min(...ends) : undefined
}