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.

16.5 KB
Raw Blame
import { isBuddy, isBuddyChat } from './buddies.js'
import type { PrismaClient } from '@prisma/client'
import { ensureIndex } from '../lib/db/indexes.js'
import { activeWork, occupiesAgent, actorKey, agent, author, conversation, fail, isLeads, stableId, SuperTabError, type Actor, type Agent, type Author, type Conversation, type MessageDraft,
  type SuperTabState } from './model.js'
import { downSince, productManagerOn } from './machines.js'
import { agentProjectId, isAgentChat, NO_PROJECT, isConfidential, ledProject, onTeamAccount, ownSession, projectAgent, projectOf, readAgent, teamSessionAccess } from './projects.js'
import { redactCredentials } from './credentials.js'

/** Any agent of an agent's project, or a person with write access, reads and types in its terminal through the host of its
 * machine (spec/2026-10-23-lead-sees-agent-terminal.md; project instructions, phase 4).
 * The request and its answer live in SuperTabTerminalRequest, never in the tab state or group history, because a screen can show secrets. */
export const TERMINAL_KEYS = ['Enter', 'Esc', 'Tab', 'Up', 'Down', 'Left', 'Right', 'Ctrl-C', '0', '1', '2', '3', '4', '5', '6', '7', '8', '9'] as const
/** The host has this long to pick a request up, then this long to answer it; after either, the request fails with a plain reason. */
export const TERMINAL_PICKUP_MS = 10_000
export const TERMINAL_ANSWER_MS = 30_000
/** A sender's wait reads its request again this often even unwoken, in case the notice of its answer was lost. */
export const TERMINAL_RECHECK_MS = 5_000
/** An unread answer, which can hold a screen's secrets, is gone after this long: refused on read, and removed by a TTL index. */
export const TERMINAL_EXPIRY_MS = 120_000
/** Run by the singleton worker at startup, like the product-usage expiry indexes. */
export async function ensureTerminalExpiry(db: PrismaClient): Promise<void> {
  await ensureIndex(db, 'SuperTabTerminalRequest', { key: { createdAt: 1 }, name: 'terminal_request_expiry', expireAfterSeconds: TERMINAL_EXPIRY_MS / 1000 })
}
/** A limited agent without a shown reset time is skipped by routing for this long. */
export const LIMIT_FALLBACK_MS = 3_600_000

export type TerminalKind = 'screen' | 'input'
export type TerminalEffect =
  | { op: 'request'; id: string; kind: TerminalKind; agentId: string; machineId: string; machineOwnerId: string; harnessId: string; requesterKey: string;
    scrollback?: number; text?: string; keys?: string[] }
  | { op: 'result'; id: string; ok: boolean; text: string | null; error: string | null }
/** A stored request as the store reads it for an answer. */
export interface TerminalRequest { id: string; agentId: string; harnessId: string; kind: TerminalKind; status: 'pending' | 'claimed' | 'done' }

/** Any agent of the agent's project (project instructions, phase 4), or a person with write access who can see the agent, reads
 *  or types in its terminal; a private one stays its own machine owner's. `elsewhere`: the agent's session is confidential in
 *  another Swarm (confidential.ts). */
export function mayDrive(state: SuperTabState, actor: Actor, target: Agent, elsewhere = false, kind: TerminalKind = 'input'): void {
  // For both kinds of requester: no person or agent reads a confidential session but its own (final review, Critical 1).
  const closed = () => {
    // A Team account holding a Product Manager: every agent there is one macOS user, which reads people's chats with it,
    // so no person types in any of them (security review 2 of #2089). Nor does any agent read or type in them, but the
    // session itself and the Product Manager there, which already runs as that user (review of phase 4, task 1). They
    // talk to them in their groups' chats.
    if (onTeamAccount(state, target) && productManagerOn(state, target.machineId)) {
      if (actor.kind === 'person' && kind === 'input') {
        fail('TERMINAL_PRIVATE', `${target.displayName ?? target.name} runs in a Harness Team account that holds a Product Manager, so nobody types in it through the Swarm. Talk to it in its group's chat.`, 403)
      }
      const self = actor.kind === 'agent' ? state.agents.find(a => a.id === actor.agentId) : undefined
      const sameUser = !!self && (ownSession(actor, target) || (self.machineId === target.machineId && !!ledProject(state, self.id)))
      if (actor.kind === 'agent' && !sameUser) {
        fail('TERMINAL_PRIVATE', `${target.displayName ?? target.name} runs in a Harness Team account that holds a Product Manager, so no other agent reads or types in it through the Swarm. Talk to it in its group's chat.`, 403)
      }
    }
    // In a Harness Team account: its project's owner reads its screen, and nobody types in it (projects.ts teamSessionAccess).
    const team = teamSessionAccess(state, actor, target, elsewhere)
    if (team === 'watch' && kind === 'screen') return
    if (team) {
      fail('TERMINAL_PRIVATE', `This ${ledProject(state, target.id) ? 'Product Manager' : 'agent'} runs in a Harness Team account: nobody types in it through the Swarm, and only its project's owner reads its screen. Talk to it in its project's chat.`, 403)
    }
    // Members may watch a Lead, but only its machine's owner drives it, whether or not its session counts as private (Ken, 2026-10-28).
    if (ledProject(state, target.id) && !ownSession(actor, target)) {
      fail('TERMINAL_PRIVATE', 'Only the person whose machine runs this agent can read or type in a Product Manager’s terminal.', 403)
    }
    if (isConfidential(state, target, elsewhere) && !ownSession(actor, target)) {
      fail('TERMINAL_PRIVATE', 'Only the person whose machine runs this agent can read or type in its terminal: it holds people’s private chats with the Product Manager.', 403)
    }
  }
  if (actor.kind === 'person') {
    author(state, actor, true)
    readAgent(state, actor, target.id)
    return closed()
  }
  closed()
  if (!projectAgent(state, actor, agentProjectId(state, target))) {
    fail('FORBIDDEN', 'Only an agent of this agent’s project, or a person with write access, can read or type in its terminal.', 403)
  }
  // An agent never drives further than the person whose machine runs it, whose own sign-in speaks for it: a teammate hosting
  // an agent of a private project they cannot read would otherwise type, through it, into the project's agents on other
  // people's logins (security review S1). Agents on one login drive each other as before, and the project's coordinator keeps
  // driving its project's agents wherever it runs (it unblocks an agent stuck on a prompt). Every path checks here: the
  // request, the host's pickup (store.ts terminalRefusal) and the answer's read (store.ts terminalResult).
  if (actor.machineOwnerId === target.machineOwnerId) return
  if (ledProject(state, actor.agentId)?.id === agentProjectId(state, target)) return
  try {
    mayDrive(state, { kind: 'person', userId: actor.machineOwnerId, email: '' }, target, elsewhere, kind)
  } catch (error) {
    if (!(error instanceof SuperTabError)) throw error
    fail('FORBIDDEN', 'An agent reads or types in another agent’s terminal only where the person whose machine runs it could.', 403)
  }
}

/** The group a terminal row belongs in: the agent's active work, else its newest open project group as a member (never the
 *  Swarm-wide Leads conversation), else its project's Lead chat. */
export function currentGroup(state: SuperTabState, target: Agent): Conversation {
  // A Buddy's rows are its person's alone, in its own chat: it has no PM, and a Swarm-wide one no project (Dee, 10-31).
  const own = isBuddy(target) ? state.conversations.find(c => isBuddyChat(c) && c.agentIds.includes(target.id)) : undefined
  if (own) return own
  // The task in its hands first: an Engineer that handed a task over and took the next one is at work on that one (#3399).
  return state.conversations.find(c => occupiesAgent(c) && c.assignment!.agentId === target.id)
    ?? state.conversations.find(c => activeWork(c) && c.assignment!.agentId === target.id)
    ?? state.conversations.findLast(c => !c.archived && !isLeads(c) && !c.audience && c.agentIds.includes(target.id) && c.leadId !== target.id)
    // A Regular agent between tasks is in its own chat (agent.new, task #4116).
    ?? (target.regular ? state.conversations.find(c => isAgentChat(c) && c.agentIds.includes(target.id)) : undefined)
    ?? conversation(state, projectOf(state, agentProjectId(state, target)).leadConversationId)
}

const nameOf = (target: Agent) => target.displayName ?? target.name

/** Where a thread session's rows go: its own thread, marked as its session's and with its project, so its main Buddy never
 *  reads them and they hide once its person loses that project (buddySessions.ts; security review 2 of #2435). */
const inSessionThread = (target: Agent): Partial<MessageDraft> => target.buddySession
  ? { replyTo: target.buddySession.thread, thread: target.buddySession.thread, buddySession: true,
    ...(target.buddySession.projectId ? { buddyProject: target.buddySession.projectId } : {}) }
  : {}

export function terminalRequest(state: SuperTabState, actor: Actor, sender: Author, id: string, now: number,
  command: { type: 'agent.screen' | 'agent.input'; agentId: string; scrollback?: number; text?: string; keys?: string[] }, elsewhere = false) {
  const target = agent(state, command.agentId)
  mayDrive(state, actor, target, elsewhere, command.type === 'agent.screen' ? 'screen' : 'input')
  if (downSince(state, target, now)) fail('HOST_OFFLINE', `${nameOf(target)}’s terminal is not running or its machine is offline.`)
  const { type: _type, agentId: _agentId, ...detail } = command
  const effect: TerminalEffect = { op: 'request', id, kind: command.type === 'agent.screen' ? 'screen' : 'input', agentId: target.id,
    machineId: target.machineId, machineOwnerId: target.machineOwnerId, harnessId: target.harnessId, requesterKey: actorKey(actor), ...detail }
  if (command.type === 'agent.screen') return { effect, message: null, removed: [] }
  // The host types the exact text; the group's row never shows a credential in it, even one the cut at 200 would split.
  const typed = redactCredentials(command.text ?? '')
  const text = command.text && `\`${typed.text.length > 200 ? `${typed.text.slice(0, 199)}…` : typed.text}\``
  const shown = [text, ...command.keys ?? []].filter(Boolean).join(' + ')
  const who = sender.displayName ?? (sender.kind === 'person' ? sender.name.split('@')[0]! : sender.name)
  const message: MessageDraft = { id, conversationId: currentGroup(state, target).id, author: sender, replyTo: null, recipients: [],
    text: `${who} typed ${shown} in ${nameOf(target)}'s terminal`, source: { kind: 'terminal-input', agentId: target.id, requestId: id },
    ...inSessionThread(target) }
  return { effect, message, removed: typed.removed }
}

/** Only the host of the agent's current terminal answers, once, a request it claimed. */
export function terminalResult(state: SuperTabState, actor: Actor, request: TerminalRequest | undefined,
  command: { type: 'agent.screenResult' | 'agent.inputResult'; ok: boolean; text?: string; error?: string }): TerminalEffect {
  if (!request) fail('NOT_FOUND', 'This terminal request is unavailable.', 404)
  const target = agent(state, request.agentId)
  if (actor.kind !== 'agent' || actor.agentId !== target.id || target.harnessId !== request.harnessId) {
    fail('HOST_REQUIRED', 'Only the host of this agent’s terminal answers its requests.', 403)
  }
  if (request.kind !== (command.type === 'agent.screenResult' ? 'screen' : 'input')) fail('REQUEST_MISMATCH', 'Answer this request with its own kind of result.', 400)
  if (request.status !== 'claimed') fail('REQUEST_CLOSED', 'This terminal request is no longer waiting for an answer.')
  return { op: 'result', id: request.id, ok: command.ok, text: command.ok && request.kind === 'screen' ? command.text ?? '' : null,
    error: command.ok ? null : command.error! }
}

/** An agent that reports its work is not stopped at a usage limit: its mark goes, as when its notice does (task #2321). Its
 *  host may still be ending the episode; that end then changes nothing. */
export function workedAgain(state: SuperTabState, agentId: string): void {
  const target = state.agents.find(a => a.id === agentId)
  if (!target?.limitedUntil && !target?.alerting?.includes('limit')) return
  target.limitedUntil = null
  target.alerting = target.alerting?.filter(a => a !== 'limit')
}

/** One row per episode: a repeated observation adds nothing, and `active: false` ends the episode. No screen text goes in the row.
 * It is delivered to the agent's project Lead, in the agent's group when the Lead is there, else by a second row in the Lead's chat. */
export function terminalAlert(state: SuperTabState, actor: Actor, sender: Author, id: string, now: number,
  command: { agentId: string; alert: 'prompt' | 'limit' | 'model'; active: boolean; resetAt?: string }): MessageDraft[] {
  const target = agent(state, command.agentId)
  if (actor.kind !== 'agent' || actor.agentId !== target.id) fail('HOST_REQUIRED', 'Only the host of this agent’s terminal reports its alerts.', 403)
  const alerting = target.alerting ?? []
  if (!command.active) {
    target.alerting = alerting.filter(a => a !== command.alert)
    // The notice is gone: so is the mark, whatever time it named (task #2321: River stayed "limited" after its notice went).
    if (command.alert === 'limit') target.limitedUntil = null
    return []
  }
  if (alerting.includes(command.alert)) return []
  target.alerting = [...alerting, command.alert]
  const group = currentGroup(state, target)
  let text = `${nameOf(target)} is waiting at a prompt in its terminal.`
  const source: Record<string, unknown> = { kind: 'terminal-alert', agentId: target.id, alert: command.alert }
  if (command.alert === 'limit') {
    const reset = command.resetAt && Date.parse(command.resetAt) > now ? Date.parse(command.resetAt) : now + LIMIT_FALLBACK_MS
    target.limitedUntil = source.limitedUntil = new Date(reset).toISOString()
    // The PM's line has no time: Desktop shows `limitedUntil` in the reader's local time, next to the line.
    if (isBuddy(target) && !target.gridModel) {
      text = 'Your Buddy reached its subscription limit. Switch engine in the Buddy header to continue.'
    } else if (ledProject(state, target.id)) {
      text = `${nameOf(target)} hit a usage limit.`
      source.lead = true
    } else text = `${nameOf(target)} hit a usage limit. Routing skips it until ${target.limitedUntil.slice(11, 16)} UTC.`
  }
  // Its engine has been retrying its model for 10 minutes (2026-10-24: a Builder on a small local model retried for an
  // hour while its Lead waited on it).
  if (command.alert === 'model') text = `${nameOf(target)} can't get answers from its model: its requests keep failing.`
  // A Buddy's alert is its owner's alone, in their chat: the PM neither reads that chat nor runs the Buddy (buddies.ts).
  const chat = isBuddy(target) ? state.conversations.find(c => isBuddyChat(c) && c.agentIds.includes(target.id)) : undefined
  if (chat) return [{ id, conversationId: chat.id, author: sender, replyTo: null, recipients: [], text, source, ...inSessionThread(target) }]
  return toLead(state, target, { id, conversationId: group.id, author: sender, replyTo: null, recipients: [], text, source })
}

/** The project Lead of an agent, unless the agent is that Lead. */
export function leadOf(state: SuperTabState, target: Agent): Agent | undefined {
  // A Buddy answers to its person alone, never to a PM; a Swarm-wide one has no project (Dee, 10-31).
  if (target.buddyOf) return undefined
  // Nor does an agent in no project: a Regular one between tasks (task #4116).
  if (agentProjectId(state, target) === NO_PROJECT) return undefined
  const lead = conversation(state, projectOf(state, agentProjectId(state, target)).leadConversationId).leadId
  return lead && lead !== target.id ? state.agents.find(a => a.id === lead) : undefined
}

/** A row about an agent, delivered to its project Lead: in the row's group when the Lead is there, else by a second row in
 *  the Lead's chat. */
export function toLead(state: SuperTabState, target: Agent, row: MessageDraft): MessageDraft[] {
  if (agentProjectId(state, target) === NO_PROJECT) return [{ ...row, recipients: [] }]
  const chat = conversation(state, projectOf(state, agentProjectId(state, target)).leadConversationId)
  const lead = leadOf(state, target)?.id
  const here = !!lead && conversation(state, row.conversationId).agentIds.includes(lead)
  const first = { ...row, recipients: here ? [lead] : [] }
  return here || !lead || !chat.agentIds.includes(lead) ? [first] : [first, { ...first, id: stableId(row.id, 'lead'), conversationId: chat.id, recipients: [lead] }]
}