Skip to content

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.

24.1 KB
Raw Blame
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 }
}