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.

7.1 KB
Raw Blame
/**
 * Steps inside a task (design docs/plans/2026-11-02-task-steps-design.md). A step is a linked group (`reviewOf` names its
 * task) with a name the project's instructions give: it keeps its own assignment, lease, attempts and costs, and readers
 * show it inside its task. Nothing here reads a step's name: which steps a task has is the instructions' to say.
 */
import { agentDisplayName } from './agentNames.js'
import { activeWork, finishWorker, type Author, type Conversation, type MessageDraft, type SuperTabState } from './model.js'

/** Whether [group] is a step of a task: any linked group, named or not. Ken, 2026-11-02: a PM that opened "Test: PR #2514"
 *  the old way, a minute after saving the steps workflow, still heard every Tester post; what reaches the PM must not rest on
 *  an agent remembering the workflow. */
export const isStep = (group: Pick<Conversation, 'reviewOf'>): boolean => !!group.reviewOf

/** A step's name: the one it was opened with, else its title (a linked group opened without one). */
export const stepName = (group: Pick<Conversation, 'step' | 'title'>): string => group.step ?? group.title

/** Whether [step]'s task is done or cancelled, as far as [state] loaded it. Only then may the archive pass take a step: one
 *  archived under an open task refuses the next round, and that re-check fails silently. A task not loaded has not ended. */
export const taskEnded = (state: SuperTabState, step: Pick<Conversation, 'reviewOf'>): boolean =>
  ['done', 'cancelled'].includes(state.conversations.find(c => c.id === step.reviewOf)?.assignment?.status ?? '')

/** The most steps a task lists (Conversation.stepIds): production's most was 14 (2026-11-05). */
const STEPS_LISTED = 200
/** [task] lists its new step [id], so a new head of its pull request re-derives the step's checks even once it is dormant
 *  (#3394), however the step opened (conversation.create, or a Ready's review steps). A task from before lists none until its
 *  PR watch looks its dormant steps up (review of #3218, round 3): listing only this one would hide those. */
export function listStep(task: Conversation, id: string): void {
  if (task.stepIds) task.stepIds = [...task.stepIds, id].slice(-STEPS_LISTED)
}

/** The steps of task [taskId], in creation order. */
export const stepsOf = (state: SuperTabState, taskId: string): Conversation[] =>
  state.conversations.filter(c => c.reviewOf === taskId)

/** Ends [task]'s steps with it, in the same write. An open one is cancelled with [reason] as its result and its agent
 *  freed; it stays unarchived, as an archived conversation takes no delivery (store.ts deliveryAllowed) and its agent is
 *  told there, and it sleeps with its task. With [archive], a finished one is archived with its task: without that, a
 *  `done` step with no pull request of its own was archived within one archive pass (`settled([])`), and a second round on
 *  it failed ARCHIVED. Returns the cancelled ones, whose agents the caller tells. */
export function endSteps(state: SuperTabState, task: Conversation, reason: string, archive: boolean): Conversation[] {
  const cancelled: Conversation[] = []
  for (const step of stepsOf(state, task.id)) {
    if (step.archived) continue
    if (activeWork(step)) {
      Object.assign(step.assignment!, { status: 'cancelled', result: reason })
      finishWorker(state, step.assignment!.agentId)
      cancelled.push(step)
    } else if (archive) step.archived = true
  }
  return cancelled
}

/** The row each step endSteps cancelled keeps, in that step, for the agent whose work ended: [reason], as [author], or as that
 *  agent where none is given (a project with no Lead). One whose agent or its contributor has left the Swarm reaches nobody: a delivery to it would
 *  throw, and the archive pass that wrote it could then never archive its task. With no author either, there is no row. */
export function stepEndedRows(state: SuperTabState, cancelled: Conversation[], reason: string, author: Author | null, id: (step: Conversation) => string): MessageDraft[] {
  return cancelled.flatMap(step => {
    // agent()'s own rule, without its throw: its contributor still here, at the generation it was shared under.
    const found = state.agents.find(a => a.id === step.assignment!.agentId)
    const agent = found && state.people.find(p => p.id === found.contributorId)?.generation === found.membershipGeneration ? found : undefined
    const by: Author | null = author ?? (agent ? { kind: 'agent', id: agent.id, name: agent.name, displayName: agentDisplayName(state.agents, agent.id), membershipGeneration: agent.membershipGeneration } : null)
    return by ? [{ id: id(step), conversationId: step.id, author: by, text: reason, replyTo: null, recipients: agent ? [agent.id] : [], source: { kind: 'system' } }] : []
  })
}

/** Whether a step may sleep, given its task's row as the sweep read it (null: gone). A step sleeps once its task is
 *  archived, never on its own clock nor with a task that is only dormant: a dormant step drops out of the Swarm read with
 *  its verdict, and one asleep under a done task was not loaded when that task was archived later, so it stayed open in an
 *  archived task (final review, minor 5). */
export const stepSleeps = (task: { archived: boolean; dormant: boolean } | null): boolean => !task || task.archived
/** The agent that owns [task]: its assignee while that agent is in the Swarm, its own work done or not, else null (the
 *  coordinator's then). Ken, 2026-11-02: a Builder set its task done before its Tester's verdict, and the verdict reached
 *  the PM; the verdict is still the Builder's to act on. */
export function ownerOf(state: SuperTabState, task: Conversation): string | null {
  const agentId = task.assignment?.agentId
  return agentId && state.agents.some(a => a.id === agentId) ? agentId : null
}

/** The task's owner for [step] (ownerOf its task), or null. */
export function taskOwner(state: SuperTabState, step: Conversation): string | null {
  const task = isStep(step) ? state.conversations.find(c => c.id === step.reviewOf) : undefined
  return task ? ownerOf(state, task) : null
}

/** Whether [agentId] has held steps only, never a task, in the groups loaded, and a task one of them checks has not ended: a
 *  Reviewer or Tester the instructions keep while the work it checked is open, whatever its role is called, so its idle time
 *  is no news for the coordinator. Once each of those tasks is done or cancelled it is idle as any agent is, whether or not
 *  the task is archived yet (Diego, 2026-11-02: one sat unseen under a finished, unarchived task, holding a slot and quota).
 *  Open tasks are always loaded; a missing parent can be dormant and must not hold idle handling. Unlike taskEnded's
 *  archive guard, this decision needs no proof that an absent task ended (Diego, 2026-11-06). */
export const checksOpenWork = (state: SuperTabState, groups: readonly Conversation[], agentId: string): boolean => {
  const held = groups.filter(g => g.assignment?.agentId === agentId)
  return held.length > 0 && held.every(isStep) && held.some(step => state.conversations.some(task =>
    task.id === step.reviewOf && !['done', 'cancelled'].includes(task.assignment?.status ?? '')))
}