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.0 KB
Raw Blame
/**
 * The board's pulse (task #3384, anh Dee's Swarm redesign, 11-05): what the PM owes and who works, from stored state, so
 * nothing waits unseen. On 11-05 the board showed Working 0 and five people's asks unanswered for 3-10 h because nothing
 * tracked what the PM owed and the idle checks ran only on the PM's poll.
 */
import { describe, expect, it } from 'vitest'
import type { Command, CommandContext } from './commands.js'
import type { Author } from './model.js'
import { sweepForLead } from './liveness.js'
import { projectsOf } from './projects.js'
import { recordPulse, storedPulse } from './pulse.js'
import { owner, stepsFixture } from './steps.test-support.js'
import { owedLines } from './inbox.js'

const MINUTE = 60_000
/** What a task an agent opens must say (commands.ts): at least one check, with a priority and who asked. */
const DONE_WHEN = [{ description: 'It works', independent: false }]

function setup() {
  const f = stepsFixture()
  const person: Author = { kind: 'person', id: 'owner', name: owner.email, membershipGeneration: f.state.people[0]!.generation } as Author
  /** A message in [on] by [by] (a person when null); in reply to [reply] (its thread root [thread]) or answering [answers]. */
  const post = (by: string | null, on: string, text: string, options: { reply?: string; thread?: string; answers?: string; replyAuthor?: Author; recipientIds?: string[] } = {}) => {
    const target = options.reply ?? options.answers
    const context: Partial<CommandContext> = target
      ? { reply: { id: target, conversationId: on, author: options.replyAuthor ?? person, createdAt: 0, thread: options.thread ?? target } } : {}
    const effects = f.run({ type: 'message.send', conversationId: on, text, replyTo: options.reply ?? null, recipientIds: options.recipientIds ?? [],
      ...options.answers ? { answers: options.answers } : {} } as Command, by ? f.as(by) : owner, context)
    return effects.result.messageId as string
  }
  const owed = (on = 'lead') => (f.group(on).owed ?? []).map(ask => ask.id)
  const react = (by: string, on: string, messageId: string, emoji: string, add = true) => f.run({ type: 'message.react', conversationId: on, messageId, emoji, on: add } as Command,
    f.as(by), { reaction: { messageId, reacted: false } })
  const request = (id: string) => ({ id, conversationId: 'lead', replyTo: null, source: null, author: person })
  const taskFrom = (ask: string) => f.run({ type: 'conversation.create', title: 'From the ask', brief: 'Do it.', checks: DONE_WHEN, priority: 'P2', requestMessageId: ask } as Command,
    f.as(f.lead), { request: request(ask) } as Partial<CommandContext>)
  return { f, post, owed, react, taskFrom, person, request }
}

describe('what the PM owes', () => {
  it('is a person\'s message to the PM, with who asked and when', () => {
    const { f, post } = setup()
    const ask = post(null, 'lead', 'Can the board show who is working?')
    expect(f.group('lead').owed).toEqual([{ id: ask, personId: 'owner', at: f.now, thread: ask }])
  })

  it('is not an agent\'s message, nor a person\'s to another agent', () => {
    const { f, post, owed } = setup()
    post(f.dev, 'lead', 'PR #12 is ready.')
    const line = post(f.dev, 'lead', 'Engineer here: a question for Ken.')
    // A person answering the Engineer's line in its thread talks to the Engineer, not the PM.
    post(null, 'lead', 'Use the second option.', { reply: line, replyAuthor: { kind: 'agent', id: f.dev, name: 'dev' } as Author })
    expect(owed()).toEqual([])
  })

  it('is not a message in a private chat', () => {
    const { f, post, owed } = setup()
    // An older Chat with PM: its audience is the person alone (new ones are closed, so it is written as stored).
    f.state.conversations.push({ id: 'private', title: 'Chat with PM', leadId: f.lead, agentIds: [f.lead], archived: false, brief: '', checks: [],
      assignment: null, lastMessageSequence: 0, audience: { people: [{ id: 'owner', generation: f.state.people[0]!.generation }] } } as never)
    try { post(null, 'private', 'A private question.') } catch { /* closed to new messages: nothing can be owed there either */ }
    expect(owed('private')).toEqual([])
  })

  it('is settled by the PM\'s reply in its thread, which settles the whole thread', () => {
    const { f, post, owed } = setup()
    const ask = post(null, 'lead', 'Why is Working 0?')
    const more = post(null, 'lead', 'Still nothing.', { reply: ask })
    const other = post(null, 'lead', 'And a second topic.')
    expect(owed()).toEqual([ask, more, other])
    post(f.lead, 'lead', 'Two agents start now.', { reply: more, thread: ask })
    expect(owed()).toEqual([other])
  })

  it('is settled by the PM\'s answer right below it, that message alone', () => {
    const { f, post, owed } = setup()
    const first = post(null, 'lead', 'First ask.')
    const second = post(null, 'lead', 'Second ask.')
    post(f.lead, 'lead', 'Done.', { answers: second })
    expect(owed()).toEqual([first])
  })

  it.each(['thumbs_up', 'tada', 'heart', 'laugh', 'eyes', 'check', 'rocket'])('is settled by the PM’s %s reaction without needing words', emoji => {
    const { f, post, owed, react } = setup()
    const ask = post(null, 'lead', 'The PM has more tabs than my browser 😂')
    react(f.lead, 'lead', ask, emoji)
    expect(owed()).toEqual([])
    const project = projectsOf(f.state)[0]!
    // Main's inbox also lists unread process notes (#3298): only the owed-ask lines matter here.
    expect(owedLines(f.state, project, f.now).join('\n')).not.toMatch(/Owed asks/)
    expect(storedPulse(f.state, project)!.asks.count).toBe(0)
  })

  it('lets the PM decide a question needs only a reaction, without settling its thread siblings', () => {
    const { f, post, owed, react } = setup()
    const ask = post(null, 'lead', 'Are we collecting tabs now?')
    const sibling = post(null, 'lead', 'And a second message.', { reply: ask })
    react(f.lead, 'lead', ask, 'eyes', false)
    expect(owed()).toEqual([ask, sibling])
    react(f.lead, 'lead', ask, 'eyes')
    expect(owed()).toEqual([sibling])
  })

  it('is settled by a task the PM opens from it', () => {
    const { post, owed, taskFrom } = setup()
    const ask = post(null, 'lead', 'Show unanswered asks on the board.')
    taskFrom(ask)
    expect(owed()).toEqual([])
  })

  // River's ruling on Hugo's review of #3209: only a task the PM opens from the ask settles it; one anyone else opens leaves the
  // PM's answer owed.
  it('is not settled by a task someone else opens from it', () => {
    const { f, post, owed, request } = setup()
    const ask = post(null, 'lead', 'Can we get dark mode?')
    f.run({ type: 'conversation.create', title: 'Dark mode', brief: 'Dark mode.', checks: [], requestMessageId: ask } as Command, owner,
      { request: request(ask) } as Partial<CommandContext>)
    expect(owed()).toEqual([ask])
  })

  // ReviewPulse2's review of #3209: a deleted ask has nothing left to answer, and its link would open a message that is gone.
  it('is settled when its message is deleted, kept as deleted or not', () => {
    const { f, post, owed } = setup()
    const [gone, kept] = [post(null, 'lead', 'Never mind.'), post(null, 'lead', 'Drop this too.')]
    const remove = (messageId: string, hasReplies: boolean) => f.run({ type: 'message.delete', conversationId: 'lead', messageId } as Command, owner,
      { messageChange: { messageId, author: { kind: 'person', id: 'owner' }, plain: true, deleted: false, hasFiles: false, hasReplies, text: 'x', sequence: 1 } })
    remove(gone, false)
    remove(kept, true)
    expect(owed()).toEqual([])
  })

  // River, on ReviewPulse2's review of #3209: the asks of a person who left the Swarm are owed to nobody.
  it('is settled when the person who asked leaves the Swarm', () => {
    const { f, owed } = setup()
    const peer = { kind: 'person' as const, userId: 'peer', email: '[email protected]' }
    const invited = f.run({ type: 'invite.create', email: peer.email, role: 'collaborator', conversationId: 'lead' } as Command)
    f.run({ type: 'invite.accept', inviteId: invited.result.inviteId as string } as Command, peer)
    f.run({ type: 'message.send', conversationId: 'lead', text: 'One ask before I go.', replyTo: null, recipientIds: [] } as Command, peer)
    expect(owed()).toHaveLength(1)
    f.run({ type: 'member.remove', userId: 'peer' } as Command)
    expect(owed()).toEqual([])
  })

  it('is not settled by another agent\'s reply or reaction', () => {
    const { f, post, owed, react } = setup()
    const ask = post(null, 'lead', 'Who reviews #12?')
    post(f.dev, 'lead', 'I can.', { reply: ask })
    react(f.dev, 'lead', ask, 'check')
    expect(owed()).toEqual([ask])
  })

  it('keeps the newest 50 of one chat', () => {
    const { f, post, owed } = setup()
    const asks = Array.from({ length: 55 }, (_, i) => { f.tick(MINUTE); return post(null, 'lead', `Ask ${i}.`) })
    expect(owed()).toEqual(asks.slice(5))
  })
})

describe('the pulse', () => {
  /** The pulse as the next command or sweep records it on the project's chat (state edited by hand is counted too). */
  const pulseOf = (f: ReturnType<typeof stepsFixture>) => { recordPulse(f.state, f.now); return storedPulse(f.state, projectsOf(f.state)[0]!)! }
  /** The pulse as recorded, without working it out again. */
  const stored = (f: ReturnType<typeof stepsFixture>) => storedPulse(f.state, projectsOf(f.state)[0]!)!
  /** A task the PM opens, unassigned (Next up). */
  const open = (f: ReturnType<typeof stepsFixture>, title: string, extra: { notBefore?: string } = {}) => {
    const id = f.run({ type: 'conversation.create', title, brief: `${title}.`, checks: DONE_WHEN, priority: 'P2', requesterId: 'owner' } as Command, f.as(f.lead)).result.conversationId as string
    if (extra.notBefore) f.run({ type: 'work.queue', conversationId: id, notBefore: extra.notBefore, hold: { kind: 'requester' } } as Command, f.as(f.lead))
    return id
  }
  const status = (f: ReturnType<typeof stepsFixture>, task: string, by: string, value: string, result: string | null) =>
    f.run({ type: 'work.status', conversationId: task, assignmentId: f.group(task).assignment!.id, status: value, result } as Command, f.as(by))

  it('counts the asks the PM owes, the oldest one\'s age and who asked', () => {
    const { f, post } = setup()
    const first = post(null, 'lead', 'First.')
    f.tick(4 * MINUTE)
    post(null, 'lead', 'Second.')
    const pulse = pulseOf(f)
    expect(pulse.pmId).toBe(f.lead)
    expect(pulse.asks).toMatchObject({ count: 2, oldestAt: f.now - 4 * MINUTE, personId: 'owner' })
    expect(pulse.asks.list[0]).toEqual({ conversationId: 'lead', messageId: first, personId: 'owner', at: f.now - 4 * MINUTE })
  })

  it('counts Working of the crew: agents of the project with a task they work on, never the PM', () => {
    const { f } = setup()
    const idle = f.add('idle', f.task)
    expect(pulseOf(f).working).toEqual({ count: 1, crew: 2, agentIds: [f.dev] })
    status(f, f.task, f.dev, 'review', 'PR #12')
    expect(pulseOf(f).working).toEqual({ count: 0, crew: 2, agentIds: [] })
    expect(idle).toBeTruthy()
  })

  it('counts Next up: open tasks nobody is assigned, never a step or a task set for a later day', () => {
    const { f } = setup()
    const a = open(f, 'Board strip'), b = open(f, 'Phone strip')
    f.step('Review')
    open(f, 'Later', { notBefore: '2099-01-01' })
    expect(pulseOf(f).nextUp).toEqual({ count: 2, conversationIds: [a, b] })
  })

  it('counts Lost with when the oldest lost its agent', () => {
    const { f } = setup()
    const lostAt = f.now
    f.group(f.task).assignment!.status = 'lost'
    f.group(f.task).assignment!.lost = { reason: 'its session stopped', at: lostAt }
    f.tick(3 * MINUTE)
    expect(pulseOf(f).lost).toEqual({ count: 1, since: lostAt, conversationIds: [f.task] })
  })

  // ReviewPulse2's review of the merge with #3390: a hold's reason is the one main records (heldReason.ts heldView), never the
  // agent's result text; a hold with none recorded is "no reason", as the board shows it.
  it('counts Held with the reason recorded for it: blocked or needs a person, and a task set for a later day', () => {
    const { f } = setup()
    const later = '2099-01-01T00:00:00.000Z'
    f.run({ type: 'work.status', conversationId: f.task, assignmentId: f.group(f.task).assignment!.id, status: 'blocked', result: null,
      hold: { kind: 'reset', what: 'quota', at: later } } as Command, f.as(f.dev))
    const other = open(f, 'Second')
    const builder = f.add('builder', other)
    f.run({ type: 'work.assign', conversationId: other, agentId: builder }, f.as(f.lead))
    status(f, other, builder, 'needs_human', 'Which bucket should the logs go to?')
    const dated = open(f, 'Later', { notBefore: '2099-01-01' })
    const held = pulseOf(f).held
    expect(held.count).toBe(3)
    expect(held.withoutReason).toBe(1)
    expect(held.list).toEqual([{ conversationId: f.task, reason: 'waits for a quota reset' },
      { conversationId: other, reason: null }, { conversationId: dated, reason: 'the requester asked for later, not before 2099-01-01' }])
  })

  it('turns red for a hold with no reason recorded, not for one with a reason and no words', () => {
    const { f } = setup()
    f.run({ type: 'work.status', conversationId: f.task, assignmentId: f.group(f.task).assignment!.id, status: 'blocked', result: null,
      hold: { kind: 'requester' } } as Command, f.as(f.dev))
    expect(pulseOf(f).redAt.held).toBeNull()
    status(f, f.task, f.dev, 'blocked', 'Stuck on the key, says why in words only.')
    expect(pulseOf(f).redAt.held).toBe(0)
  })

  it('counts a blocked task whose agent is gone as Lost, not Held: it waits for an agent first', () => {
    const { f } = setup()
    status(f, f.task, f.dev, 'blocked', 'Waiting for the key.')
    f.group(f.task).liveness = { state: 'orphaned', why: 'removed', since: f.now }
    expect(pulseOf(f).lost.conversationIds).toEqual([f.task])
    expect(pulseOf(f).held.count).toBe(0)
  })

  it('gives no hold to a task set for a day already here', () => {
    const { f } = setup()
    const today = open(f, 'Today', { notBefore: new Date(f.now).toISOString().slice(0, 10) })
    expect(pulseOf(f).held.count).toBe(0)
    expect(pulseOf(f).nextUp.conversationIds).toContain(today)
  })

  it('says when each red rule turns red, by the limits it sends', () => {
    const { f, post } = setup()
    expect(pulseOf(f).limits).toEqual({ askMinutes: 5, idleMinutes: 10, lostMinutes: 10 })
    expect(pulseOf(f).redAt).toEqual({ asks: null, idle: null, lost: null, held: null })
    post(null, 'lead', 'An ask.')
    const askedAt = f.now
    expect(pulseOf(f).redAt.asks).toBe(askedAt + 5 * MINUTE)
    status(f, f.task, f.dev, 'blocked', null)
    expect(pulseOf(f).redAt.held).toBe(0)
  })

  it('a lost task turns red 10 minutes after it lost its agent', () => {
    const { f } = setup()
    f.group(f.task).assignment!.status = 'lost'
    f.group(f.task).assignment!.lost = { reason: 'its session stopped', at: f.now }
    expect(pulseOf(f).redAt.lost).toBe(f.now + 10 * MINUTE)
  })

  it('marks when Working fell to 0 while work waits, and turns red 10 minutes later; work again clears it', () => {
    const { f } = setup()
    open(f, 'Waiting task')
    expect(pulseOf(f).idleSince).toBeNull()
    f.tick(MINUTE)
    status(f, f.task, f.dev, 'done', 'Merged.')
    const idleAt = f.now
    f.tick(MINUTE)
    f.run({ type: 'message.send', conversationId: 'lead', text: 'Anyone?', replyTo: null, recipientIds: [] } as Command)
    expect(stored(f).idleSince).toBe(idleAt)
    expect(stored(f).asks.count).toBe(1)
    expect(pulseOf(f).redAt.idle).toBe(idleAt + 10 * MINUTE)
    const task = pulseOf(f).nextUp.conversationIds[0]!
    f.run({ type: 'work.assign', conversationId: task, agentId: f.dev }, f.as(f.lead))
    expect(pulseOf(f).idleSince).toBeNull()
    expect(pulseOf(f).redAt.idle).toBeNull()
  })

  it('marks idle on the PM\'s sweep too, where a lost task is found', () => {
    const { f } = setup()
    f.group(f.task).assignment!.status = 'lost'
    f.group(f.task).assignment!.lost = { reason: 'its session stopped', at: f.now }
    sweepForLead(f.state, f.now)
    expect(stored(f).idleSince).toBe(f.now)
    expect(stored(f).lost.count).toBe(1)
  })
})