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.

14.2 KB
Raw Blame
import { projectPm } from './crewNeeds.js'
import { agentDisplayName } from './agentNames.js'
import { isBuddyChat } from './buddies.js'
import { activeWork, isLeads, stableId, type Assignment, type Author, type CommandEffects, type Conversation, type MessageDraft, type SuperTabState } from './model.js'
import { groupProject, projectsOf } from './projects.js'
import type { Reaction } from './reactions.js'
import { isStep } from './steps.js'
import { WINDOWS_OWED } from './osSteps.js'
import { usernameOf } from './usernames.js'

/** A task's ordinary opening message in the project chat. Its details and progress are replies; the root is never edited. */
export const TASK_LINE_KIND = 'task-line'
/** Where a task's root is, kept on its task (cards.ts GroupCards.line). A line stored before plain chat (2026-11-03) also
 *  holds state, title, builderId, answerFor and reported, which nothing reads; they go with their task when it archives, and
 *  this note can go once no open task predates 2026-11-03. */
export interface TaskLine { messageId: string; conversationId: string }

/** A task of a project with work of its own: never a step, the project chat, a Buddy chat, the Leads chat, or a private
 *  conversation (chat only: it holds no work, and its words are its own). */
function lined(chats: ReadonlySet<string>, group: Conversation): boolean {
  return !group.kind && !isLeads(group) && !isBuddyChat(group) && !isStep(group) && !group.audience && !chats.has(group.id)
}

/** Only stable linkage is on the root. State belongs to replies, never its text or visible source. */
function fields(group: Conversation): Record<string, unknown> {
  return { taskId: group.id, ...(group.number != null ? { number: group.number } : {}), title: group.title,
    ...(group.requesterId ? { requesterId: group.requesterId } : {}) }
}

/** The line's author: its project's coordinator, as the server's other notices in that chat are (tidy.ts), else whoever moved
 *  the task. */
function lineAuthor(state: SuperTabState, chat: Conversation, sender: Author | undefined): Author | undefined {
  const coordinator = chat.leadId ? state.agents.find(a => a.id === chat.leadId) : undefined
  return coordinator ? { kind: 'agent', id: coordinator.id, name: coordinator.name, displayName: agentDisplayName(state.agents, coordinator.id),
    membershipGeneration: coordinator.membershipGeneration } : sender
}

/** One line of an agent's result, ending as a sentence ends: what a thread reply quotes of it. */
function sentence(text: string | null | undefined): string {
  const first = (text ?? '').split(/\r?\n/).map(l => l.trim()).find(Boolean) ?? ''
  return !first || /[.!?。!?]$/.test(first) ? first : `${first}.`
}

/** `PR #12` for a GitHub pull request, else its link; several joined as a person would write them. */
function pullRequests(urls: readonly string[]): string {
  const names = urls.map(url => { const n = url.match(/\/pull\/(\d+)(?:[/?#]|$)/)?.[1]; return n ? `PR #${n}` : url })
  return names.length > 1 ? `${names.slice(0, -1).join(', ')} and ${names.at(-1)}` : names[0] ?? ''
}

const PULL_REQUEST = /https:\/\/github\.com\/[^\s/]+\/[^\s/]+\/pull\/\d+/g

/** What a task's reply says for its row in the chat (threads.ts): the group leaves the apps once it archives, and this stays. */
export type TaskAsk = 'on-it' | 'shipped' | 'closed'

function taskAsk(group: Conversation): TaskAsk {
  if (group.ledger?.mergedAt != null) return 'shipped'
  const status = group.assignment?.status
  if (status === 'cancelled' || status === 'stopped') return 'closed'
  return status === 'done' && !group.pullRequestUrls?.length && !group.cards?.pullRequests?.length ? 'closed' : 'on-it'
}

/** What a task's thread says when its builder stops reporting and its task is lost, and when its work is stopped. */
const stuck = (builder: string) => `Stuck: ${builder} stopped. Next: another engineer takes it over.`
const notBuilding = (assignment: Assignment) => `Not building this: ${sentence(assignment.result) || 'it was stopped.'}`

/** The thread's reply for what changed in [group] in this command, in the words Dee approved (2026-11-03), or none. */
function progress(state: SuperTabState, effects: CommandEffects, group: Conversation, previous: Conversation | undefined, pm: string): string | null {
  const cards = group.cards?.pullRequests
  const merged = cards?.length ? cards.filter(card => card.mergedAt !== undefined
    && previous?.cards?.pullRequests?.find(was => was.url === card.url)?.mergedAt === undefined).map(card => card.url) : []
  // A merge while its Windows test step waits for a Windows machine says the check is owed (osSteps.ts, task #4410).
  const owed = group.waitingWindowsStep ? ` ${WINDOWS_OWED}` : ''
  if (merged.length) return `Merged: ${pullRequests(merged)}. Ships in the next release.${owed}`
  // A merge with no card to mark is still the merge: its row has no other way to say it shipped.
  if (group.ledger?.mergedAt != null && previous?.ledger?.mergedAt == null) return `Merged: ${pullRequests(group.pullRequestUrls ?? [])}. Ships in the next release.${owed}`
  const assignment = group.assignment
  const was = previous?.assignment
  // Most tasks did not move in this command: they say nothing, and nothing more is read for them.
  if (!assignment || (was?.id === assignment.id && was.status === assignment.status)) return null
  const builder = agentDisplayName(state.agents, assignment.agentId)
  // Its agent's 👀 on the ask says it is taken (inThread), a new agent's takeover no more than that.
  if (was?.id !== assignment.id) return null
  switch (assignment.status) {
    case 'needs_human': {
      const decision = effects.decisions?.find(d => d.conversationId === group.id && d.assignmentId === assignment.id)
      // People talk only to the PM (anh Dee, 11-05; crewNeeds.ts): with a PM, a question that opened no decision for a person is
      // the PM's crew need, so its line tells nobody it is their call. The line follows the decision, as commands.ts routes by
      // who asked (review of #3223).
      if (projectPm(state, group) && !decision) return `Needs a decision: ${sentence(assignment.result) || 'a decision is needed.'} Next: ${pm} is on it.`
      const asked = assignment.askedOf && usernameOf(state, assignment.askedOf)
      const fallback = decision && decision.options[decision.recommended]
      return `${asked ? `@${asked} ` : ''}Your call: ${sentence(assignment.result) || 'a decision is needed.'}${fallback ? ` Default: ${sentence(fallback)}` : ''}`
    }
    case 'review': {
      const linked = [...new Set([...assignment.result?.match(PULL_REQUEST) ?? [], ...group.pullRequestUrls ?? []])]
        .filter(url => !group.cards?.pullRequests?.some(card => card.url === url && card.mergedAt !== undefined))
      return linked.length ? `Ready for review: ${pullRequests(linked)}` : 'Ready for review.'
    }
    case 'working': return was.status === 'review' ? `Changes needed: ${sentence(assignment.result) || 'see the review.'} ${builder} is fixing it.` : null
    case 'blocked': return `Stuck: ${sentence(assignment.result) || `${builder} cannot go on.`} Next: ${pm} is looking at it.`
    // A lost task says Stuck where it is lost, the one place that sees every loss (liveness.ts loseTask, endedReply).
    case 'cancelled': case 'stopped': return notBuilding(assignment)
    case 'done': return (group.pullRequestUrls ?? []).length || (group.cards?.pullRequests ?? []).length ? null : 'Done.'
    default: return null
  }
}

/** Whether [group] neither moved nor merged in this command: true for nearly every task on every command. */
function still(group: Conversation, previous: Conversation): boolean {
  const now = group.assignment, was = previous.assignment
  if (now?.id !== was?.id || now?.status !== was?.status || group.brief !== previous.brief) return false
  if (group.ledger?.mergedAt != null && previous.ledger?.mergedAt == null) return false
  const cards = group.cards?.pullRequests
  return !cards?.some(card => card.mergedAt !== undefined && previous.cards?.pullRequests?.find(old => old.url === card.url)?.mergedAt === undefined)
}

/** Keep task commands in their own conversation while presenting their work in one ordinary project-chat thread: its root,
 *  the brief as its first reply, then the PM's one reply per change (Dee, 2026-11-03). Agents' own posts stay in the task.
 *  Replies wake nobody. It runs on every command, so a task that did not move costs a few field reads; its chat, its author
 *  and a map of the conversations before are looked up only for one that did. */
export function syncTaskLines(before: SuperTabState, effects: CommandEffects, sender: Author | undefined, operationId: string): void {
  const state = effects.state
  // The clone keeps the order, and a command appends new conversations: a task is at its own index before, unless one was
  // removed; only then is the map built.
  let earlier: Map<string, Conversation> | undefined
  let chats: ReadonlySet<string> | undefined
  for (let index = 0; index < state.conversations.length; index++) {
    const group = state.conversations[index]!
    const same = before.conversations[index]
    const previous = same?.id === group.id ? same : (earlier ??= new Map(before.conversations.map(c => [c.id, c]))).get(group.id)
    if (previous && still(group, previous)) continue
    if (!lined(chats ??= new Set(projectsOf(state).map(p => p.leadConversationId)), group)) continue
    moved(state, effects, group, previous, sender, operationId)
  }
}

/** [group] is new, or moved in this command. A task some message asked for (a person's own, or their Buddy's proposal) replies
 *  in that message's thread; one nobody's message asked for posts nothing in the chat (Dee, 11-04, 'bot messages': a person sees
 *  only rows they wrote), and lives in Backlog and its own conversation. */
function moved(state: SuperTabState, effects: CommandEffects, group: Conversation, previous: Conversation | undefined, sender: Author | undefined,
  operationId: string): void {
  if (group.cards?.line || group.ledger?.proposal) inThread(state, effects, group, previous, sender, operationId)
}

/** [group]'s replies in the thread of the message that asked for it: its name when it opens there (several tasks may share one
 *  message), then its details and progress. */
function inThread(state: SuperTabState, effects: CommandEffects, group: Conversation, previous: Conversation | undefined, sender: Author | undefined,
  operationId: string): void {
  const line = group.cards?.line
  const chat = state.conversations.find(c => c.id === (line?.conversationId ?? groupProject(state, group).leadConversationId))
  const coordinator = chat && lineAuthor(state, chat, sender)
  if (!chat || !coordinator) return
  // Stuck names the coordinator, never the agent that is stuck when there is no coordinator to sign.
  const pm = chat.leadId && coordinator.kind === 'agent' && coordinator.id === chat.leadId ? coordinator.displayName ?? coordinator.name : 'the PM'
  const reply = (id: string, words: string, linked: Record<string, unknown> = {}) => {
    const root = group.cards!.line!.messageId
    effects.messages.push({ id, conversationId: chat.id, author: coordinator, text: words, replyTo: root, thread: root, recipients: [],
      source: { kind: 'system', ask: taskAsk(group), ...linked } })
  }
  if (!line) {
    // A proposal's root already has the proposal as its first reply.
    group.cards = { ...group.cards, line: { messageId: group.ledger!.proposal!.messageId, conversationId: chat.id } }
  } else if (!previous) {
    // Opened from a person's message (commands.ts requestOf): the thread names it, by its title alone.
    reply(stableId(operationId, 'task-named', group.id), group.title, fields(group))
  } else if (previous.brief !== group.brief && group.brief) reply(stableId(operationId, 'task-details', group.id), group.brief)
  const text = progress(state, effects, group, previous, pm)
  if (text) reply(stableId(operationId, 'task-progress', group.id), text)
  // In place of the On it / Shipped label (Dee, 11-04, 'bot messages'): its agent reacts on the ask as a teammate would, 👀 when
  // the task's work first starts and ✅ at its first merge. The store writes each as that agent's own reaction, once by its id.
  const agentId = group.assignment?.agentId
  const react = (emoji: Reaction) => {
    (effects.reactions ??= []).push({ conversationId: chat.id, messageId: group.cards!.line!.messageId, agentId: agentId!, emoji })
    chat.reactionSeq = (chat.reactionSeq ?? 0) + 1
  }
  if (agentId && !previous?.assignment && group.assignment!.status !== 'lost') react('eyes')
  if (agentId && group.ledger?.mergedAt != null && previous?.ledger?.mergedAt == null) react('check')
}

/** The thread reply of a task that ended outside any command, which syncTaskLines never sees (Diego, 2026-11-04, task #2693):
 *  lost to the liveness sweep, its machine's report or its Lead's poll (liveness.ts loseTask, the agent.alert command's too), or
 *  stopped by its host's receipt (store.ts stopped). As the command path's replies are: in its line's thread, by its project's
 *  coordinator, else [fallback], waking nobody. None for a task with no line, or whose project chat is gone. */
export function endedReply(state: SuperTabState, group: Conversation, id: string, fallback?: Author): MessageDraft[] {
  const line = group.cards?.line, assignment = group.assignment
  if (!line || !assignment) return []
  const chat = state.conversations.find(c => c.id === line.conversationId)
  const author = chat && lineAuthor(state, chat, fallback)
  if (!chat || !author) return []
  const text = assignment.status === 'lost' ? stuck(agentDisplayName(state.agents, assignment.agentId) ?? 'its engineer') : notBuilding(assignment)
  return [{ id, conversationId: chat.id, author, text, replyTo: line.messageId, thread: line.messageId, recipients: [],
    source: { kind: 'system', ask: taskAsk(group) } }]
}

/** The project chats holding the lines of [state]'s open tasks that its load left out: a store path that may end a task outside
 *  any command loads them first, so endedReply has its thread to write in. Empty on every path today, which loads every project chat. */
export function taskLineChats(state: SuperTabState): string[] {
  const loaded = new Set(state.conversations.map(c => c.id))
  return [...new Set(state.conversations.flatMap(c => activeWork(c) && c.cards?.line && !loaded.has(c.cards.line.conversationId)
    ? [c.cards.line.conversationId] : []))]
}