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 host form (design 4.10): for one machine, the rows of every Swarm it serves (full), or of the Swarms with a change
* that concerns it since the cursor (incremental). Grants and billing live outside the parts, so the host asks for a full
* read at start and at least every 60 s.
*/
import type { Prisma, PrismaClient } from '@prisma/client'
import type { AuthUser } from '../../lib/ssoAuth.js'
import { machineAlive } from '../../lib/prisma.js'
import { isTeamSession } from '../../lib/teamSession.js'
import { machineBillingAllowsDataPlane } from '../../lib/billingState.js'
import { fail, type SuperTabState } from '../model.js'
import { GrantReads, TEAM_HOST_ONLY, TEAM_HOST_ONLY_MESSAGE, teamByRecord, type SuperTabStore } from '../store.js'
import type { CacheView } from '../cache.js'
import { readLastChangedAts, readMachines, deriveLight } from '../cachedReads.js'
import { retryTransient } from '../retry.js'
import * as parts from '../parts/index.js'
import type { MachineData, Part } from '../parts/index.js'
import { groupsBy, retryStaleIndex } from '../parts/indexed.js'
import { plainHost } from '../parts/write.js'
import { READ_FORMAT, type HostChanges, type HostChangesRequest } from './contract.js'
import { cursorFor, readCursor } from './cursor.js'
import { hostTab, type HostLookups } from './hostRows.js'
import { hostInputs, ROW_HASH } from './hostInputs.js'
import { confidentialSessions } from '../confidential.js'
import { machineSwarms, swarmsIn } from '../swarmRows.js'
type Transaction = Prisma.TransactionClient
/** A full read covers this many of the machine's Swarms, most recently changed first (was 100 full Swarms each second). */
const FULL_TABS = 500
/** A change this machine's host cares about from the part alone (parts/commit.ts plainHost, the rule the push shares). */
function plainlyRelevant(part: Part, machineId: string): boolean {
const host = plainHost(part.kind, part.data)
return host === 'all' || host === machineId
}
const PLAIN_KINDS = ['head', 'member', 'agent', 'start'] as const
export class HostReads {
private readonly db: PrismaClient
private readonly now: () => number
/** Reads the store's own database, on its clock unless given one (tests). */
constructor(private readonly store: SuperTabStore, private readonly options: { now?: () => number; githubApp?: boolean; teamAccountsIdle?: boolean } = {}) {
this.db = store.db
this.now = options.now ?? store.now
}
async changes(user: AuthUser, machineId: string, request: HostChangesRequest): Promise<HostChanges> {
const t0 = this.now()
const from = request.cursor && !request.full ? readCursor(request.cursor, 0, t0) : { reload: true as const }
// Outside any transaction: each Swarm's signature and state come through the read cache (cache.ts), at stamps read once.
const tx = this.db
const owned = await tx.machine.findFirst({ where: { machineId, userId: user.sub, autonomousEnv: user.autonomousEnv, ...machineAlive } })
await this.store.hostFor(tx, user, machineId, owned)
if (!owned || !machineBillingAllowsDataPlane(owned)) fail('HOST_UNAVAILABLE', 'This execution host is unavailable.', 403)
// Every agent's grant check of this read shares one read of each machine, share, contributor and Workspace membership.
const grants = new GrantReads(owned)
// Swarms still in one row are migrated when first opened; the job migrates every one before the new release serves.
const ids = await machineSwarms(tx, user.autonomousEnv, machineId, FULL_TABS)
const teams = isTeamSession(user) || this.options.teamAccountsIdle ? [] : await tx.machine.findMany({ where: { userId: user.sub,
hostMachineId: machineId, sessionKind: 'team', autonomousEnv: user.autonomousEnv, ...machineAlive }, select: { machineId: true } })
const full = 'reload' in from
const woken = full ? null : await this.woken(tx, ids, machineId, from.since)
const tabs = []
const answered = woken ? ids.filter(id => woken.has(id)) : ids
const cached = await this.store.view(answered)
const newest = await readLastChangedAts(tx, cached, answered)
for (const tabId of ids) {
if (woken && !woken.has(tabId)) continue
// A wake can repeat while the cursor overlaps the same change. Share the timestamp at the read's stamp instead
// of scanning every part kind again before the unchanged-etag shortcut.
const lastChangedAt = newest.get(tabId) ?? null, held = request.held?.[tabId]
// The etag is the rows' hash and then the signature of what they were built from. A matching signature answers
// 'unchanged' from version columns alone. Never on a full read: grants and billing live outside the parts.
const inputs = await cached.get(tabId, 'host:inputs', 'main', () => hostInputs(tx, cached, tabId))
if (!full && held && inputs && held.slice(ROW_HASH) === inputs) { tabs.push({ tabId, lastChangedAt, etag: held, unchanged: true as const }); continue }
const state = await this.tabState(tx, cached, tabId, machineId)
// Its Team account alone hosts a machine this Swarm records as one, whatever its account row says now (store.ts).
if (!isTeamSession(user) && teamByRecord(state, machineId)) fail(TEAM_HOST_ONLY, TEAM_HOST_ONLY_MESSAGE, 403)
const rows = await hostTab(tabId, state, machineId, user, lastChangedAt, await this.lookups(tx, state, teams, grants))
const etag = rows.etag + (inputs ?? '')
// The host already holds these rows: say so instead of sending them again.
tabs.push(held?.slice(0, ROW_HASH) === rows.etag ? { tabId, lastChangedAt, etag, unchanged: true as const } : { ...rows, etag })
}
return { format: READ_FORMAT, full, cursor: cursorFor(t0, 0), tabs,
removedTabIds: full ? [] : await this.removed(tx, user.autonomousEnv, machineId, from.since, new Set(ids)) }
}
/**
* The Swarms with a change for this machine's host since the cursor. Groups and machine parts go by the markers their
* writes left (parts/commit.ts), since their new data alone cannot say it: a group concerns the host when its agents or
* its work were on this machine before or after the write (an agent leaving its last group, review round 1); a machine
* part when its settings or ledger changed, never when only its reading did (every 15 s; group 5's run, 2026-10-26).
*/
private async woken(tx: Transaction, ids: string[], machineId: string, since: number): Promise<Set<string>> {
// A host with no Swarm polls every second: an empty list would reach Prisma as `$or: []`, a scan of the whole collection.
if (!ids.length) return new Set()
const after = new Date(since)
const [changed, groups, machines] = await Promise.all([
parts.loadChanged(tx, ids, after, PLAIN_KINDS),
// Through the host's own index by name (parts/indexed.ts): every host runs this every second, and reads no other host's.
groupsBy(tx, 'wake', [{ $match: { tabId: { $in: ids }, changedAt: { $gt: { $date: after.toISOString() } }, hostMachineIds: machineId } },
{ $project: { _id: 0, tabId: 1 } }]) as Promise<unknown> as Promise<Array<{ tabId: string }>>,
tx.swarmMachine.findMany({ where: { tabId: { in: ids }, hostChangedAt: { gt: after } }, select: { tabId: true, key: true, data: true } }),
])
const woken = new Set([...ids.filter(id => changed.get(id)?.some(p => plainlyRelevant(p, machineId))), ...groups.map(g => g.tabId)])
// This machine's own settings, a team account's pool on this Mac, or the Mac this team account follows. Not read when no
// machine changed, as on most polls: Prisma sends an empty list as a filter no index serves, a scan of every Swarm's machines.
const follows = new Map(machines.length ? (await tx.swarmMachine.findMany({ where: { tabId: { in: [...new Set(machines.map(m => m.tabId))] }, key: machineId },
select: { tabId: true, data: true } })).map(m => [m.tabId, (m.data as MachineData | null)?.contribution?.hostMachineId]) : [])
for (const m of machines) {
if (m.key === machineId || (m.data as MachineData | null)?.contribution?.hostMachineId === machineId || follows.get(m.tabId) === m.key) woken.add(m.tabId)
}
return woken
}
/** The Swarm's active parts plus, dormant ones included, every group its agents on this machine are in (a finished
* group that is not archived still keeps its agent from automatic cleanup) and every group of a start it holds (the
* host still settles a queued start whose group went quiet). */
private async tabState(tx: Transaction, cached: CacheView, tabId: string, machineId: string): Promise<SuperTabState> {
const [light, machines] = await Promise.all([cached.get(tabId, `host:state:${machineId}`, 'main',
// With a cache that patches, built from the entries it holds (cachedReads.ts deriveLight, spec 2026-11-02 poll cost);
// otherwise one snapshot of what the host's rows are built from, tried again when a lock it waits for is held (retry.ts).
() => cached.patching ? deriveLight(this.db, cached, tabId, { groups: 'working', machineId })
: retryTransient(() => retryStaleIndex(() => this.db.$transaction(t => this.hostParts(t, tabId, machineId))))),
readMachines(tx, cached, tabId)])
return parts.reassemble({ ...light, machines }, { share: true })
}
private async hostParts(tx: Transaction, tabId: string, machineId: string) {
const [agents, starts] = await Promise.all([
tx.swarmAgent.findMany({ where: { tabId, machineId, deleted: false }, select: { key: true } }),
tx.swarmStart.findMany({ where: { tabId, machineId, deleted: false, finishedAt: null }, select: { conversationId: true } }),
])
const groupIds = [...new Set(starts.map(s => s.conversationId))]
// A pool lists every conversation of a project it has a start in.
const projectIds = groupIds.length ? [...new Set((await tx.swarmGroup.findMany({ where: { tabId, key: { in: groupIds } }, select: { projectId: true } }))
.map(g => g.projectId ?? 'lead'))] : []
// Light conversations (parts/light.ts), and only those host rows read: its agents' (dormant ones too, for `active`),
// the Lead conversations, running work (assignments, attention, stop requests), and its starts' and their projects'.
return parts.loadLight(tx, tabId, { groups: 'working', agentIds: agents.map(a => a.key), groupIds, projectIds, machines: false })
}
private async lookups(tx: Transaction, state: SuperTabState, teams: Array<{ machineId: string }>, grants: GrantReads): Promise<HostLookups> {
const people = state.people.length ? await tx.user.findMany({ where: { id: { in: state.people.map(p => p.id) }, autonomousEnv: state.environment }, select: { id: true, email: true } }) : []
const confidential = await confidentialSessions(tx, state.agents.map(a => a.id), state.id)
return { people, confidential, teams, githubApp: !!this.options.githubApp, agentGrant: target => this.store.agentGrant(tx, state, target, grants) }
}
/** Swarms whose record of this machine changed since the cursor and that no longer list it. */
private async removed(tx: Transaction, autonomousEnv: string, machineId: string, since: number, listed: Set<string>): Promise<string[]> {
const rows = await tx.swarmMachine.findMany({ where: { machineId, hostChangedAt: { gt: new Date(since) } }, select: { tabId: true } })
const gone = [...new Set(rows.map(r => r.tabId))].filter(id => !listed.has(id))
if (!gone.length) return []
return swarmsIn(tx, autonomousEnv, gone)
}
}