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 { createHash } from 'node:crypto'
import { refuseOthersInPrivateChat } from './buddies.js'
import type { Prisma, SuperTabNativeContext } from '@prisma/client'
import { z } from 'zod'
import type { AuthUser } from '../lib/ssoAuth.js'
import { isTeamSession, TEAM_SESSION_LIMITED, TEAM_SESSION_MESSAGE } from '../lib/teamSession.js'
import { activeWork, agent, appendPullRequestUrls, author, conversation, fail, stableId, SuperTabError,
type Actor, type Agent, type Author, type Conversation, type SuperTabState } from './model.js'
import { accessInputs, canReadGroup, groupRepositoryUrl, readConversation, watchersLost } from './projects.js'
import { mayDrive } from './terminal.js'
import { CANCELLABLE_DELIVERY } from './pageReads.js'
import { cloneData } from './cloneData.js'
import { numberMessages, type Touch } from './parts/commit.js'
import { redactCredentials } from './credentials.js'
import type { DeliveriesEnding, DeliveriesWaiting } from './store.js'
const id = z.string().min(1).max(160).regex(/^[A-Za-z0-9_-]+$/)
export const openNativeSchema = z.object({ operationId: id, conversationId: id, agentId: id }).strict()
export const nativeEventSchema = z.object({
turnId: id, kind: z.enum(['prompt', 'answer', 'gap']), previousEventId: id.nullable(),
text: z.string().max(16_000), truncated: z.boolean(), interrupted: z.boolean(),
gap: z.object({ incidentId: id, reason: z.enum(['recording_restarted', 'history_lost', 'unattributed_input', 'context_expired', 'agent_stopped', 'prompt_missing']),
detectedAt: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER) }).strict().optional(),
}).strict().refine(event => !event.gap || event.kind === 'gap', 'Recovery metadata belongs to a recording gap.')
type NativeEvent = z.infer<typeof nativeEventSchema>
type Transaction = Prisma.TransactionClient
type Grant = { machineOwnerId: string; contributorId: string; hostGrant: string | null }
interface Binding {
tabId: string; conversationId: string; agentId: string; harnessId: string; machineId: string; machineOwnerId: string
operator: Author; contributorId: string; contributionGeneration: string; contributionGrant: string | null; inputGrant: string | null
}
interface Loaded { state: SuperTabState }
interface Deps {
transaction<T>(body: (tx: Transaction) => Promise<T>): Promise<T>
/** The Swarm loaded from its parts, with these groups even when dormant. */
load(tx: Transaction, user: AuthUser, tabId: string, groupIds: string[]): Promise<Loaded>
/** Writes what changed from the loaded state, touching the parts the write relied on (store.ts save). */
save(tx: Transaction, loaded: Loaded, next: SuperTabState, stamp: number, touches: Touch[]): Promise<unknown>
stamp(): number
agentGrant(tx: Transaction, state: SuperTabState, target: Agent): Promise<void>
contribution(tx: Transaction, state: SuperTabState, actor: Actor, command: { machineId: string }): Promise<Grant>
/** The one machine a team session (lib/teamSession.ts) hosts for; null for any other sign-in. */
teamHost(tx: Transaction, user: AuthUser): Promise<string | null>
/** Refuses a person no longer in the Swarm's Workspace (workspaceStore.ts requireWorkspaceAccess). */
workspaceAccess(tx: Transaction, state: SuperTabState, userId: string): Promise<void>
/** Tells the agent's machine, once `tx` commits, that a delivery waits for it (store.ts announce). */
announce(tx: Transaction, waiting: DeliveriesWaiting): void
}
const json = (value: unknown): Prisma.InputJsonValue => JSON.parse(JSON.stringify(value)) as Prisma.InputJsonValue
const digest = (value: unknown) => createHash('sha256').update(JSON.stringify(value)).digest('hex')
interface Checkpoint { eventId: string | null; turnId: string | null; recordedAt: string | null; sequence: number }
interface Recovery {
assignmentId: string; incidentId: string; reason: string; detectedAt: number; checkpoint: Checkpoint; required: boolean
}
const gapReasons = {
recording_restarted: 'The work was interrupted by a restart of the terminal recording.',
history_lost: 'Part of the recorded terminal history was lost.',
unattributed_input: 'Terminal input could not be attributed to this conversation.',
context_expired: 'Terminal recording expired before the activity was captured.',
agent_stopped: 'The agent stopped during an unfinished recorded turn.',
prompt_missing: 'A terminal answer was observed without its recorded prompt.',
}
/** A required recovery's notice: what happened to [target]'s recording on [group]'s task, and the last checkpoint, with no next
* step and no change to the task (project instructions, phase 4: the instructions say what the coordinator does). */
export function recoveryText(target: { name: string; displayName?: string }, group: { title: string }, reason: string, checkpointAt: string | null): string {
return `${target.displayName ?? target.name}'s terminal recording on "${group.title}" has a gap. ${reason}\n\n`
+ `Last recorded checkpoint: ${checkpointAt ?? 'time unavailable'}. Input and commands before the gap may already have taken effect.`
}
/** Who a recorded terminal turn reaches: its task's coordinator for a required recovery, and nobody for a typed prompt, its
* answer or any other gap, which name no one (phase 1's deferred ruling); never the coordinator for its own terminal. */
export function turnRecipients(group: { leadId: string | null }, target: { id: string }, required: boolean): string[] {
return required && group.leadId && group.leadId !== target.id ? [group.leadId] : []
}
/** A host reports what its native engine observed; it cannot create human-authored
* messages. The human attached to the source is the authenticated opener of that
* terminal context, not an inference from a device name or the machine owner. */
export class SuperTabNativeStore {
constructor(private readonly deps: Deps) {}
private async validate(tx: Transaction, state: SuperTabState, record: SuperTabNativeContext) {
if (record.revoked) fail('NATIVE_CONTEXT_REVOKED', 'Reopen the terminal from this conversation.', 403)
const binding = record.binding as unknown as Binding
const operator = author(state, { kind: 'person', userId: binding.operator.id, email: binding.operator.name }, true)
const target = agent(state, record.agentId)
const group = readConversation(state, { kind: 'person', userId: binding.operator.id, email: binding.operator.name }, record.conversationId)
// A terminal drives its session and its answers land in the conversation: only those who may drive it may use it.
try { mayDrive(state, { kind: 'person', userId: binding.operator.id, email: binding.operator.name }, target) } catch (error) {
// The driving rule's own reason (read-only, the agent's project gone, a Lead or a private session), under the code clients reopen on.
if (error instanceof SuperTabError) fail('NATIVE_CONTEXT_REVOKED', error.message, 403)
throw error
}
if (operator.membershipGeneration !== binding.operator.membershipGeneration || group.archived || !group.agentIds.includes(target.id)
|| target.harnessId !== binding.harnessId || target.machineId !== binding.machineId || target.machineOwnerId !== binding.machineOwnerId
|| target.contributorId !== binding.contributorId || target.membershipGeneration !== binding.contributionGeneration
|| (target.hostGrant ?? null) !== binding.contributionGrant) {
fail('NATIVE_CONTEXT_REVOKED', 'This terminal context no longer belongs to the current contribution.', 403)
}
await this.deps.agentGrant(tx, state, target)
await this.deps.workspaceAccess(tx, state, binding.operator.id)
// Read the person's current identity, rather than trusting a name supplied by
// a terminal client or reusing an old email after an account change.
const user = await tx.user.findUnique({ where: { id: operator.id }, select: { email: true, autonomousEnv: true } })
if (!user || user.autonomousEnv !== state.environment) fail('NATIVE_CONTEXT_REVOKED', 'The terminal opener is unavailable.', 403)
const grant = await this.deps.contribution(tx, state, { kind: 'person', userId: operator.id, email: user.email }, target)
if (grant.machineOwnerId !== binding.machineOwnerId || grant.hostGrant !== binding.inputGrant) {
fail('NATIVE_CONTEXT_REVOKED', 'The terminal opener no longer has the original machine access.', 403)
}
return { binding, target, group }
}
async open(user: AuthUser, tabId: string, input: z.infer<typeof openNativeSchema>) {
// A person opens a terminal; a team session has no person to open one as.
if (isTeamSession(user)) fail(TEAM_SESSION_LIMITED, TEAM_SESSION_MESSAGE, 403)
const request = openNativeSchema.parse(input)
return this.deps.transaction(async tx => {
const { state } = await this.deps.load(tx, user, tabId, [request.conversationId])
await this.deps.workspaceAccess(tx, state, user.sub)
const operator = author(state, { kind: 'person', userId: user.sub, email: user.email }, true)
const target = agent(state, request.agentId)
const group = readConversation(state, { kind: 'person', userId: user.sub, email: user.email }, request.conversationId)
// A terminal opens in a project's conversation or a person's own Buddy chat; readConversation refuses the removed Leads
// conversation (model.ts leadsRemoved).
if (group.archived || !group.agentIds.includes(target.id)) fail('AGENT_UNAVAILABLE', 'Choose an agent in this conversation.')
await this.deps.agentGrant(tx, state, target)
const grant = await this.deps.contribution(tx, state, { kind: 'person', userId: user.sub, email: user.email }, target)
const contextId = stableId('native', tabId, user.sub, request.operationId)
const prior = await tx.superTabNativeContext.findUnique({ where: { id: contextId } })
if (prior) {
if (prior.conversationId !== request.conversationId || prior.agentId !== request.agentId) fail('OPERATION_REUSED', 'Use a new operation ID for a different terminal.')
await this.validate(tx, state, prior)
return { contextId }
}
mayDrive(state, { kind: 'person', userId: user.sub, email: user.email }, target)
const binding: Binding = { tabId, conversationId: group.id, agentId: target.id, harnessId: target.harnessId,
machineId: target.machineId, machineOwnerId: target.machineOwnerId, operator,
contributorId: target.contributorId, contributionGeneration: target.membershipGeneration,
contributionGrant: target.hostGrant ?? null, inputGrant: grant.hostGrant }
await tx.superTabNativeContext.create({ data: { id: contextId, tabId, conversationId: group.id,
agentId: target.id, userId: user.sub, binding: json(binding) } })
return { contextId }
})
}
private async hosted(tx: Transaction, user: AuthUser, tabId: string, contextId: string) {
const record = await tx.superTabNativeContext.findFirst({ where: { id: contextId, tabId } })
?? fail('NOT_FOUND', 'This terminal context is unavailable.', 404)
const loaded = await this.deps.load(tx, user, tabId, [record.conversationId]), state = loaded.state
const binding = record.binding as unknown as Binding
if (binding.machineOwnerId !== user.sub) fail('FORBIDDEN', 'Only the execution host can record this terminal.', 403)
// A team session records only the terminals of its own machine's agents.
const team = await this.deps.teamHost(tx, user)
if (team !== null && binding.machineId !== team) fail(TEAM_SESSION_LIMITED, TEAM_SESSION_MESSAGE, 403)
const verified = await this.validate(tx, state, record)
return { ...verified, loaded, record, team: team !== null }
}
async read(user: AuthUser, tabId: string, contextId: string) {
return this.deps.transaction(async tx => {
const { binding, record } = await this.hosted(tx, user, tabId, contextId)
// Old recorders ignore this. New recorders keep the old strict request
// shape until this backend explicitly advertises recovery support.
return { contextId, ...binding, lastEventId: record.lastEventId, recovery: { version: 1, serverTime: Date.now() } }
})
}
async allowsDelivery(tx: Transaction, state: SuperTabState, contextId: string): Promise<boolean> {
const record = await tx.superTabNativeContext.findFirst({ where: { id: contextId, tabId: state.id } })
if (!record) return false
try { await this.validate(tx, state, record); return true }
catch (error) { if (error instanceof SuperTabError) return false; throw error }
}
private async recovery(tx: Transaction, tabId: string, group: Conversation, target: Agent, record: SuperTabNativeContext,
event: NativeEvent, eventId: string): Promise<{ source: Recovery; text: string } | null> {
const assignment = group.assignment
// A recording gap can also mean ordinary human typing or an expired view.
// Older recorders do not distinguish those, so only known interruptions wake the Lead.
if (event.kind !== 'gap' || !event.gap || !['recording_restarted', 'history_lost', 'agent_stopped'].includes(event.gap.reason)
|| !assignment || !activeWork(group) || assignment.agentId !== target.id
|| !group.leadId || group.leadId === target.id) return null
const previous = await tx.superTabMessage.findFirst({ where: { id: record.lastEventId ?? assignment.id, tabId, conversationId: group.id } })
const source = previous?.source as { turnId?: string; recovery?: Recovery } | null
// Preserve the original checkpoint through repeated gaps. A gap is not new work progress.
let checkpoint: Checkpoint = source?.recovery?.checkpoint ?? {
eventId: previous?.id ?? null, turnId: source?.turnId ?? null,
recordedAt: previous?.createdAt.toISOString() ?? null, sequence: previous?.sequence ?? 0,
}
const incidentId = event.gap.incidentId
const receiptId = stableId('native-recovery', assignment.id, incidentId)
const prior = await tx.superTabOperation.findUnique({ where: { id: receiptId } })
const progress = assignment.recordingProgress
const progressed = !!progress && progress.at >= event.gap.detectedAt
if (progress && !progressed && progress.revision > checkpoint.sequence) {
const latest = await tx.superTabMessage.findFirst({ where: { tabId, conversationId: group.id, sequence: progress.revision } })
if (latest) checkpoint = { eventId: latest.id, turnId: null, recordedAt: latest.createdAt.toISOString(), sequence: latest.sequence }
}
const required = !prior && !progressed && ['working', 'review'].includes(assignment.status)
const recovery: Recovery = { assignmentId: assignment.id, incidentId, reason: event.gap.reason,
detectedAt: event.gap.detectedAt, checkpoint, required }
const reason = assignment.status === 'review' && event.gap.reason === 'recording_restarted'
? 'Terminal recording restarted while the task was in review.' : gapReasons[event.gap.reason]
// What happened, for the coordinator; its task keeps its status (project instructions, phase 4).
const text = recoveryText(target, group, reason, checkpoint.recordedAt)
if (!prior) await tx.superTabOperation.create({ data: { id: receiptId, tabId, actorKey: `agent:${target.id}`,
requestHash: digest([assignment.id, incidentId]), revision: 0, result: json({ eventId, recovery }) } })
return { source: recovery, text }
}
async append(user: AuthUser, tabId: string, contextId: string, input: NativeEvent) {
const event = nativeEventSchema.parse(input)
return this.deps.transaction(async tx => {
const { loaded, record, binding, team } = await this.hosted(tx, user, tabId, contextId)
const state = cloneData(loaded.state)
const target = agent(state, record.agentId), group = conversation(state, record.conversationId)
const eventId = stableId('native-event', contextId, event.turnId, event.kind), requestHash = digest(event)
const prior = await tx.superTabOperation.findUnique({ where: { id: eventId } })
if (prior) {
if (prior.requestHash !== requestHash) fail('OPERATION_REUSED', 'This native observation already has different content.')
return prior.result
}
if (record.lastEventId !== event.previousEventId) fail('NATIVE_ORDER_CHANGED', 'Reconcile the recorded terminal observations before continuing.')
const promptId = stableId('native-event', contextId, event.turnId, 'prompt')
if (event.kind === 'answer' && !await tx.superTabOperation.findUnique({ where: { id: promptId } })) {
fail('NATIVE_PROMPT_MISSING', 'The terminal prompt was not recorded. Record the observation gap first.')
}
const recovery = await this.recovery(tx, tabId, group, target, record, event, eventId)
const observedBy = author(state, { kind: 'agent', agentId: target.id, machineOwnerId: user.sub }, true)
// What a person typed in the terminal, or the agent answered, is recorded without any credential in it.
const text = recovery?.source.required ? recovery.text : event.kind === 'gap'
? 'Some terminal activity could not be recorded. Check the native session for the full conversation.' : redactCredentials(event.text).text
// Leave a legacy group's list absent so the next read can recover its older links too.
if (group.pullRequestUrls !== undefined) appendPullRequestUrls(group, [text], groupRepositoryUrl(state, group))
// A required recovery reaches the coordinator; a typed prompt, its answer or any other gap names no one (phase 1).
const recipients = turnRecipients(group, target, !!recovery?.source.required)
const draft = { id: eventId, conversationId: group.id, author: observedBy, text, replyTo: null, recipients }
// A terminal turn is an ordinary message: it never wakes the coordinator (projectUpdates.ts noteWorkChanges).
const now = Date.now(), sequences = numberMessages(state, [draft], now), sequence = sequences.get(eventId)!
// The turn touches its agent (spec ruling 2). The person who opened the terminal is guarded by this context's row,
// which the turn writes: removing that person, or taking away their access, revokes the context (rule b,
// revokeNativeContexts). Touching the person instead would make one person's terminals in different groups conflict.
// A terminal turn in a person's private chat is theirs or their own agent's alone (task #4558, #4547).
refuseOthersInPrivateChat(state, [draft], loaded.state)
await this.deps.save(tx, loaded, state, this.deps.stamp(), [{ kind: 'agent', key: target.id }])
await tx.superTabMessage.create({ data: { id: eventId, tabId, conversationId: group.id, sequence,
author: json(observedBy), source: json({ kind: 'native', phase: event.kind, turnId: event.turnId,
operator: binding.operator, truncated: event.truncated, interrupted: event.interrupted, ...(recovery ? { recovery: recovery.source } : {}) }),
text, replyTo: event.kind === 'answer' ? promptId : null, recipientIds: recipients, thread: eventId } })
for (const recipient of recipients) {
const lead = agent(state, recipient)
await tx.superTabDelivery.create({ data: { id: stableId(eventId, recipient), tabId, conversationId: group.id,
messageId: eventId, nativeContextId: contextId, agentId: recipient, machineId: lead.machineId, machineOwnerId: lead.machineOwnerId,
assignmentId: activeWork(group) && group.assignment?.agentId === recipient ? group.assignment.id : null,
membershipGeneration: lead.membershipGeneration,
// What a team host (lib/teamSession.ts) reports is the agent's word, never the person's: it reaches the Lead as
// from the agent, so a team account cannot put words in the mouth of the person who opened the terminal.
...(team
? { authorKind: 'agent', authorId: target.id, authorGeneration: target.membershipGeneration }
: { authorKind: 'person', authorId: binding.operator.id, authorGeneration: binding.operator.membershipGeneration }) } })
this.deps.announce(tx, { machineId: lead.machineId, tabId, agentId: recipient })
}
await tx.superTabNativeContext.update({ where: { id: contextId }, data: { lastEventId: eventId } })
const result = { eventId, sequence }
await tx.superTabOperation.create({ data: { id: eventId, tabId, actorKey: `agent:${target.id}`, requestHash, revision: 0, result } })
return result
})
}
}
/** Removal followed by rejoining must not revive an old terminal binding. Only what this change ended is revoked: what
* ended earlier was revoked by the change that ended it, and no context opens without access (open; validate checks it
* again at every use). Most commands change no access and read nothing here: rebuilding every viewer and every member
* outside every private conversation on each command kept prod Mongo busy (2026-10-28). Returns those who lost sight of
* an agent (watchersLost), for the observers to check again. */
/** `ending` (store.ts endDeliveries) runs the cancel of the revoked contexts' waiting deliveries, so a host holding one hears. */
export async function revokeNativeContexts(tx: Transaction, before: SuperTabState, after: SuperTabState,
ending: (holds: DeliveriesEnding, end: () => Promise<{ count: number }>) => Promise<{ count: number }> = (_, end) => end()) {
const { conditions, watchersLost } = revokeConditions(before, after)
if (conditions.length) {
const where = { tabId: before.id, revoked: false, OR: conditions }
const revoked = await tx.superTabNativeContext.findMany({ where, select: { id: true } })
await tx.superTabNativeContext.updateMany({ where, data: { revoked: true } })
if (revoked.length) await ending({ matches: row => revoked.some(r => r.id === row.nativeContextId) }, () => tx.superTabDelivery.updateMany({ where: { tabId: before.id,
nativeContextId: { in: revoked.map(r => r.id) }, status: { in: [...CANCELLABLE_DELIVERY] } },
data: { status: 'cancelled', holdReason: null, holdSince: null } }))
}
return watchersLost
}
/** Which contexts a commit revokes, and who lost sight of which agent. A command that changes no access input checks
* nothing: rebuilding every check on each one cost a 480-group Swarm about 5 ms of every command (item 7, 2026-10-28). */
export function revokeConditions(before: SuperTabState, after: SuperTabState) {
const conditions: Prisma.SuperTabNativeContextWhereInput[] = []
if (accessInputs(before) === accessInputs(after)) return { conditions, watchersLost: [] }
const people = new Map(after.people.map(p => [p.id, p])), agents = new Map(after.agents.map(a => [a.id, a]))
const groups = new Map(after.conversations.map(c => [c.id, c]))
for (const member of before.people) {
const current = people.get(member.id)
if (!current || current.generation !== member.generation || (current.role === 'viewer' && member.role !== 'viewer')) conditions.push({ userId: member.id })
}
// A removed agent's contexts, and those of an agent given a replacement terminal: they name the old terminal, and its
// waiting turns are cancelled with them, so a claim racing the change conflicts on their rows (rule b).
for (const target of before.agents) {
const current = agents.get(target.id)
if (!current || current.harnessId !== target.harnessId) conditions.push({ agentId: target.id })
}
// Those who may no longer watch an agent, such as everyone but its machine's owner once it reads private chats.
const lost = watchersLost(before, after)
for (const { agentId, personIds } of lost) conditions.push({ agentId, userId: { in: personIds } })
for (const group of before.conversations) {
const current = groups.get(group.id)
if (!current || (current.archived && !group.archived)) conditions.push({ conversationId: group.id })
// The removed Leads conversation is nobody's to read (model.ts leadsRemoved), so whoever read a group that turns into one loses it.
else {
for (const member of after.people) {
const reader = { kind: 'person' as const, userId: member.id, email: member.email }
if (canReadGroup(before, reader, group) && !canReadGroup(after, reader, current)) conditions.push({ conversationId: group.id, userId: member.id })
}
const removed = group.agentIds.filter(id => !current.agentIds.includes(id))
if (removed.length) conditions.push({ conversationId: group.id, agentId: { in: removed } })
}
}
return { conditions, watchersLost: lost }
}