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 read API by parts (docs/design/2026-10-26-swarm-state-parts.md, section 4): the single source of truth for the
* response shapes. Desktop/web (`desktop/lib/super_tabs`) and the CLI (`cli/src/superTabs`) mirror these by hand; announce
* any change to the Lead before it merges.
*
* Every payload below is the `data` of the usual `{ success, data }` envelope. Times are epoch milliseconds; part `data`
* keeps today's ISO strings where today's record has them.
*/
import type { Agent, AgentStart, Conversation, Person, SuperTabState, WorkStatus } from '../model.js'
import type { ContributedMachine } from '../machines.js'
import type { PromptWait } from '../promptWaits.js'
export const READ_FORMAT = 2
export type PartKind = 'head' | 'member' | 'agent' | 'group' | 'machine' | 'start' | 'progress'
/** A live part: the reader's view of one stored record. */
export interface LivePart<T> { key: string; version: number; changedAt: number; data: T }
/** A removed part. It never carries data; a reader receives it only if it could read the part's last data. */
export interface Tombstone { key: string; version: number; changedAt: number; deleted: true }
/** A group that left the active set (archived, or finished and idle 24 h). Fetch it whole with `groups/:id`. */
export interface DormantStub { key: string; version: number; changedAt: number; dormant: true }
export type PartChange<T> = LivePart<T> | Tombstone
export type GroupChange = LivePart<GroupView> | Tombstone | DormantStub
/** The head as a reader sees it: no sharing, overlap alerts, retired number or parked groups; projects, rules and
* invitations filtered (invitations only for the Swarm owner). `autoJoin`: people at the owner's domain join by themselves
* (autoJoin.ts), from the sharing the head holds; who declined is never sent. */
export type HeadView = Pick<SuperTabState, 'version' | 'id' | 'name' | 'project' | 'leadsConversationId' | 'ownerId'
| 'environment' | 'routingPolicy' | 'rules' | 'paused' | 'invitations' | 'localModels' | 'workspaceId' | 'workspaceVisibility' | 'buddies' | 'removedMachines'
| 'autoJoin'> & {
/** How many Buddies each person may have (task #3818): always sent, 5 unless the Swarm's owner set another. An older backend
* sends none, so an app offers several Buddies only where this is present. */
buddyCap: number
/** Fixed columns for the chosen preset (task #3896); an older server omits both, meaning Full. */
projects?: Array<import('../projects.js').SwarmProject & {
process: import('../process.js').ProjectProcess; columns: readonly import('../process.js').BoardColumn[]
}>
}
/** A member's avatar says only `{ kind: 'upload' }` for an upload: its link comes signed in `derived.avatars`. */
export type MemberView = Omit<Person, 'avatar'> & { avatar?: import('../profile.js').AvatarView }
/** The stored agent. Time-based and cross-part values (`downSince`, `limitedUntil`, an awaiting decision, the custom
* role) come only in `derived.agents`, so an agent never changes without a new version. */
export type AgentView = Omit<Agent, 'downNamed' | 'downSince' | 'limitedUntil' | 'roleId' | 'avatar'> & { avatar?: import('../profile.js').AvatarView }
/** A private conversation's audience: the people it is shared with. The project's Lead always reads it too. */
export interface Audience { people: Array<{ id: string; generation: string }> }
/** A conversation with its own message counter (`lastMessageSequence` and message sequences compare within one group).
* `dormant` is set only on a dormant group fetched on demand; `audience` only on a private conversation. */
export type GroupView = Omit<Conversation, 'chatLimits' | 'talkedAt' | 'messageSeq' | 'reportSeq' | 'dormant' | 'lastActivityAt' | 'audience' | 'ledger' | 'proposals'> & {
/** A task's lane, as the crew dispatch hands it out (dispatch.ts laneOf: its PM's, else its owned paths'), null when no
* lane owns its paths; absent on a chat or a step. From the group alone, so a change read's changed tasks keep every lane's
* count whole on the reader's side (task #3400). Absent from an older backend. */
handOutLane?: string | null
/** When it shipped (ms): its first Done; absent until it has. Nothing else of its ledger is sent. */
shippedAt?: number
/** Why a held task is held, or `none` for a hold from before reasons; absent when it is not held (heldReason.ts heldView). */
held?: import('../heldReason.js').HeldView
}
& { messageSeq: number; dormant?: true; audience?: Audience
/** A Buddy chat's owner, in place of its audience (read/views.ts groupView). */
buddyOwnerId?: string }
/** A contribution as `state.machines[]` has it, privacy detail only for its contributor, harness ids cut to what the
* reader can see. Machines without a contribution are never sent. */
export type MachineView = ContributedMachine
export type StartView = AgentStart
export interface ProgressView {
since: number
summarizedFloor: number
summarized: Record<string, number>
requestedFloor: number
requested: Record<string, number>
requestedAt: number | null
requestMessageId?: string
}
/** Values that change without a part changing (time, or several parts). Recomputed in full on every response;
* clients overlay it on the parts. */
export interface Derived {
/** The board's pulse of each project the reader sees (pulse.ts, task #3384), by project id. Absent from an older backend. */
pulse?: Record<string, import('../pulse.js').Pulse>
/** When each component's release may next open, by project id then component (releases.ts nextReleaseAt, task #3827): 0 is now,
* absent one is left to people. Only for the projects the reader sees and that have a release list; the list itself is never
* sent. A time already past is as good as 0: the settle writes a new one each minute it changes. Absent from an older backend. */
releaseTimes?: Record<string, import('../releases.js').ReleaseLedger['nextAt'] & object>
/** Every agent the reader can see. `workDecision` is null when the stored value stands; `roleId` null outside Custom. */
/** `roleName`: the role it goes by (instructions.ts roleNameOf), its stored one or what it is. */
/** `kind`: the reader's Buddy, a PM leading a project, or a Regular agent; `chatId`: the chat its person talks to it in, or null
* (agentKind.ts, task #4116). Absent from an older backend. */
/** `myAgent`: whether it is in the reader's My agents (agentKind.ts inMyAgents, task #4192). Absent from an older backend. */
agents: Record<string, { downSince: string | null; limitedUntil: string | null; workDecision: 'awaiting' | null; roleId: string | null; roleName: string;
kind: import('../agentKind.js').AgentKind; chatId: string | null; myAgent: boolean
/** Lead or Member, and its main project when the reader reads that project (agentKind.ts, task #4540). Absent from an older backend. */
role: import('../agentKind.js').AgentRole; mainProjectId: string | null }>
/** Every contributed machine the reader can see. */
/** `clientVersion`: the CLI version its daemon last connected with (routing reads a machine updated since its failed starts). */
machines: Record<string, { availableSlots: number; teamWork: { allowed: true } | { allowed: false; reason: string; [key: string]: unknown }; clientVersion?: string
/** Engines suspended there now after failed starts, with why (engineHealth.ts); absent when none. */
suspendedEngines?: Record<string, string>
/** Pickup timeout cooldown: applies to every new start, including grid models. */
machineSuspended?: string
/** A person reading a teammate's machine: where New Project's Product Manager would run there by engine, the machine
* (its Team account or itself), or why it cannot now (leadStart.ts leadChoices). Absent for their own machines. */
lead?: Record<string, { machineId: string } | { refused: string }> }>
/** A Lead agent only. */
otherProjectsWork?: OtherProjectWorkView[]
/** A project agent only: the account each project's PM runs on, a project it may not read named "another project". */
pmAccounts?: Array<{ machineId: string; hostMachineId?: string; engine: string; project: string; pm: string }>
/** The Swarm's owner only: projects nobody owns, which they may delete but never read (projects.ts ownerlessProjects). */
ownerlessProjects?: Array<{ id: string; name: string; conversations: number }>
/** A person only. */
mentionsWaiting?: number
/** A person only: a digest of which tags wait, moving when they change though the count may not. */
mentionsDigest?: string
/** Signed links to uploaded avatars, by `person:<id>` and `agent:<id>` (avatarLinks.ts): fresh with every read, the same
* through each half hour, each opening for at most an hour. Absent when nobody visible has one. */
avatars?: Record<string, string>
/** A person only: decisions asked of them, still open. */
decisionsWaiting?: number
/** A person only: a digest of which decisions are open, moving when they change though the count may not. */
decisionsDigest?: string
/** A person only: the task agents waiting at a prompt in their terminals for them (promptWaits.ts), shown under Decisions and
* counted with them. Absent from an older backend, and for an agent. */
promptsWaiting?: PromptWait[]
/** A person only: a digest of which of their Activity rows are unread (activity.ts), moving when one is written, read or
* removed. No count and no chat: the client reads its list again when it moves. Absent from an older backend. */
activityDigest?: string
/** A person only: a digest of their reminders and when each is due (reminders.ts), moving when one is set, replaced or
* cleared. No count and no chat: the client reads its reminders again when it moves, and at the `next` time that read
* gave it. Absent from an older backend. */
remindersDigest?: string
/** A person only: their own read marks (readMarks.ts), the newest message sequence read by conversation. A first load has
* every one of the conversations it holds; a changes read only those moved since its cursor, kept by the client as the
* higher of the two. Never another person's. */
readMarks?: Record<string, number>
/** A person only: those of their `readMarks` whose last move was their own Mark unread (readMarks.ts lowerReadMark), which
* a client takes in place of a higher mark it holds, where it keeps the higher of the two for every other mark. Like
* `readMarks`: a first load has every one of the conversations it holds, a changes read those moved since its cursor; a read
* that raises the mark again ends it. Absent when there are none, and from an older backend. Never another person's. */
unreadMarks?: Record<string, number>
/** A person only: their own thread marks (readMarks.ts), the newest message sequence read by thread root, by conversation.
* Like `readMarks`: a first load has those of the conversations it holds, a changes read those moved since its cursor.
* Absent when there are none, and from an older backend. Never another person's. */
threadMarks?: Record<string, Record<string, number>>
/** A person only: their own notification setting by conversation (chatSettings.ts), `all`, `mentions` or `muted`. Like
* `readMarks`: a first load has every one of the conversations it holds (a chat with none is at `mentions`), a changes read
* those moved since its cursor. Absent when there are none, and from an older backend. Never another person's. */
chatSettings?: Record<string, 'all' | 'mentions' | 'muted'>
/** Present, and false, only from a backend that held Harness Team accounts to listed owners' Swarms (2026-10-27 to 11-02):
* this Mac's daemon and Desktop then offered no team account for it. No longer sent: every Swarm takes part. */
teamAccounts?: false
/** This server takes a thread reply's `newSession` (buddySessions.ts): Desktop offers New session only where it is
* true and the Buddy's machine reports it can run sessions. Absent from an older backend, whose strict schema refuses
* the field. */
threadSessions?: true
/** This server also takes `newSession` on a person's top-level message in their own Buddy chat: the message roots its
* own thread, which gets the session (commands.ts routeBuddySession). Desktop offers New session in that chat's main
* composer only where it is true. Absent from an older backend, which refuses it. */
sessionsFromChat?: true
/** One Buddy per person per Swarm (Dee, 10-31): a person's one Buddy chat, its Buddy reading every project they read, and New
* session in one project. An older server says nothing, and its app keeps a Buddy per project. */
swarmBuddy?: true
}
export interface OtherProjectWorkView {
conversationId: string; projectName: string; title: string; owns: string[]; status: WorkStatus; agentName: string; pr: string | null
}
interface ReadMeta {
format: typeof READ_FORMAT
/** Opaque: unpadded base64url. Send it back unchanged to `changes`. */
cursor: string
serverTime: number
/** The newest data change of any part of this Swarm (touches do not count); null for a Swarm with no parts yet. */
lastChangedAt: number | null
/** The visibility epoch; a change makes `changes` answer `reload`. */
epoch: number
}
/** GET /api/super-tabs/:tabId/parts[?asAgentId=] */
export interface FirstLoad extends ReadMeta {
/** Own active Tasks; absent for agent readers and older servers. */
personalTasks?: import('./personalTasks.js').PersonalTasks
tabId: string
githubApp?: true
/** This backend opens a task's steps (`conversation.create` with `step`, task steps design); absent on an older one. */
steps?: true
head: LivePart<HeadView>
members: LivePart<MemberView>[]
agents: LivePart<AgentView>[]
/** The reader's visible active groups, in creation order. */
groups: LivePart<GroupView>[]
machines: LivePart<MachineView>[]
starts: LivePart<StartView>[]
progress: LivePart<ProgressView>[]
derived: Derived
/** Opaque: the reader's summary (`derived` without its marks) as a hash (derivedEtag.ts). Send it back as `derivedEtag` on
* the next change read. Absent from an older backend. */
derivedEtag: string
}
/** The reader's own marks of `derived`, which a change read sends only as they move. */
export type ReaderMarks = Pick<Derived, 'readMarks' | 'unreadMarks' | 'threadMarks' | 'chatSettings'>
/** GET /api/super-tabs/:tabId/changes?cursor=[&asAgentId=][&machines=light][&derivedEtag=] */
export type Changes = ChangesReload | ChangesDelta
/** Drop the store and do a first load: bad or old cursor, another epoch, or older than tombstones are kept. */
export interface ChangesReload { reload: true }
/** A machine's own reading, as one line, for a client that asked (`machines=light`): when it last reported, from which it works out
* online or offline as it does from a part. The rest of the reading is read on demand (MachineReadings). */
export interface MachineReading { key: string; version: number; receivedAt: number }
/** GET /api/super-tabs/:tabId/machine-readings[?asAgentId=]: every machine the reader sees, whole, for the route and the machine panel. */
export interface MachineReadings { format: number; serverTime: number; machines: LivePart<MachineView>[] }
export interface ChangesDelta extends ReadMeta {
/** Only summaries changed since this response’s existing cursor. */
personalTasks?: import('./personalTasks.js').PersonalTasks
reload: false
head: LivePart<HeadView> | null
members: PartChange<MemberView>[]
agents: PartChange<AgentView>[]
groups: GroupChange[]
machines: PartChange<MachineView>[]
/** Only for a client that asked: machines whose reading alone moved, which `machines` then leaves out. */
machineReadings?: MachineReading[]
starts: PartChange<StartView>[]
progress: PartChange<ProgressView>[]
/** The whole summary, or with `derivedUnchanged` only the reader's moved marks: the client keeps the summary it holds. */
derived: Derived | ReaderMarks
/** As a first load's: the summary this reply's reader has now, sent whether or not `derived` carries it. */
derivedEtag: string
/** Only when the client sent the `derivedEtag` its summary still hashes to (task #2906): `derived` then holds only the
* reader's moved marks. A client that sends no etag, as every released one, always gets the whole summary. */
derivedUnchanged?: true
}
/** GET /api/super-tabs/:tabId/groups?dormant=1[&projectId=][&before=][&asAgentId=]: newest activity first, 50 a page. */
export interface DormantGroups { groups: LivePart<GroupView>[]; next: string | null }
/** GET /api/super-tabs/:tabId/groups/:conversationId[?asAgentId=]: active or dormant; 404 when unreadable. */
export interface OneGroup { group: LivePart<GroupView> }
/** POST /api/super-tabs/:tabId/commands: the parts the command wrote (never the ones it only touched). */
export interface CommandReply {
result: Record<string, unknown>
parts: Array<{ kind: PartKind; key: string; version: number }>
lastChangedAt: number | null
/** Only on a replayed receipt from before the migration. */
legacyRevision?: number
}
/** GET /api/super-tabs/list[?after=][&mentions=1] */
export interface SwarmList {
/** `workspaceId` names its Workspace (null before the migration); a Swarm whose Workspace the person left is not listed. */
tabs: Array<{ id: string; name: string; ownerId: string; workspaceId: string | null; paused: boolean; lastChangedAt: number | null
/** Only on the reader's own Personal Swarm. */
personal?: true
/** With `?mentions=1`: the person's waiting tags in the Swarm and their digest, as the Swarm's own state counts them (a
* Swarm whose count cannot be told here has neither). */
mentionsWaiting?: number; mentionsDigest?: string }>
next: string | null
}
/** GET /api/super-tabs/:tabId/conversations/:conversationId/messages[?after=&afterId= | ?before=&beforeId= | ?messageId=]
* (design 4.6). Rows are ordered by (sequence, id); `revision` is gone. With no cursor the page is the newest 100, and
* `next` names its oldest row: send it back as `before`/`beforeId` for the page before. Forward pages (`after`) name their
* newest row the same way. `next` is null at the end. `after` alone (no `afterId`) means strictly after that sequence,
* which is all a poll for new messages needs. */
export interface MessagePageCursor { sequence: number; id: string }
export interface MessagePage<M = Record<string, unknown>> {
messages: M[]
next: MessagePageCursor | null
/** The conversation's reaction counter (reactions.ts): when it moved, read the page shown again for its counts. Each
* message carries `reactions: [{ emoji, count, by: [{ kind, id }] }]`, current members only. */
reactionSeq: number
}
/** GET /api/super-tabs/hosts/:machineId/changes?cursor=[&full=1], or POST to the same path with this body when the host
* holds etags (up to 500 Swarms do not fit in a URL). Ask `full` at start and at least every 60 s. */
export interface HostChangesRequest {
cursor?: string
full?: boolean
/** Swarm id → the `etag` of the rows the host holds for it. A Swarm whose rows still hash the same comes back unchanged. */
held?: Record<string, string>
}
export interface HostChanges {
format: typeof READ_FORMAT
full: boolean
cursor: string
/** Swarms with a host-relevant change (all of the machine's Swarms when `full`): replace each one's rows, or keep the
* rows held for an `unchanged` one. */
tabs: HostTab[]
/** Incremental only: Swarms that no longer list this machine. Empty when `full`. */
removedTabIds: string[]
}
export type HostTab = HostTabRows | HostTabUnchanged
/** The rows still hash to the `etag` the host sent in `held`: keep them (only `lastChangedAt` may have moved). */
export interface HostTabUnchanged { tabId: string; lastChangedAt: number | null; etag: string; unchanged: true }
export interface HostTabRows {
tabId: string
lastChangedAt: number | null
/** Opaque: send it back in `held`. It changes whenever `roster`, `pool` or `assignments` do (not for the host's own
* machine reading or the rows' change times), and may change when they do not. */
etag: string
unchanged?: never
/** Today's `GET /hosts/:m` rows for this Swarm, `revision` replaced by `lastChangedAt`. */
roster: HostRosterRow[]
/** Today's `GET /hosts/:m/pools` row for this Swarm, or null when this machine is not contributed there by the caller. */
pool: HostPool | null
/** Today's `GET /hosts/:m/assignments` rows for this Swarm. */
assignments: Array<{ tabId: string; assignmentId: string; harnessId: string }>
}
export type HostRosterRow =
| HostAgentRow
| { tabId: string; agent: { id: string; harnessId: string; machineId: string }; closeSession: true; active: false }
| { tabId: string; cleanup: { machineId: string; removalId: string } }
| { tabId: string; joinTeam: { machineId: string; name: string; maxAgents: number } }
export interface HostAgentRow {
/** A main Buddy's private chat, used only by its own host to restart it on another engine. */
buddyConversationId?: string
tabId: string
tabName: string
lastChangedAt: number | null
paused: boolean
active: boolean
attention: { assignmentId: string; status: WorkStatus; result: string | null } | null
/** Its task lost to a usage limit, still waiting for it: when its host types it back into the same session. `lostAt`
* names that loss, since one task can be lost, resumed and lost again. */
resume: { conversationId: string; assignmentId: string; lostAt: number; at: string } | null
agent: Agent
/** A Buddy's own chat, its main one's or the thread session's (task #3818): its host ends a session and moves a model switch
* there. Absent on every other agent; null while its chat is not loaded. An older backend sends none: the person's main chat. */
buddyChatId?: string | null
/** Main Buddy whose session may rest and resume in place (#3824). */
buddySleepManaged?: true
joinSwarm: boolean
skillMode: 'default' | 'orchestration'
role?: { id: string; name: string; kind: string; version: string; projectId: string } | null
/** The role it goes by (instructions.ts roleNameOf). */
roleName: string
/** Its project's instructions as the state names them: the host reads the text when `revision` moves. Revision 0 (no
* `hash`): no document yet, so the built-in template. */
instructions: { projectId: string; revision: number; hash: string | null; coordinatorName: string } | null
lead: boolean
/** A PM's own row: the oldest message a person sent it that it has not answered (timeChecks.ts owedAsk), and how long it may
* owe one while it hangs before its host restarts it. Null on every other row, and while it owes nothing. */
owed: { messageId: string; since: number; restartAfterMs: number } | null
/** New: lets the host decide what it may read without a full Swarm read. */
leadsConversationId: string | null
/** The conversation this agent leads, when it is a project's Product Manager. */
ledConversationId: string | null
stopRequested: boolean
observers: Array<{ email: string; userId: string }>
/** Its session is confidential in some Swarm: the host refuses every share of it, ordinary ones too (Critical 1). */
confidential: boolean
/** Confidential, but this Swarm's current Lead: the host lets `observers` watch it through this Swarm's shares while this
* row is in force, and nobody else (Ken, 2026-10-28). An older host ignores it and refuses them, which errs closed. */
membersWatch: boolean
}
export interface HostPool {
tabId: string
paused: boolean
machine: ContributedMachine
starts: AgentStart[]
/** Buddies' starts (buddies.ts), apart from `starts`: a host from before Buddies would launch one as a Builder. */
buddyStarts?: AgentStart[]
/** Product Managers' starts (leadStart.ts), apart from `starts` for the same reason. */
leadStarts?: AgentStart[]
/** Regular agents' starts (commands.ts agent.new, task #4116), apart for the same reason. */
regularStarts?: AgentStart[]
projects?: Array<{ id: string; leadConversationId: string; repository?: unknown; conversationIds: string[] }>
localGrid?: string
reservations: Array<{ harnessId: string; generation: string }>
harnessIds: string[]
removedHarnessIds?: string[]
githubApp?: true
/** The host may say what it launches beyond workers in its readings (leadStart.ts). */
capabilitiesWanted?: true
/** Asks for positive idle Buddy activity in fresh machine readings (#3824). */
buddySleepWanted?: true
}
/** HTTP 426 on GET /api/super-tabs, /:tabId, /hosts/:m, /hosts/:m/pools and /hosts/:m/assignments. */
export const UPDATE_REQUIRED = { code: 'UPDATE_REQUIRED', status: 426, message: 'Update Harness to keep using this Swarm.' } as const
/** HTTP 503 on the new routes while a Swarm is still on the old format; clients retry. */
export const SWARM_MIGRATING = { code: 'SWARM_MIGRATING', status: 503, message: 'This Swarm is being upgraded. Try again in a moment.' } as const