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.

18.2 KB
Raw Blame
/** 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 } }))
}