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.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
/**
* One Swarm's rows for a machine's host (design 4.10): exactly what `GET /hosts/:m`, `/pools` and `/assignments` gave
* before parts (the store's old host reads, which this replaced), built from a reassembled state, with `revision`
* replaced by `lastChangedAt` and the Leads conversation id added to agent rows.
*/
import { buddySleepManaged } from '../buddySleep.js'
import type { AuthUser } from '../../lib/ssoAuth.js'
import { activeWork, agent, isLeads, SuperTabError, conversation, type Agent, type SuperTabState } from '../model.js'
import { buddyChatOf, isSwarmBuddy, isSwarmBuddyChat } from '../buddies.js'
import { buddyEngineChat } from '../buddyEngine.js'
import { hostLocalGrid, machineContribution, machineLimitReached, machineRoom, type MachineCleanup } from '../machines.js'
import { agentProjectId, agentSetRole, canWatchAgent, confidentialSets, isConfidential, groupProject, ledProject, projectsOf, skillModeOf, startProject, skillSetOf, watchClosed, type ConfidentialSets } from '../projects.js'
import type { HostAgentRow, HostPool, HostRosterRow, HostTabRows } from './contract.js'
import { hostEtag } from './hostEtag.js'
import { coordinatorNameOf, FIRST_INSTRUCTIONS, roleNameOf } from '../instructions.js'
import { PM_RESTART_AFTER_MS } from '../timeChecks.js'
export interface HostLookups {
/** The Swarm's people with their account emails (observers). */
people: Array<{ id: string; email: string }>
/** Its agents whose session is confidential in another Swarm (confidential.ts): nobody but its machine's person watches them. */
confidential: Set<string>
/** Throws a SuperTabError when the agent's machine grant is gone (store.ts agentGrant). */
agentGrant(target: Agent): Promise<void>
/** This Mac's Harness Team accounts, which join wherever the Mac was added. */
teams: Array<{ machineId: string }>
githubApp: boolean
}
/** Removed machines whose host has not yet said it cleaned up (store.ts cleanups). */
const cleanups = (state: SuperTabState): MachineCleanup[] => [
...(state.machines ?? []).flatMap(m => m.removal ? [{ machineId: m.machineId, removalId: m.removal.id, machineOwnerId: m.contributorId }] : []),
...(state.machineCleanups ?? [])]
export async function hostTab(tabId: string, state: SuperTabState, machineId: string, user: AuthUser, lastChangedAt: number | null, lookups: HostLookups): Promise<HostTabRows> {
const rows = { tabId, lastChangedAt, roster: await roster(tabId, state, machineId, user, lastChangedAt, lookups),
pool: pool(tabId, state, machineId, user, lookups.githubApp), assignments: assignments(tabId, state, machineId, user) }
return { ...rows, etag: hostEtag(rows) }
}
async function roster(tabId: string, state: SuperTabState, machineId: string, user: AuthUser, lastChangedAt: number | null, lookups: HostLookups): Promise<HostRosterRow[]> {
const rows: HostRosterRow[] = []
// Where its owner added this Mac and its team account is missing, this host adds that account (cli/src/superTabs/host.ts).
const mac = state.machines?.find(m => m.machineId === machineId && m.contributorId === user.sub && m.scope === 'swarm' && !m.removal && !m.buddyOnly)
// Only as many as machine.contribute would take (machines.ts machineRoom): an old CLI retries any refusal but MACHINES_FULL
// for good, and stops only once its row goes (#2637).
const missing = (mac ? lookups.teams : []).filter(team => !state.machines?.some(m => m.machineId === team.machineId)
&& !state.machineCleanups?.some(c => c.machineId === team.machineId))
for (const team of missing.slice(0, machineRoom(state, user.sub, { team: true }))) {
rows.push({ tabId, joinTeam: { machineId: team.machineId, name: mac!.name, maxAgents: mac!.maxAgents } })
}
// Once per read: each row asks it for each person (task #4504). The state is this read's own, so nothing changes it meanwhile.
const sets = confidentialSets(state)
for (const target of state.agents.filter(a => a.machineId === machineId && a.machineOwnerId === user.sub)) {
try { agent(state, target.id); await lookups.agentGrant(target) } catch (error) { if (error instanceof SuperTabError) continue; throw error }
rows.push(agentRow(tabId, state, machineId, user, lastChangedAt, lookups, target, sets))
}
for (const { agentId: id, harnessId } of (state.closingSessions ?? []).filter(c => c.machineId === machineId && c.machineOwnerId === user.sub)) {
rows.push({ tabId, agent: { id, harnessId, machineId }, closeSession: true, active: false })
}
rows.push(...cleanups(state).filter(c => c.machineId === machineId && c.machineOwnerId === user.sub)
.map(({ removalId }) => ({ tabId, cleanup: { machineId, removalId } })))
return rows
}
function agentRow(tabId: string, state: SuperTabState, machineId: string, user: AuthUser, lastChangedAt: number | null, lookups: HostLookups, target: Agent,
sets: ConfidentialSets): HostAgentRow {
const closed = lookups.confidential.has(target.id)
const waiting = state.conversations.find(c => activeWork(c) && c.assignment!.agentId === target.id &&
c.assignment!.execution.machineId === machineId && ['needs_human', 'blocked'].includes(c.assignment!.status))?.assignment
// A task it lost to a usage limit that gave a reset time, while nobody has handed it on: its host resumes it then
// (cli superTabs/limitResume.ts), and the backend still decides (commands.ts work.resume).
const marked = target.lostTask
const lost = marked?.resumeAt ? state.conversations.find(c => c.id === marked.conversationId)?.assignment : undefined
const resume = marked?.resumeAt && lost?.id === marked.assignmentId && lost.status === 'lost' && lost.lost?.at === marked.at
? { conversationId: marked.conversationId, assignmentId: marked.assignmentId, lostAt: marked.at, at: marked.resumeAt } : null
const home = projectsOf(state).find(p => p.id === agentProjectId(state, target))
const custom = home && skillSetOf(home) === 'custom' ? home : null
const chosen = custom ? agentSetRole(state, custom, target) : null
const buddyChat = isSwarmBuddy(target) || (target.buddySession && target.buddyOf) ? buddyChatOf(state, target) : undefined
return {
tabId, tabName: state.name, lastChangedAt, paused: state.paused,
// `active` lets the host release members that are only in archived groups to automatic cleanup.
active: state.conversations.some(c => !c.archived && c.agentIds.includes(target.id)),
attention: waiting ? { assignmentId: waiting.id, status: waiting.status, result: waiting.result?.slice(0, 500) ?? null } : null,
resume,
agent: target,
...(buddySleepManaged(state, target) ? { buddySleepManaged: true as const } : {}),
// A Buddy-only record is not the machine in the Swarm: the owner's Lead there still joins it, which makes the record an ordinary
// machine (commands.ts machine.contribute ifMissing; security review 2 of #2234).
// Not where machine.contribute would refuse it (#2637): a Buddy-only record is counted already, so it still joins.
joinSwarm: state.ownerId === user.sub && target.contributorId === user.sub && !state.machines?.some(m => m.machineId === machineId && !m.buddyOnly)
&& (state.machines?.some(m => m.machineId === machineId) || !machineLimitReached(state, user.sub))
&& state.conversations.some(c => !c.archived && c.leadId === target.id),
skillMode: home ? skillModeOf(home) : 'orchestration',
// What the host installs as the agent's instructions, read again when the revision moves (project instructions, phase 3).
roleName: roleNameOf(state, target),
// At revision 0 (nothing saved) the hash is the template's, so a backend release that changes the template moves it and
// running daemons read the text again (2026-11-02: agents kept the old routing after #2495, as revision 0 never moves).
instructions: home ? { projectId: home.id, revision: home.instructionsRevision ?? 0,
hash: home.instructionsHash ?? (home.instructionsRevision ? null : FIRST_INSTRUCTIONS.instructionsHash),
coordinatorName: coordinatorNameOf(home) } : null,
...(custom ? { role: chosen && { ...chosen, projectId: custom.id } } : {}),
lead: !!ledProject(state, target.id),
// What a PM owes people, and how long it may while it hangs: its host restarts it after that (timeChecks.ts, cli host.ts).
owed: (() => { const owed = ledProject(state, target.id)?.owed; return owed ? { ...owed, restartAfterMs: PM_RESTART_AFTER_MS } : null })(),
// Removed (model.ts leadsRemoved); an older CLI still reads the field, so it stays, always empty.
leadsConversationId: null,
// The conversation it leads: the chat its host rebuilds its start prompt from when it switches it (cli leadSwitchRequest.ts).
// A field of its own: an older host reads leadsConversationId as "only this conversation's deliveries" (cli host.ts).
ledConversationId: ledProject(state, target.id)?.leadConversationId ?? null,
...(isSwarmBuddy(target) && !target.buddySession ? { buddyConversationId: buddyChat?.id ?? buddyEngineChat(state, target) } : {}),
stopRequested: target.workDecision === 'stop' && !state.conversations.some(c => activeWork(c) && c.assignment?.agentId === target.id),
observers: lookups.people.filter(p => p.id !== user.sub && canWatchAgent(state, { kind: 'person', userId: p.id, email: p.email }, target, closed, sets))
.map(p => ({ email: p.email, userId: p.id })),
// The host refuses every share of a confidential session, ordinary ones too, and remembers it (cli observers.ts).
confidential: isConfidential(state, target, closed, sets),
// But for this Swarm's current Lead: its listed observers watch it while this row is in force (Ken, 2026-10-28).
membersWatch: isConfidential(state, target, closed, sets) && !watchClosed(state, target, closed, sets),
// Which of its person's Buddies' chats it is in (task #3818).
...isSwarmBuddy(target) || (target.buddySession && target.buddyOf) ? { buddyChatId: buddyChat?.id ?? null } : {},
}
}
function pool(tabId: string, state: SuperTabState, machineId: string, user: AuthUser, githubApp: boolean): HostPool | null {
let contribution
try { contribution = machineContribution(state, machineId) } catch (error) { if (error instanceof SuperTabError) return null; throw error }
if (!contribution || contribution.contributorId !== user.sub) return null
const pending = (state.starts ?? []).filter(s => s.request.machineId === machineId && s.poolGeneration === contribution.generation
&& (!s.harnessId || !s.poolSettled) && !s.error)
// A host from before Buddies reads only `starts`, and would launch a Buddy as a Builder: it never sees one. Nor a Product
// Manager (leadStart.ts), which goes only to a host that said it starts one.
// Nor a Regular agent (commands.ts agent.new, task #4116), which an older host would launch in a project folder it lacks.
const starts = pending.filter(s => !s.request.buddyOf && !s.request.leadFor && !s.request.regular), buddyStarts = pending.filter(s => s.request.buddyOf)
const regularStarts = pending.filter(s => s.request.regular)
const leadStarts = pending.filter(s => s.request.leadFor)
const buddyChats = new Set(buddyStarts.map(s => s.request.conversationId))
const reservations = (state.harnessReservations ?? []).filter(r => r.machineId === machineId)
const removedHere = (state.removedSessions ?? []).filter(r => r.machineId === machineId).map(r => r.harnessId)
return { tabId, paused: state.paused, machine: contribution, starts, ...(buddyStarts.length ? { buddyStarts } : {}), ...(leadStarts.length ? { leadStarts } : {}),
...(regularStarts.length ? { regularStarts } : {}),
...(contribution.scope === 'swarm' ? { projects: projectsOf(state).filter(p => pending.some(s => startProject(state, s.request)?.id === p.id))
.map(p => ({ id: p.id, leadConversationId: p.leadConversationId, repository: p.repository,
// A private conversation is chat only and never runs work here, so its id stays with its audience; a Buddy chat whose
// Buddy starts here is named, so the host may prepare the project's folder for it.
conversationIds: state.conversations.filter(c => !isLeads(c) && !isSwarmBuddyChat(c) && (!c.audience || buddyChats.has(c.id)) && groupProject(state, c).id === p.id).map(c => c.id) })) } : {}),
// A Buddy-only machine never joins the Swarm's grid: it serves nobody's models (machines.ts buddyOnly).
...(contribution.buddyOnly ? {} : hostLocalGrid(state)),
reservations: reservations.map(({ harnessId, generation }) => ({ harnessId, generation })),
// Sessions whose agents left as closed, which this host lists again if they reopen (closedAgents.ts restoreSessions). Ids only,
// and only to the machine's own host. Absent when there are none.
...(removedHere.length ? { removedHarnessIds: removedHere } : {}),
harnessIds: [...new Set([...state.agents.filter(a => a.machineId === machineId).map(a => a.harnessId), ...reservations.map(r => r.harnessId),
...(state.starts ?? []).filter(s => s.request.machineId === machineId && s.harnessId).map(s => s.harnessId!)])],
...(githubApp ? { githubApp: true as const } : {}),
// Asks the host to say what it launches beyond workers (machines.ts `capabilities`): a host never sends a field this
// server did not ask for, so an older server, which would refuse every reading with it, never sees it.
buddySleepWanted: true as const, capabilitiesWanted: true as const }
}
function assignments(tabId: string, state: SuperTabState, machineId: string, user: AuthUser) {
return state.conversations.filter(activeWork).flatMap(group => {
const work = group.assignment!
return work.execution.machineId === machineId && work.execution.machineOwnerId === user.sub
? [{ tabId, assignmentId: work.id, harnessId: work.execution.harnessId }] : []
})
}