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
import { checksOpenWork, isStep, taskEnded } from './steps.js'
import { isBuddy, isSwarmBuddy } from './buddies.js'
import { buddyEngineChat } from './buddyEngine.js'
import { isCrew } from './crew.js'
import { expiredModelRequests, unservedBuddyModels } from './buddyModel.js'
import { agentDisplayName } from './agentNames.js'
import { githubRepository, type GitHubRepository } from '../github/repository.js'
import { activeWork, appendPullRequestUrls, stableId, type Actor, type Agent, type Conversation, type MessageDraft, type SuperTabState } from './model.js'
import { agentProjectId, canReadGroup, groupProject, ledProject, projectsOf } from './projects.js'
import { toLead } from './terminal.js'
import { roleNameOf } from './instructions.js'
// Dee, 2026-11-06: the server handles routine idle decisions. After 15 minutes it requests a host-confirmed stop for an
// idle non-crew Engineer and keeps Reviewers/Testers; standing crew use their existing sleep/wake keeper. Tidying governs
// auto-archive only. The PM's notice is information, not work it has to carry out.
/** How long an agent has no open task before its coordinator is told. */
export const IDLE_NOTICE_MS = 15 * 60_000
/** How long a PM's switch request waits for its machine to claim it (agent.switchClaim) before it is dropped. */
export const SWITCH_UNCLAIMED_MS = 2 * 60_000
const time = (value: string | undefined) => value === undefined ? undefined : Date.parse(value)
/** The loaded groups an agent belongs to or worked in. */
export const groupsOf = (state: SuperTabState, target: Agent): Conversation[] =>
state.conversations.filter(c => c.agentIds.includes(target.id) || c.assignment?.agentId === target.id)
/** When the agent last had anything to do: its start, its coordinator's keep, its own progress, or a message in one of its
* groups. An agent the Swarm started that never had an assignment (no task of its own, never lost one) only sits in its
* groups, whose messages are about others' work: it is idle from its start or keep (Swarm autonomous-harness, 2026-10-29:
* one sat idle 18+ minutes, its time renewed by every message in a busy chat). One a person added by hand has no start of
* record, so its groups' messages count, from the one it joined in. A person talking with it counts either way: an agent
* a person is chatting with is never idle (hieule, 11-06, task #3816). Undefined when nothing tells when. */
export function idleSince(target: Agent, groups: Conversation[]): number | undefined {
const worked = !!target.lostTask || groups.some(g => g.assignment?.agentId === target.id) || !target.startedSession
const seen = [time(target.startedSession?.createdAt), target.keptAt, ...groups.flatMap(g => [g.talkedAt?.[target.id]?.person, g.talkedAt?.[target.id]?.answer]),
...(worked ? groups : []).flatMap(g => [time(g.lastActivityAt),
...g.assignment?.agentId === target.id ? [g.assignment.progressAt, g.assignment.lost?.at] : []])]
.filter((t): t is number => t !== undefined && Number.isFinite(t))
return seen.length ? Math.max(...seen) : undefined
}
/** An agent whose task a usage limit took waits to take it back (work.resume) until that task is resumed, handed on or
* cancelled, however late the resume comes after the reset (review of #1807). A task not loaded is taken as waiting. */
function waitingToResume(state: SuperTabState, target: Agent): boolean {
const lost = target.lostTask
if (!lost?.resumeAt) return false
const group = state.conversations.find(c => c.id === lost.conversationId)
return !group || (group.assignment?.id === lost.assignmentId && group.assignment.status === 'lost')
}
/**
* Tells the project's coordinator, once per idle spell, of every agent of the project with no open task for IDLE_NOTICE_MS:
* not a Buddy (it waits for its person), crew (it stands by between tasks, crew.ts) nor the coordinator, not stopping nor kept (a keep answers the notice until the agent
* is assigned again, which clears it, and finishes that work), with no delivery waiting for it (`busy`), not
* waiting to resume after a usage limit, and in no loaded group with active work. One row in the coordinator's chat, to it
* alone (model.ts NOTICE_READERS `idle`); the agent's `idleNoticedAt` records the spell, so the next poll says nothing until
* new activity starts another. It also records host-confirmed idle stops or role retention. Run by the backend's time
* checks, which know what deliveries wait even when the PM is hung.
*/
export function idleNotices(state: SuperTabState, projectId: string, now: number, busy: ReadonlySet<string>): MessageDraft[] {
if (state.paused) return []
const project = projectsOf(state).find(p => p.id === projectId)
const coordinatorId = project && state.conversations.find(c => c.id === project.leadConversationId)?.leadId
const coordinator = coordinatorId ? state.agents.find(a => a.id === coordinatorId) : undefined
if (!project || !coordinator) return []
const rows: MessageDraft[] = []
for (const target of state.agents) {
if (target.id === coordinator.id || isBuddy(target) || isCrew(target) || target.workDecision === 'stop' || target.workDecision === 'keep' || busy.has(target.id)
|| agentProjectId(state, target) !== projectId || waitingToResume(state, target)) continue
const groups = groupsOf(state, target)
// Handed work leaves an Engineer free for dispatch, but review/CI can return work to it. Its host cannot confirm an
// agent.remove while it owns active work, so it must not receive an idle stop either.
if (groups.some(activeWork)) continue
// A Reviewer or Tester, by what it worked on: the instructions keep it while the work it checked is open (Ken,
// 2026-11-02: "Tester has had no open task" twice in 8 minutes, nothing for the PM to do), and no longer.
if (checksOpenWork(state, groups, target.id)) continue
const since = idleSince(target, groups)
if (since === undefined || now - since < IDLE_NOTICE_MS || target.idleNoticedAt === since) continue
target.idleNoticedAt = since
const role = roleNameOf(state, target)
if (/review|test|guide|integrator/i.test(role) || /^(guide|integrator)\d*$/i.test(target.name)) {
target.workDecision = 'keep'
target.keptAt = now
continue
}
if (target.startedSession && /^(engineer|builder)$/i.test(role.trim())) {
target.idleStop = { previous: target.workDecision ?? null }
target.releaseId = stableId('idle-stop', target.id, String(since))
target.workDecision = 'stop'
}
rows.push(...toLead(state, target, { id: stableId('idle', target.id, String(since)), conversationId: project.leadConversationId, replyTo: null,
recipients: [], author: { kind: 'agent', id: coordinator.id, name: coordinator.name, displayName: agentDisplayName(state.agents, coordinator.id),
membershipGeneration: coordinator.membershipGeneration },
text: `${target.displayName ?? target.name} has had no open task for 15 minutes.`, source: { kind: 'idle', agentId: target.id } }))
}
return rows
}
/** Whether a switch request ran out: nobody claimed it in 2 minutes, or its claim's lease lapsed. */
export const switchExpired = (request: NonNullable<Agent['switchRequest']>, now: number): boolean =>
now >= (request.claimedUntil === undefined ? Date.parse(request.at) + SWITCH_UNCLAIMED_MS : Date.parse(request.claimedUntil))
/** A switch request that ran out is dropped (the PM keeps its engine), and its project chat says so once: the host that never
* answered cannot. Run by the liveness sweep, which any machine's report drives, as the PM's own host may be the one down. */
export function staleSwitches(state: SuperTabState, now: number): MessageDraft[] {
const rows: MessageDraft[] = []
for (const pm of state.agents) {
const request = pm.switchRequest, project = request && ledProject(state, pm.id)
const chat = isSwarmBuddy(pm) && !pm.buddySession ? buddyEngineChat(state, pm) : project?.leadConversationId
if (!request || !chat) continue
if (!switchExpired(request, now)) continue
delete pm.switchRequest
rows.push({ id: stableId('switch-stale', pm.id, request.id), conversationId: chat, replyTo: null, recipients: [],
author: { kind: 'agent', id: pm.id, name: pm.name, displayName: agentDisplayName(state.agents, pm.id), membershipGeneration: pm.membershipGeneration },
text: `Couldn't switch ${isBuddy(pm) ? 'your Buddy' : 'the PM'}: its machine did not answer.`, source: { kind: 'switch', agentId: pm.id } })
}
return rows
}
export { BUDDY_MODEL_GONE_MS, BUDDY_MODEL_LEASE_MS } from './buddyModel.js'
/** A Buddy's model switch its machine never reported is dropped (the Buddy stays where it was), and its owner's Buddy chat
* says so once. Run by the liveness sweep, as staleSwitches is: the Buddy's own machine may be the one down. */
export function staleModelRequests(state: SuperTabState, now: number): MessageDraft[] {
const drafts = expiredModelRequests(state, now).map(({ buddy, requestId, conversationId, text, machines }): MessageDraft => ({
id: stableId('buddy-model-stale', buddy.id, requestId), conversationId, replyTo: null, recipients: [], text,
source: { kind: 'system', ...(machines.length ? { machines } : {}) },
author: { kind: 'agent', id: buddy.id, name: buddy.name, displayName: agentDisplayName(state.agents, buddy.id), membershipGeneration: buddy.membershipGeneration } }))
// After the expiry, so a Buddy whose machine never answered one request home is asked again on the next sweep.
unservedBuddyModels(state, now, buddy => stableId('buddy-model-gone', buddy.id, String(now)))
return drafts
}
/** A linked task (`reviewOf`) the Swarm does not archive by itself: none of its checks carries evidence, nobody cancelled it,
* and the task it links to is still going. Once that task is done or cancelled the link is moot. By hand any agent of the
* project or a person archives it (project instructions, phase 4). */
export const linkPending = (state: SuperTabState, linked: Conversation): boolean => {
if (!linked.reviewOf || linked.assignment?.status === 'cancelled' || linked.checks.some(c => c.evidence)) return false
const target = state.conversations.find(c => c.id === linked.reviewOf)
return !!target && activeWork(target)
}
/** How long a finished group stays open after its last message: an archived group refuses posts, and the Lead still talks
* to its worker for a while after the task ends (ruling in the plan, 2026-10-27). */
export const ARCHIVE_QUIET_MS = 30 * 60_000
/** Whether a group may archive by itself, as far as the Swarm alone can tell: its task done or cancelled, quiet for
* ARCHIVE_QUIET_MS, not a linked task still owing its verdict (linkPending), not a step whose task is still open
* (steps.ts taskEnded), and not a Lead conversation, a private chat with people or the Leads conversation. Its pull requests and decisions are checked by the caller (archive.ts). */
export function archivable(state: SuperTabState, group: Conversation, now: number): boolean {
if (state.tidy === false || group.archived || group.kind || group.audience) return false
if (projectsOf(state).some(p => p.leadConversationId === group.id)) return false
if (!['done', 'cancelled'].includes(group.assignment?.status ?? '') || linkPending(state, group)) return false
if (isStep(group) && !taskEnded(state, group)) return false
const last = time(group.lastActivityAt)
return last !== undefined && now - last >= ARCHIVE_QUIET_MS
}
/** Work that ended without finishing: only a cancel with a reason closes it, never an archive alone (#558). */
export const unfinishedWork = (group: Conversation): boolean => ['lost', 'stopped'].includes(group.assignment?.status ?? '')
/** Who hears that a group archives without shipping: the person who asked for its cancelled task, unless they archive it
* themselves or can no longer read it (#558). */
export function cancelledTags(state: SuperTabState, group: Conversation, actor?: Actor): string[] {
if (group.assignment?.status !== 'cancelled' || !group.requesterId) return []
if (actor?.kind === 'person' && actor.userId === group.requesterId) return []
const requester = state.people.find(p => p.id === group.requesterId)
return requester && canReadGroup(state, { kind: 'person', userId: requester.id, email: requester.email }, group) ? [requester.id] : []
}
/** Why a cancelled task ended, as its cancel recorded it, without the final full stop. */
export const cancelReason = (group: Conversation): string => (group.assignment?.result ?? '').replace(/[.\s]+$/, '')
/** "PR #1875", as a Lead's cancel or a builder's result names a pull request without its link. */
const PR_NUMBER = /\bPR #([1-9][0-9]{0,8})\b/gi
/** A repository's name, or owner/name, as a result writes it next to "PR #N": "from autonomous-harness PR #2716", "PR #12 in acme/tool". */
const REPO_NAME = '([A-Za-z0-9](?:[\\w.-]*\\w)?(?:/[A-Za-z0-9](?:[\\w.-]*\\w)?)?)'
const NAME_BEFORE = new RegExp(`(?:^|[\\s(])(from\\s+)?${REPO_NAME}\\s+$`, 'i'), NAME_AFTER = new RegExp(`^\\s+(?:in|of)\\s+${REPO_NAME}`, 'i')
/** English compounds a result writes before "PR", which look like a repository's name and are none. */
const COMPOUND = /^(?:follow-(?:up|on)|(?:re|co|pre|non|one)-\w+)$/i
/** Whether [name] next to a "PR #N" plainly names a repository other than the project's. Dropping one of its own numbers
* archives a group while that pull request is open (#558); reading another's as its own waits at most until that number
* closes here or is not found. So "Desktop/CLI PR #12", "test-only PR #12" and "PR #12 in docs/plans" stay its own (review
* of #2895): a name counts after "from" ("Ported from autonomous-harness PR #2716"), or as owner/name of the project's owner. */
function otherRepository(name: string | undefined, from: boolean, repository: GitHubRepository | null): boolean {
if (!name) return false
const [owner, repo] = name.toLowerCase().split('/')
if (repo === undefined) return from && /^[a-z]/.test(owner!) && /[._-]/.test(owner!) && !COMPOUND.test(owner!) && owner !== repository?.name.toLowerCase()
if (name.toLowerCase() === repository?.fullName.toLowerCase()) return false
return from || owner === repository?.owner.toLowerCase()
}
/** How a pull request an archive waits on ended: merged, closed, or missing, a number GitHub knows no pull request by in
* that repository (another repository's, #2602). */
export type SettledPullRequest = 'merged' | 'closed' | 'missing'
/** The pull requests a group's archive waits on: those it links, and those its result and check evidence name, a "PR #N"
* read in its project's repository. A cancel saying "Handed off as PR #1875" linked nothing, so the group archived while
* that PR was open (#558). A number another repository's name sits next to is that repository's, and never waited on
* ("Ported from autonomous-harness PR #2716" held a task open forever, #2602). Null when it names a number with no GitHub
* repository to read it in: it stays open. */
export function archiveWaitsFor(group: Conversation, repositoryUrl: string | null | undefined): string[] | null {
const texts = [group.assignment?.result, ...group.checks.map(check => check.evidence)]
const named = { pullRequestUrls: [...group.pullRequestUrls ?? []] } as Conversation
appendPullRequestUrls(named, texts)
const repository = githubRepository(repositoryUrl)
const numbers = texts.flatMap(text => [...(text ?? '').matchAll(PR_NUMBER)]
.filter(match => {
const before = NAME_BEFORE.exec(text!.slice(0, match.index))
return !otherRepository(before?.[2], !!before?.[1], repository)
&& !otherRepository(NAME_AFTER.exec(text!.slice(match.index + match[0].length))?.[1], false, repository)
})
.map(match => match[1]!))
if (!numbers.length) return named.pullRequestUrls!
if (!repository) return null
return [...new Set([...named.pullRequestUrls!, ...numbers.map(n => `https://github.com/${repository.fullName}/pull/${n}`)])]
}
/** The one quiet line an archived group gets, to nobody, written as its project's Lead; none when the project has no Lead.
* A cancelled task's requester is tagged in it (cancelledTags). */
export function archiveLine(state: SuperTabState, group: Conversation, now: number): MessageDraft | null {
const prs = group.pullRequestUrls?.length ? ' and its pull requests are merged or closed' : ''
const mentions = cancelledTags(state, group), reason = mentions.length && cancelReason(group) ? ` (${cancelReason(group)})` : ''
const line = leadLine(state, group, now, `Archived: the work is ${group.assignment!.status}${reason}${prs}.`)
return line && mentions.length ? { ...line, mentions } : line
}
function leadLine(state: SuperTabState, group: Conversation, now: number, text: string): MessageDraft | null {
const leadId = state.conversations.find(c => c.id === groupProject(state, group).leadConversationId)?.leadId
const lead = leadId ? state.agents.find(a => a.id === leadId) : undefined
if (!lead) return null
return { id: stableId('auto-archive', group.id, String(now)), conversationId: group.id, replyTo: null, recipients: [],
author: { kind: 'agent', id: lead.id, name: lead.name, displayName: agentDisplayName(state.agents, lead.id), membershipGeneration: lead.membershipGeneration },
text, source: { kind: 'auto-archive' } }
}
// A review nobody is reviewing closes once the work it reviews needs no Swarm review (Ken, 2026-10-30): 28 of 31 open
// review groups waited for a Reviewer on pull requests already merged, reviewed outside the Swarm or folded into a batch PR.
// A review with no Reviewer has no task to finish or cancel, so `archivable` never matched it.
/** A review group with no active Reviewer: none was ever free, or its Reviewer's task ended. The archive pass reads these
* as it reads finished work (parts/write.ts workFinished). */
export const unattendedReview = (group: Conversation): boolean => !!group.reviewOf && !activeWork(group)
/** The pull requests that decide whether an unattended review still matters: those it links and those of the work it reviews. */
export function reviewPullRequests(state: SuperTabState, review: Conversation): string[] {
const reviewed = state.conversations.find(c => c.id === review.reviewOf)
return [...new Set([...review.pullRequestUrls ?? [], ...reviewed?.pullRequestUrls ?? []])]
}
/** Whether an unattended review may close by itself, as far as the Swarm alone can tell: the work it reviews is done or
* cancelled, it links, or that work links, a pull request, and it has been quiet for ARCHIVE_QUIET_MS. That each of those pull requests is merged or
* closed, and that no decision waits there, the caller checks (archive.ts, store.ts archiveFinished). */
export function reviewClosable(state: SuperTabState, review: Conversation, now: number): boolean {
if (state.tidy === false || review.archived || review.kind || review.audience || !unattendedReview(review)) return false
if (!taskEnded(state, review)) return false
if (projectsOf(state).some(p => p.leadConversationId === review.id)) return false
if (!reviewPullRequests(state, review).length) return false
const last = time(review.lastActivityAt)
return last !== undefined && now - last >= ARCHIVE_QUIET_MS
}
const pullNumber = (url: string) => `#${url.slice(url.lastIndexOf('/') + 1)}`
/** The one quiet line a closed review gets, naming each pull request and how it ended. */
export function reviewCloseLine(state: SuperTabState, review: Conversation, settled: Readonly<Record<string, SettledPullRequest>>, now: number): MessageDraft | null {
const prs = reviewPullRequests(state, review).map(url => `${pullNumber(url)} ${settled[url] === 'missing' ? 'not found' : settled[url]}`).join(', ')
return leadLine(state, review, now, `Closed: ${prs}; no Swarm review is needed now.`)
}