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.

18.4 KB
Raw Blame
/**
 * The board's pulse (task #3384, anh Dee's Swarm redesign, 11-05): what each project's PM owes and who works, from stored
 * state, shown to everyone on the board so nothing waits unseen. On 11-05 the board showed Working 0 and five people's asks
 * unanswered for 3-10 h: nothing tracked what the PM owed, and the idle checks ran only on the PM's poll.
 *
 * An owed ask is a person's message that reached the PM, kept on its conversation (`Conversation.owed`) until the PM answers
 * it in its place (a reply in its thread, or an answer right below it), explicitly reacts, or opens a task from it.
 * A project agent explicitly entrusted with an ask by the PM may also settle that ask by replying in its thread.
 * Nothing here refuses anything: a settle that finds nothing does nothing.
 */
import { isBuddy, isBuddyChat } from './buddies.js'
import { heldView, type HeldReason } from './heldReason.js'
import { fail, isLeads, type Author, type Conversation, type SuperTabState } from './model.js'
import { agentProjectId, groupProject, type SwarmProject } from './projects.js'
import { unconfirmedNote } from './processNotes.js'
import { noteTaskLines, type LinesBefore } from './statusCard.js'
import { switched } from './boardRights.js'

/** One person's message to the PM not settled yet: its id, who wrote it, when, and the root of the thread it is in (its own
 *  id for a top-level message). `delegatedTo` is the one project agent the PM entrusted with answering this ask. */
export interface OwedAsk { id: string; personId: string; at: number; thread: string; delegatedTo?: string }

/** At most this many asks are kept per conversation, the newest: a growth bound, far above what a PM leaves unanswered. */
export const MAX_OWED = 50

/** The project [group] belongs to, or none for a conversation outside every project (the removed Leads chat, a person's one
 *  Buddy chat). Never throws: the pulse is never a reason for a command to fail. */
function projectOfGroup(state: SuperTabState, group: Conversation): SwarmProject | undefined {
  if (isLeads(group) || group.kind === 'swarm-buddy') return undefined
  try { return groupProject(state, group) } catch { return undefined }
}

/** The agent leading [project]: its chat's Lead. */
export function pmOf(state: SuperTabState, project: SwarmProject): string | null {
  return state.conversations.find(c => c.id === project.leadConversationId)?.leadId ?? null
}

/** Whether asks in [group] count: a project's chat or task, never a private chat or a Buddy chat, whose words and people only
 *  their audience reads (the pulse is shown to every reader of the project). */
const counted = (group: Conversation): boolean => !group.audience && !group.kind && !isBuddyChat(group)

/** Records [message] as owed when a person wrote it and it reached [group]'s PM. */
export function owe(state: SuperTabState, group: Conversation, message: { id: string; author: Author; recipients: readonly string[]; thread: string | null; source?: unknown }, now: number): void {
  if (message.author.kind !== 'person' || (message.source && (message.source as { kind?: string }).kind !== 'buddy-proposal') || !counted(group)) return
  const project = projectOfGroup(state, group)
  const pm = project && pmOf(state, project)
  // A project switched to the Board way of working owes its PM no chat messages (boardRights.ts, task #3819).
  if (!pm || !message.recipients.includes(pm) || switched(project)) return
  group.owed = [...(group.owed ?? []).filter(ask => ask.id !== message.id), { id: message.id, personId: message.author.id, at: now, thread: message.thread ?? message.id }]
    .slice(-MAX_OWED)
}

function settle(group: Conversation, settled: (ask: OwedAsk) => boolean): void {
  if (!group.owed) return
  const left = group.owed.filter(ask => !settled(ask))
  if (left.length === group.owed.length) return
  if (left.length) group.owed = left
  else delete group.owed
}

const byPm = (state: SuperTabState, group: Conversation, agentId: string): boolean => {
  const project = projectOfGroup(state, group)
  return !!project && pmOf(state, project) === agentId
}

/** A PM's post in the Guide's task explicitly names the project-chat ask and one recipient. Free text and role names never
 *  confer this authority: membership routing remains the PM's judgment. Kept with the bounded ask until it is settled. */
export function handoffAsk(state: SuperTabState, group: Conversation, agentId: string | null, messageId: string, recipients: readonly string[]): void {
  const project = projectOfGroup(state, group)
  if (!project || !agentId || pmOf(state, project) !== agentId) fail('ASK_HANDOFF_PM', 'Only the project PM can hand off an owed ask.', 403)
  const target = recipients.length === 1 ? state.agents.find(a => a.id === recipients[0]) : undefined
  if (!target || target.id === agentId || isBuddy(target) || agentProjectId(state, target) !== project.id) {
    fail('ASK_HANDOFF_AGENT', 'Name exactly one project agent for the handoff.', 400)
  }
  const chat = state.conversations.find(c => c.id === project.leadConversationId)
  const ask = chat?.owed?.find(a => a.id === messageId)
  if (!ask) fail('ASK_NOT_OWED', 'This ask is no longer owed in the project chat.', 409)
  ask.delegatedTo = target.id
}

/** The PM's post in [group]: a reply in a thread ([thread], its root) settles every ask in that thread; an answer right below a
 *  message ([answers]) settles that message. An entrusted project agent settles only its named ask, in that ask's thread. */
export function settleReply(state: SuperTabState, group: Conversation, agentId: string, place: { answers: string | null; thread: string | null }): void {
  if (!group.owed) return
  if (byPm(state, group, agentId)) {
    settle(group, ask => ask.id === place.answers || (!!place.thread && ask.thread === place.thread))
  } else if (place.thread && group.owed.some(ask => ask.delegatedTo === agentId && ask.thread === place.thread)) {
    const target = state.agents.find(a => a.id === agentId)
    if (target && !isBuddy(target) && agentProjectId(state, target) === projectOfGroup(state, group)?.id) {
      settle(group, ask => ask.delegatedTo === agentId && ask.thread === place.thread)
    }
  }
}

/** The PM's explicit reaction on [messageId] settles it. Automatic receipt eyes never call this command path (#3663). */
export function settleReaction(state: SuperTabState, group: Conversation, agentId: string, messageId: string, on: boolean): void {
  if (!on || !group.owed || !byPm(state, group, agentId)) return
  settle(group, ask => ask.id === messageId)
}

/** [messageId], deleted by its author: nothing is left to answer, and its link would open a message that is gone. */
export function settleDeleted(group: Conversation, messageId: string): void {
  settle(group, ask => ask.id === messageId)
}

/** A task the PM opens from the person's request [messageId] in [project]'s chat settles it (commands.ts requestOf); one anyone
 *  else opens leaves the PM's answer owed (River's ruling on the review of #3209). */
export function settleRequest(state: SuperTabState, project: SwarmProject, agentId: string | null, messageId: string): void {
  const chat = state.conversations.find(c => c.id === project.leadConversationId)
  if (chat && agentId && pmOf(state, project) === agentId) settle(chat, ask => ask.id === messageId)
}


/** When each rule turns the strip red (anh Dee's brief), sent with the pulse so no app holds a threshold. */
export interface PulseLimits { askMinutes: number; idleMinutes: number; lostMinutes: number }
export const PULSE_LIMITS: PulseLimits = { askMinutes: 5, idleMinutes: 10, lostMinutes: 10 }

/** A project's pulse. `redAt`: when each rule turns red (0: already, by its nature), null while it cannot. */
export interface Pulse {
  pmId: string | null
  asks: { count: number; oldestAt: number | null; personId: string | null; list: Array<{ conversationId: string; messageId: string; personId: string; at: number }> }
  working: { count: number; crew: number; agentIds: string[] }
  nextUp: { count: number; conversationIds: string[] }
  lost: { count: number; since: number | null; conversationIds: string[] }
  held: { count: number; withoutReason: number; list: Array<{ conversationId: string; reason: string | null }> }
  idleSince: number | null
  /** The what-changed note for PMs its PM has not confirmed (processNotes.ts, task #3581), so the board shows who has not. */
  process: { noteId: string } | null
  redAt: { asks: number | null; idle: number | null; lost: number | null; held: number | null }
  limits: PulseLimits
}

const ENDED = new Set(['done', 'stopped', 'cancelled'])
const MINUTE = 60_000

/** The day [now] falls on, as a task's `notBefore` is written. */
const dayOf = (now: number): string => new Date(now).toISOString().slice(0, 10)

/** A recorded hold reason in a few words, as the strip's Held list shows it. */
export function heldWords(reason: HeldReason): string {
  switch (reason.kind) {
    case 'task': return `waits on #${reason.taskNumber}`
    case 'person': return 'waits on a person\'s answer'
    case 'reset': return `waits for a ${reason.what} reset`
    case 'requester': return 'the requester asked for later'
  }
}

/**
 * Whether [group] is held, and why (River's ruling, 11-05): its agent set blocked or needs a person, or nobody is assigned and
 * it is set for a later day. Its reason is the one recorded for the hold (#3390, heldReason.ts heldView, the one place that
 * reads it), in words; none recorded is no reason, as the board shows it. A date also says the day. ReviewPulse2 on the merge
 * with #3390: the agent's result text decided it before, a second way to decide one thing.
 */
export function holdOf(group: Conversation, today: string): { reason: string | null } | null {
  // A pause by someone who steers its project (boardRights.ts, task #3819), with its reason when one was given.
  if (group.paused) return { reason: group.paused.reason ? `paused: ${group.paused.reason}` : 'paused' }
  const assignment = group.assignment
  const dated = !assignment && !!group.notBefore && group.notBefore > today
  const stated = !!assignment && (assignment.status === 'blocked' || assignment.status === 'needs_human')
  if (!dated && !stated) return null
  const view = heldView(group)
  const words = view && view.kind !== 'none' ? heldWords(view) : null
  return { reason: words && dated ? `${words}, not before ${group.notBefore}` : words }
}

/** Whether [group] lost its agent: lost, or nobody holds it (liveness.ts `orphaned`), and since when. */
function lostSince(group: Conversation): number | null {
  const assignment = group.assignment
  if (!assignment || ENDED.has(assignment.status)) return null
  if (assignment.status === 'lost') return assignment.lost?.at ?? group.liveness?.since ?? 0
  return group.liveness?.state === 'orphaned' ? group.liveness.since : null
}

interface Counts { working: Set<string>; crew: string[]; nextUp: string[]; lost: Array<{ id: string; since: number }>; held: Array<{ conversationId: string; reason: string | null }> }

/** Each agent's project, worked out once for every project counted (agentProjectId may search the conversations). */
export const agentProjects = (state: SuperTabState): Map<string, string> => new Map(state.agents.map(a => [a.id, agentProjectId(state, a)]))

/** The Swarm's open conversations and agents by project, sorted out in one pass, so a pulse for every project costs one walk of
 *  the Swarm rather than one per project: recordPulse runs after every command (ENGINEERING 4). */
export interface PulseIndex {
  /** Each project's open tasks and steps, never its chat, a private chat or a Buddy chat. */
  work: Map<string, Conversation[]>
  /** Each project's open conversations that hold owed asks. */
  owing: Map<string, Conversation[]>
  /** Each project's agents but Buddies. */
  agents: Map<string, string[]>
}
export function pulseIndex(state: SuperTabState, projectOfAgent = agentProjects(state), only?: string): PulseIndex {
  const chats = new Set((state.projects ?? []).map(p => p.leadConversationId))
  const index: PulseIndex = { work: new Map(), owing: new Map(), agents: new Map() }
  const add = <T>(map: Map<string, T[]>, key: string, value: T) => { const list = map.get(key); if (list) list.push(value); else map.set(key, [value]) }
  for (const group of state.conversations) {
    if (group.archived || !counted(group)) continue
    const projectId = group.projectId ?? 'lead'
    if (only && projectId !== only) continue
    if (group.owed?.length) add(index.owing, projectId, group)
    if (!chats.has(group.id)) add(index.work, projectId, group)
  }
  for (const agent of state.agents) if (!isBuddy(agent)) add(index.agents, projectOfAgent.get(agent.id) ?? agentProjectId(state, agent), agent.id)
  return index
}

function countWork(state: SuperTabState, project: SwarmProject, now: number, index: PulseIndex): Counts {
  const pm = pmOf(state, project)
  const crew = (index.agents.get(project.id) ?? []).filter(id => id !== pm)
  const inCrew = new Set(crew), today = dayOf(now)
  const counts: Counts = { working: new Set(), crew, nextUp: [], lost: [], held: [] }
  for (const group of index.work.get(project.id) ?? []) {
    const assignment = group.assignment
    // Lost first: a blocked task whose agent is gone waits for an agent before anything else.
    const since = lostSince(group)
    if (since !== null) { counts.lost.push({ id: group.id, since }); continue }
    const hold = holdOf(group, today)
    if (hold) { counts.held.push({ conversationId: group.id, reason: hold.reason }); continue }
    if (!assignment) { if (!group.reviewOf) counts.nextUp.push(group.id); continue }
    if (assignment.status === 'working' && inCrew.has(assignment.agentId)) counts.working.add(assignment.agentId)
  }
  return counts
}

/** Working is 0 while work waits (Next up or lost). */
const idle = (counts: Counts): boolean => !counts.working.size && (counts.nextUp.length > 0 || counts.lost.length > 0)

/** The most of each list a stored pulse keeps (its counts stay whole): a growth bound on the project chat's part. */
export const PULSE_LIST_MAX = 50

/**
 * Works out each project's pulse and keeps it on the project's chat, where every read finds it: a change poll reads only the
 * light base (the project chats and running work, light fields: parts/light.ts), so a pulse derived at read time from it lost
 * the asks and Next up a full read showed (Hugo's review of #3209). Run where every open group is loaded, after each command
 * and on the PM's sweep, so the board reddens on time without anyone's poll. Writes only on a change. When Working fell to 0
 * while work waits is kept in it (`idleSince`) from one run to the next.
 */
export function recordPulse(state: SuperTabState, now: number, only?: string, before?: LinesBefore): void {
  // The asks of a person who left the Swarm are owed to nobody, however they left.
  const people = new Set(state.people.map(p => p.id))
  for (const group of state.conversations) if (group.owed?.some(ask => !people.has(ask.personId))) settle(group, ask => !people.has(ask.personId))
  if (!state.projects?.length) return
  // [only]: the one project a command's conversation is in, whose pulse alone it can move; every project otherwise.
  const projects = only ? state.projects.filter(p => p.id === only) : state.projects
  const index = pulseIndex(state, agentProjects(state), only), chats = new Map(state.conversations.map(c => [c.id, c]))
  for (const project of projects) {
    const chat = chats.get(project.leadConversationId)
    if (!chat) continue
    const pulse = projectPulse(state, project, now, PULSE_LIMITS, index, chat.pulse?.idleSince ?? null)
    if (JSON.stringify(pulse) !== JSON.stringify(chat.pulse)) chat.pulse = pulse
    // Each task's status line (statusCard.ts), on the task, written only where this pass moved it (task #4419): a command and the
    // Lead's sweep give the lines from before they changed anything.
    if (before) noteTaskLines(state, project, index, now, dayOf(now), before)
  }
}

/** The project of the conversation [command] names, whose pulse alone it can move; undefined for a command that names none, or
 *  a conversation outside every project, which may move any. */
export function pulseProjectOf(state: SuperTabState, command: object): string | undefined {
  const id = (command as { conversationId?: unknown }).conversationId
  const group = typeof id === 'string' ? state.conversations.find(c => c.id === id) : undefined
  return group ? projectOfGroup(state, group)?.id : undefined
}

/** [project]'s pulse as last recorded on its chat (recordPulse), or none. */
export const storedPulse = (state: SuperTabState, project: SwarmProject): Pulse | undefined =>
  state.conversations.find(c => c.id === project.leadConversationId)?.pulse

/** [project]'s pulse at [now], from what is loaded: every open group, as a command or the PM's sweep loads them. [idleBefore]:
 *  when Working fell to 0 while work waits, as last recorded. */
export function projectPulse(state: SuperTabState, project: SwarmProject, now: number, limits: PulseLimits = PULSE_LIMITS,
  index = pulseIndex(state), idleBefore: number | null = null): Pulse {
  const counts = countWork(state, project, now, index)
  const asks = (index.owing.get(project.id) ?? [])
    .flatMap(c => c.owed!.map(ask => ({ conversationId: c.id, messageId: ask.id, personId: ask.personId, at: ask.at })))
    .sort((a, b) => a.at - b.at)
  const oldest = asks[0]
  const lostAt = counts.lost.length ? Math.min(...counts.lost.map(l => l.since)) : null
  const idleSince = idle(counts) ? idleBefore ?? now : null
  const withoutReason = counts.held.filter(h => h.reason === null).length
  return {
    pmId: pmOf(state, project),
    asks: { count: asks.length, oldestAt: oldest?.at ?? null, personId: oldest?.personId ?? null, list: asks.slice(0, PULSE_LIST_MAX) },
    working: { count: counts.working.size, crew: counts.crew.length, agentIds: counts.crew.filter(id => counts.working.has(id)).slice(0, PULSE_LIST_MAX) },
    nextUp: { count: counts.nextUp.length, conversationIds: counts.nextUp.slice(0, PULSE_LIST_MAX) },
    lost: { count: counts.lost.length, since: lostAt, conversationIds: counts.lost.map(l => l.id).slice(0, PULSE_LIST_MAX) },
    held: { count: counts.held.length, withoutReason, list: counts.held.slice(0, PULSE_LIST_MAX) },
    idleSince,
    process: (note => note ? { noteId: note.id } : null)(unconfirmedNote(state, project)),
    redAt: {
      asks: oldest ? oldest.at + limits.askMinutes * MINUTE : null,
      idle: idleSince === null ? null : idleSince + limits.idleMinutes * MINUTE,
      lost: lostAt === null ? null : lostAt + limits.lostMinutes * MINUTE,
      held: withoutReason ? 0 : null,
    },
    limits,
  }
}