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.

12.5 KB
Raw Blame
/** Buddy thread sessions (docs/superpowers/specs/2026-10-30-buddy-thread-sessions-design.md; Scholes, 10-30): by the person's
 *  choice, a thread in their Buddy chat gets its own Buddy session, a second Buddy agent on the same machine, so a long
 *  question there never holds a quick one in the main chat. A session hears and answers only its thread, reads the main chat
 *  only up to where it started (a short excerpt), and ends when its person ends it, when it has been idle for 30 minutes
 *  (its host says so), or with its main Buddy. The main Buddy reads none of its thread. */
import { isBuddy, isBuddyChat, isSwarmBuddyChat } from './buddies.js'
import { canReadProject, projectsOf } from './projects.js'
import { fail, stableId, type Agent, type AgentStart, type Author, type BuddySessionEntry, type Conversation, type MessageDraft, type SuperTabState } from './model.js'

/** At most this many of the person's messages wait for a session that is still starting. */
export const MAX_SESSION_WAITING = 20
/** What a machine's host reports (`capabilities`) when it can run thread sessions. */
export const BUDDY_SESSION_CAPABILITY = 'buddySessions'
/** The main-chat excerpt a session starts from: the last CONTEXT_MESSAGES before it started, each cut to CONTEXT_CHARS, at
 *  most CONTEXT_BYTES in all. */
export const CONTEXT_MESSAGES = 10
export const CONTEXT_CHARS = 500
export const CONTEXT_BYTES = 6 * 1024
/** The quiet line a session's end leaves in its thread. */
export const SESSION_ENDED_KIND = 'buddy-session-ended'
export type SessionEndReason = 'ended' | 'idle' | 'stopped' | 'failed' | 'removed' | 'maintenance' | 'access'

export const isThreadSession = (agent: Pick<Agent, 'buddySession'> | undefined): boolean => !!agent?.buddySession
/** The chat's main Buddy: the Buddy in it that is not a thread session. */
export function mainBuddyOf(state: SuperTabState, chat: Conversation): Agent | undefined {
  return state.agents.find(a => chat.agentIds.includes(a.id) && isBuddy(a) && !a.buddySession)
}
/** The thread sessions running in [chat]. */
export const sessionAgentsOf = (state: SuperTabState, chat: Conversation): Agent[] =>
  state.agents.filter(a => chat.agentIds.includes(a.id) && isBuddy(a) && !!a.buddySession)

/**
 * [chat]'s live and starting sessions, its record pruned of any that ended without saying (its agent gone, its start failed
 * or gone): a removal path that missed the record never holds a slot. Changes [chat] only when something is pruned.
 */
export function liveSessions(state: SuperTabState, chat: Conversation): BuddySessionEntry[] {
  const entries = chat.buddySessions ?? []
  const live = entries.filter(entry => entry.agentId
    ? state.agents.some(a => a.id === entry.agentId && chat.agentIds.includes(a.id))
    : state.starts?.some(s => s.id === entry.startId && !s.error && !s.harnessId) === true)
  if (live.length !== entries.length) setSessions(chat, live)
  return live
}
export function setSessions(chat: Conversation, entries: BuddySessionEntry[]): void {
  if (entries.length) chat.buddySessions = entries
  else delete chat.buddySessions
}

/** The live or starting session of [thread] in [chat]. */
export const sessionOf = (state: SuperTabState, chat: Conversation, thread: string | null | undefined): BuddySessionEntry | undefined =>
  thread ? liveSessions(state, chat).find(e => e.thread === thread) : undefined

/** The person whose Buddy chat [chat] is, at the membership it was opened in. */
export const chatOwner = (chat: Conversation): { id: string; generation: string } | undefined => chat.audience?.people[0]

/** Refuses anyone but [chat]'s own person, at their current membership, with words that never say whose chat it is. */
export function requireChatOwner(state: SuperTabState, chat: Conversation, userId: string): { id: string; generation: string } {
  const owner = chatOwner(chat)
  const me = state.people.find(p => p.id === userId)
  if (!isBuddyChat(chat) || !owner || !me || owner.id !== me.id || owner.generation !== me.generation) {
    fail('BUDDY_SESSION_CHAT', 'Start or end a session in a thread of your own Buddy chat.', 403)
  }
  return owner
}

/** The words a session's end leaves in its thread, for its person. */
export function endedText(reason: SessionEndReason, detail?: string): string {
  switch (reason) {
    case 'ended': return 'Session ended: you ended it.'
    case 'idle': return 'Session ended: idle for 30 minutes.'
    case 'stopped': return 'Session ended: it stopped unexpectedly.'
    case 'failed': return `Session ended: it couldn't start${detail ? `: ${detail.slice(0, 300)}` : '.'}`
    case 'removed': return 'Session ended: its Buddy was removed or replaced.'
    case 'maintenance': return 'Session ended: Harness was updated. Start a new session to continue.'
    case 'access': return 'Session ended: you no longer read its project.'
  }
}

/**
 * The one way a session's end is recorded, for every path (commands, the start timeouts in liveness.ts): its entry leaves
 * [chat]'s record and a quiet line in its thread says why, to nobody (a reply to the thread's root, tagged as the session's,
 * so the main Buddy never reads it). Said by the session's agent when it ran, else by the chat's person. Closing the agent
 * itself is the caller's: only a command can (commands.ts removeAgent). Nothing when the entry is already gone.
 */
export function endSessionEntry(state: SuperTabState, chat: Conversation, entry: BuddySessionEntry, reason: SessionEndReason, detail?: string): MessageDraft[] {
  if (!(chat.buddySessions ?? []).some(e => e.startId === entry.startId)) return []
  setSessions(chat, (chat.buddySessions ?? []).filter(e => e.startId !== entry.startId))
  const agent = entry.agentId ? state.agents.find(a => a.id === entry.agentId) : undefined
  const owner = chatOwner(chat), person = owner && state.people.find(p => p.id === owner.id && p.generation === owner.generation)
  const author: Author | undefined = agent ? { kind: 'agent', id: agent.id, name: agent.name, displayName: agent.displayName ?? agent.name,
    membershipGeneration: agent.membershipGeneration } : person ? { kind: 'person', id: person.id, name: person.email, membershipGeneration: person.generation } : undefined
  if (!author) return []
  const project = entryProject(state, entry)
  return [{ id: stableId(SESSION_ENDED_KIND, chat.id, entry.startId), conversationId: chat.id, author, text: endedText(reason, detail),
    replyTo: entry.thread, recipients: [], thread: entry.thread, buddySession: true, ...(project ? { buddyProject: project } : {}),
    source: { kind: SESSION_ENDED_KIND, reason, thread: entry.thread } }]
}

/** The project [entry]'s session works in: its agent's, or its start's while it starts; none for a plain session. */
export function entryProject(state: SuperTabState, entry: Pick<BuddySessionEntry, 'agentId' | 'startId'>): string | undefined {
  return (entry.agentId ? state.agents.find(a => a.id === entry.agentId)?.buddySession?.projectId : undefined)
    ?? state.starts?.find(s => s.id === entry.startId)?.request.buddySession?.projectId
}

/** A thread session's start that failed outside a command (liveness.ts timeouts): ended through its own path, never as its
 *  main Buddy's start, so the main chat says nothing and the thread says why. */
export function failedSessionStart(state: SuperTabState, start: AgentStart): MessageDraft[] {
  const chat = start.request.buddySession && state.conversations.find(c => c.id === start.request.conversationId)
  const entry = chat ? (chat.buddySessions ?? []).find(e => e.startId === start.id) : undefined
  return chat && entry ? endSessionEntry(state, chat, entry, 'failed', start.error ?? undefined) : []
}

/** A message row as the session read check needs it: its author and source too, for a person's one Buddy chat. */
export interface SessionRow { id: string; thread?: string | null; buddySession?: boolean | null; author?: unknown; source?: unknown; buddyProject?: string | null }

/**
 * Whether a Buddy [reader] reads [row] of its own Buddy chat (spec: Security, "No session reads another's thread"). A thread
 * session reads its own thread alone (its root and replies); the main Buddy reads every row but a session thread's replies.
 * Anyone else, and any other conversation, reads as before. The one predicate every agent read of a Buddy chat applies.
 *
 * In a person's one Buddy chat (Dee, 10-31; spec: Guard and Access), with [state]: a project session reads in its thread only
 * its person's own words, its own and the line that ends it, never a main-Buddy row it was started from; and nobody, the person
 * included, reads a row of a project they no longer read (its PM's lines, its sessions' threads).
 */
export function sessionReadsRow(reader: Pick<Agent, 'id' | 'buddyOf' | 'buddySession'> | undefined, group: Pick<Conversation, 'kind' | 'audience'>,
  state?: SuperTabState): (row: SessionRow) => boolean {
  const lost = state && isSwarmBuddyChat(group) ? lostProjectRow(state, group) : () => false
  if (!reader?.buddyOf || !isBuddyChat(group)) return row => !lost(row)
  const own = reader.buddySession
  if (own?.projectId) {
    const owner = chatOwner(group as Conversation)
    return row => (row.id === own.thread || row.thread === own.thread) && !lost(row) && (ownWords(row, owner?.id, reader.id)
      || (row.source as { kind?: unknown } | null | undefined)?.kind === SESSION_ENDED_KIND
      || earlierSessionOf(row, own.projectId!))
  }
  if (own) return row => (row.id === own.thread || row.thread === own.thread) && !lost(row)
  return row => !row.buddySession && !lost(row)
}

/** Whether [row] was written by the chat's person [personId] or by the session [selfId] itself. */
function ownWords(row: SessionRow, personId: string | undefined, selfId: string): boolean {
  const author = row.author as { kind?: unknown; id?: unknown } | null | undefined
  return !!author && ((author.kind === 'person' && author.id === personId) || (author.kind === 'agent' && author.id === selfId))
}

/** Whether [row] is an agent's row of a session of [projectId] in this thread, so one reopened there has its history (Scholes,
 *  11-02). The server sets the mark on the row: a main Buddy's rows and another project's session's never carry it. */
function earlierSessionOf(row: SessionRow, projectId: string): boolean {
  return (row.author as { kind?: unknown } | null | undefined)?.kind === 'agent' && row.buddySession === true && row.buddyProject === projectId
}

/** In a person's one Buddy chat, the rows of a project its person no longer reads, or that is gone: each row of a project
 *  session's thread and each PM's private line carries its project (MessageDraft.buddyProject), and an older PM line its
 *  source's. On the row itself, so hiding has no limit (security review 2 of #2435). */
export function lostProjectRow(state: SuperTabState, group: Pick<Conversation, 'audience'>): (row: SessionRow) => boolean {
  const owner = group.audience?.people[0]
  const member = owner && state.people.find(p => p.id === owner.id && p.generation === owner.generation)
  const reads = new Map<string, boolean>()
  const readable = (projectId: string) => {
    if (!reads.has(projectId)) {
      const project = projectsOf(state).find(p => p.id === projectId)
      reads.set(projectId, !!member && !!project && canReadProject(state, { kind: 'person', userId: member.id, email: member.email }, project))
    }
    return reads.get(projectId)!
  }
  return row => {
    const marked = row.buddyProject ?? (row.source as { projectId?: unknown } | null | undefined)?.projectId
    return typeof marked === 'string' && !readable(marked)
  }
}

/** A main-chat row as the excerpt reads it. */
export interface ContextRow { id: string; sequence: number; text: string; author: { kind: string; name?: string; displayName?: string }; createdAt: Date }

/**
 * The main-chat excerpt a session starts from: [rows] (main-stream rows of its chat at or before its `from`, newest first,
 * as read), the newest CONTEXT_MESSAGES, oldest first, each cut to CONTEXT_CHARS, dropping the oldest until CONTEXT_BYTES fit.
 */
export function sessionContext(rows: readonly ContextRow[]): Array<{ id: string; sequence: number; author: string; text: string; createdAt: Date }> {
  const picked = rows.slice(0, CONTEXT_MESSAGES).map(row => ({ id: row.id, sequence: row.sequence, createdAt: row.createdAt,
    author: row.author.displayName ?? row.author.name ?? row.author.kind,
    text: [...row.text].length > CONTEXT_CHARS ? `${[...row.text].slice(0, CONTEXT_CHARS).join('')}…` : row.text })).reverse()
  const size = (list: typeof picked) => Buffer.byteLength(JSON.stringify(list.map(r => [r.author, r.text])))
  while (picked.length && size(picked) > CONTEXT_BYTES) picked.shift()
  return picked
}