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
/** A project's Product Manager started by the Swarm on one of its machines (Dee, 10-29, option B), as a Buddy's start is
* (buddies.ts): recorded on the machine's contribution and launched by its host. Its person names the machine, which is their
* own computer: Swarm v3 starts no agent on another person's computer and none in a Team account (task #4120). Desktop's
* own-machine flow (project.create, a local start, agent.add) is unchanged. */
import { admitMachineStart, contributedEngines, failTeamWork, machineContribution, NOT_YOUR_COMPUTER, projectFolder, projectsOnMachine, teamAccountPool,
noRepositoryStart, slotCounter, TEAM_ACCOUNTS_GONE, type ContributedMachine } from './machines.js'
import { actorKey, fail, person, SuperTabError, type AgentStart, type AgentStartRequest, type Conversation, type Person, type SuperTabState } from './model.js'
import { BUILT_IN_ROLE_DEFAULTS, projectsOf, type SwarmProject } from './projects.js'
import { failureNotice, publicReason } from './startFailure.js'
import { coordinatorNameOf } from './instructions.js'
/** What a host reports it can launch: a Product Manager. A host from before it is never given one. */
export const LEAD_CAPABILITY = 'leadStart'
/** The coordinator's name in rows written before projects could name it (store.ts reads them for Buddies); new rows use what
* the project calls it (instructions.ts coordinatorNameOf). */
export const LEAD_NAME = 'Product Manager'
/** Memory and disk gate it; CPU use is one momentary sample, so it is not capped, as a routed Builder's start (Diego, 10-30). */
export const LEAD_REQUIREMENTS: AgentStartRequest['requirements'] = { memoryBytes: 2 * 1024 ** 3, diskBytes: 1024 ** 3, maxCpuPercent: 100,
tools: ['git'], devices: [], quotaRequired: false }
/** Where the project's Product Manager is: starting on the machine its person named, started, or failed with the reason. */
export interface LeadPlacement {
status: 'starting' | 'started' | 'failed'
machineId: string
machineName: string
startId?: string
reason?: string
}
/** `repositoryUrl`: the address its folder is cloned from, recorded for a project that has none yet. */
export interface LeadRequest { engine: string; model?: string; effort?: string; branchRef?: string; repositoryUrl?: string }
export interface LeadContext {
now: number
teamMachines?: readonly string[]
otherWorkspaceMachines?: readonly string[]
/** The slots of each pool, counted once for a read that admits many (machines.ts slotCounter). */
slots?: (pool: ContributedMachine) => number
}
/** Efforts a Product Manager never runs at (task #3022, Ken 11-05): it keeps what people teach it only when it thinks hard
* enough to. Claude's and Codex's names below high. */
const BELOW_LEAD_EFFORT = new Set(['none', 'minimal', 'low', 'medium'])
/** The effort a Product Manager gets when its start or switch names a model and no effort. */
export const LEAD_EFFORT = 'high'
/** [request] for a Product Manager at high effort or above: an effort named below it is refused, and a model named with no
* effort gets the coordinator's own default effort for that model (Claude Opus at xhigh, as its start; review of #3066, 3),
* else high. With no model it keeps its engine's own model and effort, which its host sets only together. */
export function leadEffort<T extends { engine: string; model?: string; effort?: string }>(request: T, name: string): T {
if (request.effort && BELOW_LEAD_EFFORT.has(request.effort.toLowerCase())) {
fail('EFFORT_TOO_LOW', `A ${name} runs at high effort or above, so it keeps what people teach it. Choose high, xhigh or max.`, 400)
}
if (!request.model || request.effort) return request
const defaults = BUILT_IN_ROLE_DEFAULTS.lead
const own = defaults?.engine === request.engine && defaults.model && family(defaults.model) === family(request.model) ? defaults.effort : undefined
return { ...request, effort: own ?? LEAD_EFFORT }
}
/** The engines a Product Manager runs on, as people read them. */
const LEAD_ENGINES = { claude: 'Claude Code', codex: 'Codex' } as const
/** Admits [project]'s Product Manager as [start] asks, in [pool], or throws why not. Writes nothing. */
function admitLead(state: SuperTabState, project: SwarmProject, pool: ContributedMachine, start: AgentStartRequest, context: LeadContext): void {
if (!contributedEngines(pool).includes(start.engine)) {
fail('ENGINE_NOT_OFFERED', `${LEAD_ENGINES[start.engine as keyof typeof LEAD_ENGINES] ?? start.engine} isn’t offered on ${pool.name}.`, 403)
}
admitMachineStart(state, start, context.now, undefined, context.teamMachines, context.otherWorkspaceMachines, project, context.slots)
// Its Team account will serve only this project (machines.ts productManagerOn), so not one running another's work now.
if (teamAccountPool(pool) && [...projectsOnMachine(state, pool.machineId)].some(id => id !== project.id)) {
fail('TEAM_ACCOUNT_BUSY', `The Harness Team account on ${pool.name} runs other projects' agents, so it cannot host this ${coordinatorNameOf(project)} now.`, 409)
}
if (!pool.observation?.capabilities?.includes(LEAD_CAPABILITY)) {
fail('HOST_OUTDATED', `Update Harness on ${pool.name} to run a ${coordinatorNameOf(project)} there.`, 409)
}
}
/** Where [project]'s Product Manager with [request]'s engine runs when its person names [machineId], as its start request; or
* throws why it cannot run there now. Writes nothing. The machine itself for its own owner; on another person's Mac, its
* Harness Team account when that admits this Product Manager with this engine now, else the Mac itself, as its owner,
* unless the Mac was added as its person joined. A Team account named itself keeps its rules and is refused with its reason.
* The start (placeLead) and New Project's machine list (leadChoices) both read it, so they never disagree. */
export function leadHost(state: SuperTabState, project: SwarmProject, machineId: string, request: LeadRequest, leadFor: AgentStartRequest['leadFor'],
context: LeadContext): AgentStartRequest {
// A machine whose owner left the Swarm stays listed while its host cleans up. Its contribution is withdrawn; machineContribution
// would tell the person starting the Product Manager that they lost access themselves.
const listed = state.machines?.find(m => m.machineId === machineId)
if (listed && !state.people.some(p => p.id === listed.contributorId)) fail('CONTRIBUTION_REVOKED', 'This machine contribution was withdrawn.', 403)
const named = machineContribution(state, machineId) ?? fail('MACHINE_NOT_LISTED', 'Add this machine to the Swarm first.', 403)
const startIn = (pool: ContributedMachine): AgentStartRequest => noRepositoryStart(pool, project, { conversationId: project.leadConversationId, machineId: pool.machineId,
engine: request.engine, ...(request.model ? { model: request.model } : {}), ...(request.effort ? { effort: request.effort } : {}), name: coordinatorNameOf(project),
cwd: projectFolder(pool, project), worktree: true, ...(request.branchRef ? { branchRef: request.branchRef } : {}), requirements: LEAD_REQUIREMENTS, leadFor })
// A PM starts only on its person's own computer, as them, and never in a Team account (task #4120, the PM's ruling): the
// person starting it is [leadFor]'s, else the project's owner.
if (teamAccountPool(named)) failTeamWork(TEAM_ACCOUNTS_GONE)
if (named.contributorId !== (leadFor?.personId ?? project.ownerId)) failTeamWork({ code: 'NOT_YOUR_COMPUTER', reason: NOT_YOUR_COMPUTER })
const start = startIn(named)
admitLead(state, project, named, start, context)
return start
}
/** Where New Project's Product Manager would run on each teammate's machine, for [personId] as its owner, by engine: the
* machine it runs in, or why it cannot run there now. The same answer leadHost gives the start, before the project exists, so
* Desktop shows the server's decision rather than working one out (security review 1 of #2228). The person's own machines
* are left to Desktop, which starts the Product Manager there itself; a Team account is read through its Mac. Reasons name
* no other project. */
export function leadChoices(state: SuperTabState, personId: string, context: LeadContext): Record<string, Record<string, { machineId: string } | { refused: string }>> {
const by = state.people.find(p => p.id === personId)
if (!by || state.paused) return {}
const project = { id: '', name: '', ownerId: personId, leadConversationId: '', visibility: 'private', members: [], updateMinutes: 5,
skillMode: 'default' } as unknown as SwarmProject
const leadFor = { projectId: '', personId, generation: by.generation }
// Every teammate's machine and engine is admitted against this one state: its slots are counted once (prod 10-31: a quarter
// of a change read's CPU, each admission grouping the Swarm's 543 released harnesses again).
context = { ...context, slots: context.slots ?? slotCounter(state) }
const choices: Record<string, Record<string, { machineId: string } | { refused: string }>> = {}
for (const machine of state.machines ?? []) {
if (machine.hostMachineId || machine.removal || machine.contributorId === personId) continue
choices[machine.machineId] = Object.fromEntries(Object.keys(LEAD_ENGINES).map(engine => {
try {
return [engine, { machineId: leadHost(state, project, machine.machineId, { engine }, leadFor, context).machineId }]
} catch (error) {
if (!(error instanceof SuperTabError)) throw error
return [engine, { refused: error.message }]
}
}))
}
return choices
}
/** Records the start of [project]'s Product Manager on [machineId] for [by], and marks the project starting. Refuses, and
* changes nothing, when that machine cannot take it now. */
export function placeLead(state: SuperTabState, project: SwarmProject, by: Person, machineId: string, request: LeadRequest,
startId: string, context: LeadContext): AgentStart {
const start = leadHost(state, project, machineId, request, { projectId: project.id, personId: by.id, generation: by.generation }, context)
const pool = machineContribution(state, start.machineId)!
state.starts ??= []
if (state.starts.filter(s => !s.harnessId && !s.error).length >= 32) fail('STARTS_PENDING', 'Reconcile pending agent starts before adding more.')
const contributor = person(state, pool.contributorId)
const recorded: AgentStart = { poolGeneration: pool.generation, id: startId, creationId: `super-${startId}`,
actorKey: actorKey({ kind: 'person', userId: by.id, email: by.email }), contributorId: contributor.id,
membershipGeneration: contributor.generation, machineOwnerId: pool.contributorId, hostGrant: null, request: start,
harnessId: null, dispatched: false, error: null, requestedAt: context.now }
state.starts.push(recorded)
project.repository ??= { machineId: pool.machineId, cwd: start.cwd, repositoryUrl: request.repositoryUrl ?? null }
project.lead = { status: 'starting', machineId: pool.machineId, machineName: pool.name, startId }
return recorded
}
/** A start of [project]'s Product Manager not yet running or failed. */
export const leadStarting = (state: SuperTabState, projectId: string): AgentStart | undefined =>
state.starts?.find(s => s.request.leadFor?.projectId === projectId && !s.harnessId && !s.error)
const placementOf = (state: SuperTabState, start: AgentStart): LeadPlacement | undefined => {
const lead = start.request.leadFor && projectsOf(state).find(p => p.id === start.request.leadFor!.projectId)?.lead
return lead?.startId === start.id ? lead : undefined
}
/** A person set another coordinator while this start ran (both security reviews of #2636): it never joins the project chat. The
* start ends with the reason and its placement is forgotten, as the project has its coordinator. The line its conversation
* shows and its source, a system row naming the machine as leadJoined's does; null when no coordinator holds the chat. */
export function leadOvertaken(state: SuperTabState, start: AgentStart, home: Conversation): { text: string; reason: string; source: { kind: 'system'; machine?: string } } | null {
const holder = home.leadId && home.agentIds.includes(home.leadId) ? state.agents.find(a => a.id === home.leadId) : undefined
const project = start.request.leadFor && projectsOf(state).find(p => p.id === start.request.leadFor!.projectId)
if (!holder || !project) return null
const placement = placementOf(state, start)
const machine = placement?.machineName ?? state.machines?.find(m => m.machineId === start.request.machineId)?.name
if (placement) delete project.lead
const name = coordinatorNameOf(project)
const reason = `This project already has ${holder.displayName ?? holder.name} as its ${name}.`
return { reason, text: `${name} started on ${machine ?? 'its machine'}, but this project already has ${holder.displayName ?? holder.name} as its ${name}, so it did not join.`,
source: machine ? { kind: 'system', machine } : { kind: 'system' } }
}
/** Its agent [agentId] joined the project's Lead conversation [home]: it leads it, unless a Lead was added there by hand
* meanwhile, which stays. The line its conversation shows, and its source: a system row naming the machine, so a Buddy reads
* it without the name (store.ts withoutMachineNames; Diego, 10-30). */
export function leadJoined(state: SuperTabState, start: AgentStart, home: Conversation, agentId: string): { text: string; source: { kind: 'system'; machine?: string } } {
if (!home.leadId || !home.agentIds.includes(home.leadId)) home.leadId = agentId
const placement = placementOf(state, start)
if (placement) placement.status = 'started'
const machine = placement?.machineName ?? state.machines?.find(m => m.machineId === start.request.machineId)?.name
const project = start.request.leadFor && projectsOf(state).find(p => p.id === start.request.leadFor!.projectId)
const started = `${project ? coordinatorNameOf(project) : start.request.name} started on ${machine ?? 'its machine'}.`
const ran = state.agents.find(a => a.id === agentId)?.configuration
const other = ran && otherThanAsked(start.request, ran)
return { text: other ? `${started} ${other}` : started, source: machine ? { kind: 'system', machine } : { kind: 'system' } }
}
/** A Product Manager's start line when its machine could not launch it with the model and effort it asked for, so it runs its
* engine's own model (Desktop's own-machine start; the Swarm's start says it in leadJoined). [name]: what its project calls it. */
export const launchRefusedLine = (asked: { model: string; effort?: string }, name: string) =>
`${name} started. It asked for ${asked.effort ? `${asked.model} at ${asked.effort}` : asked.model} and runs its engine\u2019s own model there: this machine could not launch it with them.`
/** A Claude id by its family (`claude-opus-5-5[1m]` is opus), as the CLI's route rates it. */
const family = (model: string) => /haiku|sonnet|opus|fable/.exec(model.toLowerCase())?.[0] ?? model.toLowerCase()
/** What a started agent runs when it is known to differ from the model or effort its start asked for, said for its chat; null
* when it runs them or cannot tell (no model reported, an effort read as auto). Its start never fails over this. */
function otherThanAsked(asked: { model?: string; effort?: string }, ran: { model: string | null; effort: string | null }): string | null {
if (!asked.model) return null
const effortKnown = !!ran.effort && ran.effort !== 'auto' && ran.effort !== 'default'
const modelDiffers = !!ran.model && family(ran.model) !== family(asked.model)
const effortDiffers = effortKnown && !!asked.effort && ran.effort !== asked.effort
if (!modelDiffers && !effortDiffers) return null
const wanted = asked.effort ? `${asked.model} at ${asked.effort}` : asked.model
const runs = [ran.model ?? 'its engine\u2019s own model', ...(effortKnown ? [`at ${ran.effort}`] : [])].join(' ')
return `It asked for ${wanted} and runs ${runs} there.`
}
/** Its start failed with [reason]: the project says why and waits for its person to name a machine again. The line its
* conversation shows; null for a start that is no longer the project's. */
export function leadStartFailed(state: SuperTabState, start: AgentStart, reason: string): string | null {
const placement = placementOf(state, start)
if (!placement) return null
delete placement.startId
// Every reader of the project reads its placement: the reason a group member may read, never the host's own words, which
// can name a folder on the machine or a token problem (startFailure.ts). Its asker reads those on the start.
Object.assign(placement, { status: 'failed', reason: publicReason(reason) })
return failureNotice(start.request.name, reason)
}
/** How long a person's message in their Personal Swarm's project chat with no Lead waits for its Lead (task #2633, Huy 11-04):
* one sent longer before the Lead joins is not delivered to it. */
export const LEAD_WAIT_MS = 30 * 60_000
/** At most this many messages wait for a project's Lead, the newest. */
export const MAX_LEAD_WAITING = 20
/** How long one Desktop's claim to start a project's Lead (lead.claim) holds off another machine's: past it, that start is
* taken as lost. A native start takes a few minutes at most, an engine's install included. */
export const LEAD_CLAIM_MS = 10 * 60_000
/** Records message [id] as waiting for [project]'s Lead, dropping what waited too long, keeping the newest. */
export function leadWaits(project: SwarmProject, id: string, now: number): void {
project.leadWaiting = [...(project.leadWaiting ?? []).filter(w => now - w.at < LEAD_WAIT_MS), { id, at: now }].slice(-MAX_LEAD_WAITING)
}
/** [project]'s Lead [agentId] joined its chat: the messages its person sent there while it had none are delivered to it, as a
* Buddy's waiting messages are (store.ts writeLateDeliveries checks each is its person's own row in that chat), and what waited
* and the claim end. */
export function leadArrived(state: SuperTabState, project: SwarmProject, agentId: string, now: number) {
const waiting = (project.leadWaiting ?? []).filter(w => now - w.at < LEAD_WAIT_MS)
delete project.leadWaiting
delete project.leadClaim
const owner = state.people.find(p => p.id === project.ownerId)
if (!owner) return []
return waiting.map(w => ({ messageId: w.id, conversationId: project.leadConversationId, agentId, lead: true as const,
author: { kind: 'person' as const, id: owner.id, generation: owner.generation } }))
}