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.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
/**
* 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)
})
})