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
/**
* The Swarm hands the next task to a free project worker by itself (#3592 extends #3400's crew dispatch). What it decides
* is here, from the state alone: each task's lane, who is free, what
* each free member gets, the two clocks and the capacity line. The store's pass (store.ts dispatchCrew) sends each pick
* through work.assign, whose own write refuses a second assignment.
*/
import { askedByAnother } from './members.js'
import { SEED_RULES, type MachineRule, type ProjectRules } from './policy.js'
import { firstMachines, isReview, machineRuleRefusal } from './machineRules.js'
import { isBuddy } from './buddies.js'
import { sessionClosed } from './closedAgents.js'
import { activeWork, handed, occupiesAgent, reviewsWanted, type Agent, type Assignment, type Conversation, type SuperTabState } from './model.js'
import { agentProjectId, NO_PROJECT, onTeamAccount, projectOf, projectsOf, regularMayWorkIn } from './projects.js'
import { barredFromTeamWritten } from './teamWritten.js'
import { digestOf, localNow } from './digest.js'
import { DEFAULT_TIME_ZONE } from './costs/reflection.js'
import { queueOrder, queueSiblings } from './taskQueue.js'
import { unavailableReason } from './liveness.js'
import { FAILED, type PullRequestWatch } from './pullRequestEvents.js'
import { modelMatches } from './rules.js'
import { roleNameOf } from './instructions.js'
import { stepCandidates } from './reviewerPick.js'
import { ownMerge } from './mergedTasks.js'
const HOUR_MS = 3_600_000
/** A lane of work and the repository paths it owns: the project rules record's `lanes` entry (#3393), the same shape. */
export interface Lane { name: string; owns: readonly string[] }
/** The validated dispatch policy of one project; the default is only for legacy pure callers. */
export interface DispatchRules extends Readonly<ProjectRules['dispatch']> { readonly lanes: readonly Lane[]; readonly machines: readonly MachineRule[] }
export const dispatchRules = (rules: ProjectRules): DispatchRules => ({ ...rules.dispatch, lanes: rules.lanes, machines: rules.machines ?? [] })
/** Null holds only this project's configurable clocks and dispatch until its rules can be repaired/read. */
export type DispatchLookup = (projectId: string) => DispatchRules | null
export const DISPATCH_RULES: DispatchRules = Object.freeze(dispatchRules(SEED_RULES))
/** The lane [name] means, matched in any case, as the table writes it; undefined when the table has none by that name. */
export function laneNamed(lanes: readonly Lane[], name: string): string | undefined {
return lanes.find(lane => lane.name.toLowerCase() === name.trim().toLowerCase())?.name
}
/** Stores [group]'s hand-out lane, when it is a task (not a chat, a step or a private chat), after its paths or lane changed:
* readers copy it (read/views.ts groupView), no read computes it. */
export function stampLane(group: Conversation, lanes: readonly Lane[] = DISPATCH_RULES.lanes): void {
if (group.task && !group.reviewOf && !group.kind && !group.audience) group.handOutLane = laneOf(group, lanes)
else delete group.handOutLane
}
/** "a, b or c": the lane names as a refusal lists them. */
export function spokenList(names: readonly string[]): string {
return names.length <= 1 ? names.join('') : `${names.slice(0, -1).join(', ')} or ${names.at(-1)}`
}
/** Whether [path] lies under [area]: an area ending in '/' is a folder, any other names one path and what is under it. */
const under = (path: string, area: string): boolean => {
const folder = area.endsWith('/') ? area : `${area}/`
return path === area || path.startsWith(folder)
}
/** The lane [group]'s task is handed out in: the one its PM or a person set (work.lane), else the lane owning most of its
* owned paths, a tie going to the table's first; null when no lane owns any of them. */
export function laneOf(group: Pick<Conversation, 'lane' | 'task'>, lanes: readonly Lane[]): string | null {
if (group.lane) return laneNamed(lanes, group.lane) ?? null
let best: string | null = null, most = 0
for (const lane of lanes) {
const count = (group.task?.owns ?? []).filter(path => lane.owns.some(area => under(path.replace(/^\.?\//, ''), area))).length
if (count > most) { best = lane.name; most = count }
}
return best
}
/** Configured time in a progress notice, without rounding a project's threshold. */
const duration = (ms: number): string => {
const [value, unit] = ms % HOUR_MS === 0 ? [ms / HOUR_MS, 'hour'] : ms % 60_000 === 0 ? [ms / 60_000, 'minute'] : [ms / 1000, 'second']
return `${value} ${unit}${value === 1 ? '' : 's'}`
}
export const returnReason = (lane: string | null, rules: DispatchRules = DISPATCH_RULES): string =>
`no progress for ${duration(rules.returnAfterMs)}: back in the ${lane ?? 'project'} lane`
export const nudgeLine = (lane: string | null, rules: DispatchRules = DISPATCH_RULES): string =>
`No progress on this task for ${duration(rules.nudgeAfterMs)}. Post where it stands, or set it blocked with why; at ${duration(rules.returnAfterMs)} it goes back to the ${lane ?? 'project'} lane.`
/** The progress clocks on [assignment] of [group], held by any project worker (liveness.ts): from its own last progress
* (its assignment, status, check or post: `progressAt`), only while working. `nudge` after `nudgeAfterMs`, once
* per spell of quiet; `return` after `returnAfterMs`. Waiting on a person, blocked or handed: no clock. */
export function crewClock(_group: Conversation, _worker: Agent, assignment: Assignment, now: number, rules: DispatchRules): 'nudge' | 'return' | null {
const since = assignment.progressAt
if (assignment.status !== 'working' || since === undefined) return null
if (now - since >= rules.returnAfterMs) return 'return'
return now - since >= rules.nudgeAfterMs && !(assignment.nudgedAt !== undefined && assignment.nudgedAt >= since) ? 'nudge' : null
}
/** Moving off a failing machine (task #3398, crewMove.ts): work.assign refuses it until the move lands. Read without a type
* until #3398 declares it, as #3397 does. */
const moving = (agent: Agent): boolean => !!(agent as { movedTo?: unknown }).movedTo
/** Asleep (task #3398, crewSleep.ts): its session closed on purpose; work.assign wakes it in the same write. */
const asleep = (agent: Agent): boolean => !!(agent as { asleep?: unknown }).asleep
/** The workers of [projectId] free for a task (the name is kept for callers): not its PM, not a Buddy, not stopping or moving, a session not
* closed unless asleep, no launch still pending) with nothing in their hands and fewer than `maxHanded` handed tasks;
* fewest handed first, then as the roster lists them. */
export function freeCrew(state: SuperTabState, projectId: string, rules: DispatchRules, now: number): Agent[] {
const project = projectOf(state, projectId)
const leads = new Set(state.conversations.flatMap(c => c.leadId ? [c.leadId] : []))
const handedBy = new Map<string, number>(), busy = new Set<string>()
for (const group of state.conversations) {
const holder = group.assignment?.agentId
if (!holder) continue
if (occupiesAgent(group)) busy.add(holder)
else if (activeWork(group) && handed(group)) handedBy.set(holder, (handedBy.get(holder) ?? 0) + 1)
}
// A PM in a Harness Team account assigns only agents of its own machine or another Team account (store.ts teamCommand,
// security review 2 of #2089): the main account stays out of its reach.
const leadId = state.conversations.find(c => c.id === project.leadConversationId)?.leadId
const lead = leadId ? state.agents.find(a => a.id === leadId) : undefined
const reachable = (agent: Agent) => !lead || !onTeamAccount(state, lead) || agent.machineId === lead.machineId || onTeamAccount(state, agent)
const launching = (agent: Agent) => !!state.starts?.some(s => !s.poolSettled && s.poolGeneration && s.request.machineId === agent.machineId && s.harnessId === agent.harnessId)
// An idle Regular agent is in no project until a task places it (task #4116): it is free in each project it may work in, so a
// task its PM routed to it is handed over (task #4218). The assignment checks the same again (projects.ts sameProject).
const inProject = (agent: Agent) => {
const own = agentProjectId(state, agent)
return own === projectId || (!!agent.regular && own === NO_PROJECT && regularMayWorkIn(state, agent, project))
}
return state.agents
.filter(agent => inProject(agent) && !leads.has(agent.id) && !isBuddy(agent)
// Nor a Team account's, which takes no new work (task #4120).
&& agent.workDecision !== 'stop' && !onTeamAccount(state, agent) && !moving(agent) && (asleep(agent) || !sessionClosed(state, agent, now)) && !launching(agent)
&& !busy.has(agent.id) && (handedBy.get(agent.id) ?? 0) < rules.maxHanded && reachable(agent)
// A member its machine or engine cannot serve now would lose the task at once (liveness.ts): until that clears.
&& !unavailableReason(state, agent, now, asleep(agent)))
.map((agent, at) => ({ agent, at, handed: handedBy.get(agent.id) ?? 0 }))
.sort((a, b) => a.handed - b.handed || a.at - b.at)
.map(entry => entry.agent)
}
/** The open tasks of [projectId] a worker may be handed, plus lost review/test steps whose build is still active: never a
* chat or private chat. A brief, no active work, not finished, whose not-before day has come; P0 first, then the
* project's Next up. */
export function openTasks(state: SuperTabState, projectId: string, now: number): Conversation[] {
const project = projectOf(state, projectId)
// The day people meant: the project's own (its digest's time zone), Vietnam's without one, as the PM schedule reads it.
const today = localNow(digestOf(project)?.timeZone ?? DEFAULT_TIME_ZONE, now).date
const lostSteps = state.conversations.filter(group => {
if (group.archived || group.kind || group.audience || !group.reviewOf || group.assignment?.status !== 'lost' || (group.projectId ?? 'lead') !== projectId) return false
const task = state.conversations.find(g => g.id === group.reviewOf)
// Never a step of a task whose own merge is recorded (mergedTasks.ts, task #4032): nothing is left to check.
return !!task && !task.archived && (task.projectId ?? 'lead') === projectId && activeWork(task) && !ownMerge(task)
})
// Nor a task whose own merge is recorded: finished work, which the sweep sets done (task #4032).
const open = [...queueSiblings(state, project).filter(group => !ownMerge(group)), ...lostSteps].filter(group => (group.task || group.brief.trim())
&& !activeWork(group) && !['done', 'cancelled'].includes(group.assignment?.status ?? '') && !(group.notBefore && group.notBefore > today)
// Paused by someone who steers its project (boardRights.ts, task #3819): until resumed.
&& !group.paused)
const ordered = queueOrder(open)
return [...ordered.filter(g => g.priority === 'P0'), ...ordered.filter(g => g.priority !== 'P0')]
}
/** The lanes an Engineer takes: its crew lane or last known task area, otherwise any project area. */
function takes(state: SuperTabState, member: Agent, rules: DispatchRules): (lane: string | null) => boolean {
if (!/^(engineer|builder)$/i.test((member.crew?.role ?? roleNameOf(state, member)).trim())) return () => false
// Ordinary workers have no crew lane: retain the area of their last task when the server knows it.
const previous = member.crew ? undefined : state.conversations.findLast(g => g.task && !g.reviewOf && g.assignment?.agentId === member.id)
const own = member.crew?.lane ?? (previous ? laneOf(previous, rules.lanes) : null)
return own ? lane => lane !== null && laneNamed(rules.lanes, own) === lane : () => true
}
/** Whether [group] is big, hard or risky work, which Routing puts on Opus or Astra: the PM marked it strong, or it wants two reviews
* and the PM did not mark it standard (#3576). */
const needsStrongModel = (group: Conversation): boolean => group.task?.strength === 'strong' || (group.task?.strength === undefined && reviewsWanted(group.task) === 2)
/** Whether [member] runs a model Routing allows for big or risky work: Opus at high effort or above, or Astra at xhigh (an effort
* not set is not known to be either). */
const onStrongModel = (member: Agent): boolean => {
const effort = (member.configuration.effort ?? '').toLowerCase(), model = member.configuration.model
return (modelMatches('opus', model) && ['high', 'xhigh', 'max'].includes(effort)) || (modelMatches('astra', model) && ['xhigh', 'max'].includes(effort))
}
/** The tasks [member] could be handed now, best first: those pinned to it (oldest pin first), then its lane's open tasks.
* A task it just lost to the 3-hour clock is not offered to it. */
export function candidatesFor(state: SuperTabState, member: Agent, rules: DispatchRules, now: number, open: Conversation[],
skip: Skip = () => false) {
const lostByIt = (group: Conversation) => group.lostAttempt?.agentId === member.id && group.assignment?.status === 'lost'
const pinned = open.filter(g => pinOf(g)?.agentId === member.id).sort((a, b) => pinOf(a)!.at - pinOf(b)!.at)
const members = new Set(state.agents.filter(a => a.workDecision !== 'stop' && !moving(a)).map(a => a.id))
const acceptsLane = takes(state, member, rules)
// The project's machine rules (machineRules.ts): what its machine refuses now, it is not handed, pinned or not.
const refused = (review: boolean) => !!machineRuleRefusal(rules.machines, { machineId: member.machineId, engine: member.configuration.engine, review }, now)
const refusesWork = refused(false), refusesReview = refused(true)
// A step named for an OS goes to an agent of that OS only (task #3926), as it went when first opened.
const steps = open.filter(g => g.reviewOf && !lostByIt(g) && !(refusesReview && isReview(g))).filter(step => stepCandidates(state, step, now).some(a => a.id === member.id))
const lane = open.filter(g => (!g.lane || !!laneNamed(rules.lanes, g.lane)) && !g.reviewOf && !pinned.includes(g) && !(pinOf(g) && members.has(pinOf(g)!.agentId)) && !lostByIt(g)
// Ordinary workers recover work; new tasks still need the PM's route or a standing crew lane.
&& (member.crew || (g.assignment?.status === 'lost' && g.lostAttempt))
// Another person's ask goes to their own Member (members.ts, task #4697), never to this agent on its own.
&& !askedByAnother(state, g, member)
&& acceptsLane(laneOf(g, rules.lanes)) && (!needsStrongModel(g) || onStrongModel(member)))
// Team-written code goes to Team accounts only (teamWritten.ts); a pick refused this round is not sent again (store.ts).
const allowed = (group: Conversation) => (group.reviewOf ? steps.includes(group) : !refusesWork) && !barredFromTeamWritten(state, group, member) && !skip(group.id, member.id)
return [...pinned.filter(allowed).map(group => ({ group, why: 'pin' as const })),
...[...steps.filter(g => !pinned.includes(g)), ...lane].filter(allowed).map(group => ({ group, why: 'lane' as const }))]
}
/** A pin never sends a lost task straight back to the failed agent; another free worker takes it. */
const pinOf = (group: Conversation): Conversation['pin'] =>
group.pin && !(group.assignment?.status === 'lost' && group.lostAttempt?.agentId === group.pin.agentId) ? group.pin : undefined
/** A pick the caller leaves out: one whose work.assign was refused this round (store.ts dispatchCrew). */
export type Skip = (conversationId: string, agentId: string) => boolean
/** The round a task is in, for its dispatch's operation id and refusal memory: its last assignment's, kept across a
* redefinition (its run ledger), so a new round never replays the last one's receipt. */
export const roundOf = (group: Conversation): string => group.ledger?.runs?.at(-1)?.assignmentId ?? group.assignment?.id ?? 'first'
/** One assignment the dispatch makes. */
export interface DispatchPick { conversationId: string; agentId: string; why: 'pin' | 'lane'; lane: string | null }
/** What each free worker of [projectId] gets in one pass: its first candidate no other worker took first. Nothing while
* the Swarm is paused. */
export function dispatchPlan(state: SuperTabState, projectId: string, rules: DispatchRules, now: number, skip: Skip = () => false): DispatchPick[] {
if (state.paused) return []
const open = openTasks(state, projectId, now), taken = new Set<string>(), picks: DispatchPick[] = []
const free = freeCrew(state, projectId, rules, now)
const candidates = new Map(free.map(member => [member.id, candidatesFor(state, member, rules, now, open, skip)]))
// A lane's work goes first to its machines (machineRules.ts firstMachines): a task a free member there could take waits for
// it; a member elsewhere takes it only when none there can.
const heldFor = new Map<string, string[]>()
for (const member of free) for (const { group, why } of candidates.get(member.id)!) {
if (why === 'lane' && firstMachines(rules.machines, laneOf(group, rules.lanes)).includes(member.machineId)) heldFor.set(group.id, [...heldFor.get(group.id) ?? [], member.id])
}
for (const member of free) {
const next = candidates.get(member.id)!.find(c => !taken.has(c.group.id) && (c.why === 'pin' || !heldFor.has(c.group.id) || heldFor.get(c.group.id)!.includes(member.id)))
if (!next) continue
taken.add(next.group.id)
picks.push({ conversationId: next.group.id, agentId: member.id, why: next.why, lane: laneOf(next.group, rules.lanes) })
}
return picks
}
/** One lane's line of the capacity read: its waiting tasks (open, nobody's, in hand-out order), how many of its tasks are in
* someone's hands, and since when the longest-waiting one has waited (null when no wait was recorded). */
export interface LaneCapacity { lane: string; waiting: number; busy: number; oldestAt: number | null }
/** When [group] began waiting with nobody holding it: as its liveness recorded, else when its last attempt was lost. */
const waitingSince = (group: Conversation): number | undefined =>
group.liveness?.state === 'orphaned' ? group.liveness.since : group.assignment?.lost?.at
/** [projectId]'s lanes as the dispatch sees them, in the table's order, each with work waiting or in hand. A time, not an age,
* so the read's summary does not move as the clock does (read/derivedEtag.ts). */
export function laneCapacity(state: SuperTabState, projectId: string, rules: DispatchRules, now = Date.now()): LaneCapacity[] {
const open = openTasks(state, projectId, now)
const project = projectOf(state, projectId)
const busy = queueSiblings(state, project).filter(occupiesAgent)
return rules.lanes.flatMap(({ name }) => {
const waiting = open.filter(g => laneOf(g, rules.lanes) === name)
const inHand = busy.filter(g => laneOf(g, rules.lanes) === name).length
if (!waiting.length && !inHand) return []
const since = waiting.map(waitingSince).filter((t): t is number => t !== undefined)
return [{ lane: name, waiting: waiting.length, busy: inHand, oldestAt: since.length ? Math.min(...since) : null }]
})
}
/** "Desktop: 6 waiting, 2 busy, oldest 2 h" (under an hour in minutes; no oldest when none was recorded). */
export function capacityLine(c: LaneCapacity, now: number): string {
const age = c.oldestAt === null ? null : Math.max(0, now - c.oldestAt)
const oldest = age === null ? '' : age >= HOUR_MS ? `, oldest ${Math.floor(age / HOUR_MS)} h` : `, oldest ${Math.floor(age / 60_000)} min`
return `${c.lane}: ${c.waiting} waiting, ${c.busy} busy${oldest}`
}
/** What [watch] says its task's builder should come back for: a merge conflict, or a failed check run at its head. */
export function pullRequestPin(watch: Pick<PullRequestWatch, 'mergeable' | 'checkRuns'>): 'ci' | 'conflict' | null {
if (watch.mergeable === false) return 'conflict'
return watch.checkRuns.some(run => !!run.conclusion && FAILED.has(run.conclusion)) ? 'ci' : null
}
/** Pins [group], a task with no active work, to its last attempt's agent for [why]: the dispatch hands it to that member
* first, while it is available (candidatesFor). A pin already there keeps its time; active work is never pinned. */
export function pinBuilder(group: Conversation, why: NonNullable<Conversation['pin']>['why'], now: number): void {
// Its last round's agent: a stopped round's, not an older lost one's.
const builder = group.assignment?.agentId ?? group.lostAttempt?.agentId
if (!builder || activeWork(group) || group.pin) return
group.pin = { agentId: builder, why, at: now }
}