Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions docs/yap.md
Original file line number Diff line number Diff line change
Expand Up @@ -245,6 +245,20 @@ what Claude Code reads. `SessionEnd` removes it.

Another agent is one more adapter like it, or none (above): a harness can call `/yap` directly.

## Handed on the board

A Rinai board hands an issue to the crew with one label, `crew`. Nothing on the web reaches the machine: the
daemon reads each running project's board once a minute (`Crew.watch`), one project per board however many
checkouts of the repo are registered. For an open issue carrying the label it reads who put it there (GitHub's
issue events, walking back from the newest page to the latest `labeled`). It takes the issue only if that login is
the one `gh` is signed in as, and only once: an issue that has ever been on the rail, a failed one included, waits
for `yap take`.

The label brings the issue onto the rail as drafts, never as started work: its title, body and comments are
whoever wrote them, so a human reads the plan and starts it. Taking the label off (or closing the issue) drops the
handed goal's drafts; anything already started is the human's to stop. A board read that is capped or fails drops
nothing. Progress goes back as it already does: claimed, commented, In review or Blocked.

## Remote

A web client (Rinai first) reaches a machine through a **relay**: the machine's daemon dials out and holds one
Expand Down
101 changes: 98 additions & 3 deletions src/crew.check.ts
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ import { Chats, rooted } from './chat'
import { Crew, ROUNDS } from './crew'
import { MAIL_MS, threadChips } from './kodrChips'
import { childEnv } from './env'
import type { AgentRunner, Tracker, Workspace } from './ports'
import type { AgentRunner, Card, Tracker, Workspace } from './ports'
import { Sessions, gitRisk, gitWhere, norm, patchFiles } from './sessions'
import { resolve } from 'node:path'
import { SqliteStore } from './store'
Expand All @@ -22,7 +22,7 @@ import { rpc } from './mcp'
const ok = { ok: true, log: '' }
const TWO = { tickets: [{ title: 'first', body: '', criteria: ['a', 'b'], deps: [] }, { title: 'second', body: '', criteria: ['a', 'b'], deps: [0] }] }

function rig(reviews: boolean[], o: { gateOk?: boolean; plan?: object; hang?: boolean; report?: string; diff?: string; landed?: string; baseBroken?: boolean } = {}) {
function rig(reviews: boolean[], o: { gateOk?: boolean; plan?: object; hang?: boolean; report?: string; diff?: string; landed?: string; baseBroken?: boolean; handed?: (Card & { by: string | null })[] | never[]; briefFails?: boolean; briefGate?: Promise<void>; handedFails?: boolean } = {}) {
let atBase = false
const store = new SqliteStore(new Database(':memory:'))
const merged: string[] = []
Expand Down Expand Up @@ -90,11 +90,22 @@ function rig(reviews: boolean[], o: { gateOk?: boolean; plan?: object; hang?: bo
const told: string[] = []
const tracker: Tracker = {
cards: async () => [{ number: 7, title: 'from the board', column: 'todo', priority: 'normal', cycle: true }],
brief: async (_r, n) => `# issue ${n}\nthe brief`,
brief: async (_r, n) => {
if (o.briefGate) told.push(`brief ${n}`)
if (o.briefFails) throw new Error('offline')
await o.briefGate
return `# issue ${n}\nthe brief`
},
file: async (_r, title) => (told.push(`file ${title}`), { number: 9, title, column: 'todo', priority: 'normal', cycle: false }),
claim: async (_r, n) => void told.push(`claim ${n}`),
move: async (_r, n, column) => void told.push(`move ${n} ${column}`),
comment: async (_r, n, text) => void told.push(`comment ${n} ${text.split('\n')[0]}`, ...(text.includes('The crew did') ? ['the reporter summary leaked'] : [])),
handed: async () => {
if (o.handedFails) throw new Error('capped')
return (o.handed ?? []).map(({ by, ...c }) => c)
},
labeler: async (_r, n) => (told.push(`events ${n}`), o.handed?.find(c => c.number === n)?.by ?? null),
me: async () => 'you',
}
const crew = new Crew(store, ws, agent, tracker, '/tmp/yap')
return { store, crew, merged, squashed, prompts, told, ws, dirty }
Expand Down Expand Up @@ -202,6 +213,90 @@ const settled = (store: SqliteStore, id: number) => until(() => store.tickets().
assert.equal(store.tickets()[0].summary, 'did the thing', 'the ticket carries its author\'s report')
}

// Handed on the board: the crew label from the person this machine works for brings the issue onto the rail as
// drafts that wait for a human. Anyone else's label is left alone, and an issue already on the rail is not taken
// twice; who labelled an unchanged issue is not read again.
{
const card = { number: 7, title: 'from the board', column: 'todo', priority: 'normal', cycle: false, updated_at: 't1' }
const { store, crew, told } = rig([true, true], { handed: [{ ...card, by: 'You' }, { ...card, number: 8, by: 'stranger' }, { ...card, number: 9, by: null }] })
await crew.openProject('.')
await crew.openProject('/elsewhere')
await crew.watch()
await until(() => store.goals()[0]?.status === 'ready')
assert.deepEqual(store.goals().map(g => g.issue), [7], 'only the issue its own person handed, in one project of the two on that board')
assert.deepEqual(store.tickets().map(t => t.status), ['draft', 'draft'], 'drafts: a human starts them')
told.length = 0
await crew.watch()
assert.equal(store.goals().length, 1, 'not taken twice')
assert.deepEqual(told.filter(t => t.startsWith('events')), [], 'an unchanged issue is not read again')
}
// A take in flight holds the issue: a manual `yap take` racing the poll does not put it on the rail twice.
{
const card = { number: 7, title: 'from the board', column: 'todo', priority: 'normal', cycle: false, by: 'you' }
let open!: () => void
const o = { handed: [card], briefGate: new Promise<void>(r => (open = r)) }
const { store, crew, told } = rig([true, true], o)
const p = await crew.openProject('.')
const polling = crew.watch()
await until(() => told.includes('brief 7'))
await assert.rejects(crew.take(p.id, 7, 'from the board'), /already on the rail/)
open()
await polling
assert.equal(store.goals().length, 1, 'one goal for one issue')
}
// A handed issue whose plan failed is not retaken every minute: `yap take` is the retry. A take that throws is
// tried again, and logged once; so is a board that can't be read whole.
{
const card = { number: 7, title: 'from the board', column: 'todo', priority: 'normal', cycle: false, by: 'you' }
const { store, crew } = rig([], { plan: { tickets: [] }, handed: [card] })
await crew.openProject('.')
await crew.watch()
await until(() => store.goals()[0]?.status === 'failed')
await crew.watch()
assert.equal(store.goals().length, 1, 'a failed plan waits for a human')

const down = rig([], { handed: [card], briefFails: true })
const q = await down.crew.openProject('.')
await down.crew.watch()
await down.crew.watch()
const tracked = () => down.store.events({ project_id: q.id }).filter(e => e.kind === 'tracker').map(e => e.data.did)
assert.deepEqual(tracked(), ['hand failed'], 'one failure line, no handed line for what was not taken')

}
{
const o = { handed: [], handedFails: true }
const { store, crew } = rig([], o)
const p = await crew.openProject('.')
await crew.watch()
await crew.watch()
assert.deepEqual(store.events({ project_id: p.id }).filter(e => e.kind === 'tracker').map(e => e.data.did), ['board unreadable'], 'said once')
}
// Taking the label off is the take back: the handed goal's drafts are dropped, and the goal with them, so a
// label put back brings it in again. A board that can't be read whole drops nothing, and an issue a human took
// with `yap take` is theirs, label or none.
{
const card = { number: 7, title: 'from the board', column: 'todo', priority: 'normal', cycle: false, by: 'you' }
const o: { handed: (typeof card)[]; handedFails?: boolean } = { handed: [card] }
const { store, crew } = rig([true, true], o)
const p = await crew.openProject('.')
await crew.watch()
await crew.take(p.id, 5, 'taken by hand')
await until(() => store.goals().every(g => g.status === 'ready') && store.tickets().length === 4)
o.handed = []
o.handedFails = true
await crew.watch()
assert.ok(store.tickets().every(t => t.status === 'draft'), 'a failed read is not a label coming off')
o.handedFails = false
await crew.watch()
const by = (issue: number) => store.tickets().filter(t => store.goals().find(g => g.id === t.goal_id)!.issue === issue).map(t => t.status)
assert.deepEqual(by(7), ['dropped', 'dropped'], 'the handed drafts go')
assert.deepEqual(by(5), ['draft', 'draft'], 'the hand-taken ones stay')
o.handed = [card]
await crew.watch()
await until(() => store.goals().filter(g => g.issue === 7).length === 2 && store.goals().every(g => g.status !== 'planning'))
assert.deepEqual(store.goals().filter(g => g.issue === 7).map(g => g.status), ['dropped', 'ready'], 'labelled again, it comes back')
}

// An author that reports BLOCKED goes to a human, not to the reviewer.
{
const { store, crew, prompts } = rig([], { report: 'Status: BLOCKED\nVerified: nothing; the API needs a key I do not have' })
Expand Down
120 changes: 114 additions & 6 deletions src/crew.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
import { homedir } from 'node:os'
import { basename, join, resolve } from 'node:path'
import type { AgentRunner, Goal, Project, Store, Ticket, Tracker, Workspace } from './ports'
import type { AgentRunner, Card, Goal, Project, Store, Ticket, Tracker, Workspace } from './ports'

/** Review rounds a ticket gets before it lands in front of a human. */
export const ROUNDS = 4
Expand Down Expand Up @@ -256,6 +256,9 @@ function receipt(t: Ticket, checks: Check[] | null, ref: string) {
].join('\n')
}

/** The label that hands an issue to the crew on a Rinai board: Rinai's "Hand to the crew" puts it there. */
export const CREW_LABEL = 'crew'

export class Crew {
private live = new Map<number, { abort: AbortController; activity: string; at: number; done: Promise<void> }>()
private gates = new Map<number, Promise<unknown>>()
Expand Down Expand Up @@ -353,17 +356,122 @@ export class Crew {
async cards(project_id: number) {
const p = await this.tracked(project_id)
if (!p.tracker) throw new Error('this repo has no GitHub remote, so there is no board to read')
const taken = new Set(this.store.goals().filter(g => g.project_id === p.id && g.status !== 'failed').map(g => g.issue))
const taken = this.onRail(p.tracker)
return (await this.tracker.cards(p.tracker)).map(c => ({ ...c, onRail: taken.has(c.number) }))
}

/** Bring a tracker issue onto the rail: the planner turns its brief into draft tickets. */
/** Issues being taken right now, `tracker#n`: claimed before the first await, so two takes can't both pass the check. */
private taking = new Set<string>()

/** Bring a tracker issue onto the rail: the planner turns its brief into draft tickets, which wait for a human. */
async take(project_id: number, issue: number, title: string) {
const p = await this.tracked(project_id)
if (!p.tracker) throw new Error('this repo has no board')
if (this.store.goals().some(g => g.project_id === p.id && g.issue === issue && g.status !== 'failed'))
throw new Error(`#${issue} is already on the rail`)
return this.plan(p.id, `#${issue} ${title}`, issue, await this.tracker.brief(p.tracker, issue))
const key = `${p.tracker}#${issue}`
if (this.taking.has(key) || this.onRail(p.tracker).has(issue)) throw new Error(`#${issue} is already on the rail`)
this.taking.add(key)
try {
return this.plan(p.id, `#${issue} ${title}`, issue, await this.tracker.brief(p.tracker, issue))
} finally {
this.taking.delete(key)
}
}

/** Issues on the rail from this board, in any project that reads it; a failed one only when asked, a taken-back one never. */
private onRail(tracker: string, failed = false) {
const ids = new Set(this.store.projects().filter(p => p.tracker === tracker).map(p => p.id))
return new Set(
this.store.goals().filter(g => ids.has(g.project_id) && g.issue !== null && g.status !== 'dropped' && (failed || g.status !== 'failed')).map(g => g.issue!),
)
}

private watching = false
private failed = new Set<string>()
/** Who labelled an issue, as of its `updated_at`: relabelling changes that, so a stale answer is never used. */
private labellers = new Map<string, { at: string; by: string | null }>()
/**
* Issues handed to the crew on the board: the `crew` label, put there by the person this machine works for. The
* board only asks; this machine decides, so a label from anyone else, or an issue that ever came onto the rail
* (a failed one included: `yap take` again is the retry), is left alone. A handed issue is planned into drafts
* that wait for a human to start them: its title, body and comments are anyone's words. Taking the label off is
* the take back: the handed goal's drafts are dropped.
*/
async watch() {
if (this.watching) return
this.watching = true
try {
const boards = new Set<string>()
for (const p of this.store.projects()) {
// One project per board: two checkouts of one repo would both read it.
if (!p.tracker || !p.running || boards.has(p.tracker)) continue
boards.add(p.tracker)
// One board failing to read leaves the others to be read. Logged once until it reads again: a board too big
// to read whole would otherwise do nothing, silently, every minute.
const key = `board ${p.tracker}`
try {
await this.watchBoard(p, p.tracker)
this.failed.delete(key)
} catch (e: any) {
if (!this.failed.has(key)) this.store.log(p.id, null, 'tracker', { did: 'board unreadable', error: String(e?.message ?? e) })
this.failed.add(key)
}
}
} finally {
this.watching = false
}
}

private async watchBoard(p: Project, tracker: string) {
// Throws on a failed or capped read: an empty answer must mean no label, never "could not tell".
const labelled = await this.tracker.handed(tracker, CREW_LABEL)
this.takeBack(p, tracker, new Set(labelled.map(c => c.number)))
const seen = this.onRail(tracker, true)
const fresh = labelled.filter(c => !seen.has(c.number))
if (!fresh.length) return
const me = (await this.tracker.me()).toLowerCase()
for (const c of fresh) {
const key = `${tracker}#${c.number}`
// A `yap take` of it is in flight: that one wins, and losing the race is not a failure.
if (this.taking.has(key)) continue
const known = this.labellers.get(key)
const by = known && c.updated_at && known.at === c.updated_at ? known.by : await this.tracker.labeler(tracker, c.number, CREW_LABEL).catch(() => undefined)
if (by === undefined) continue // could not read: ask again next minute
if (c.updated_at) this.labellers.set(key, { at: c.updated_at, by })
if (by?.toLowerCase() !== me) continue
try {
const goal = await this.take(p.id, c.number, c.title)
this.store.patchGoal(goal.id, { handed: true })
this.store.log(p.id, null, 'tracker', { did: 'handed', issue: c.number, by, goal: goal.id })
this.failed.delete(key)
} catch (e: any) {
// Tried again next minute, logged once.
if (!this.failed.has(key)) this.store.log(p.id, null, 'tracker', { did: 'hand failed', issue: c.number, error: String(e?.message ?? e) })
this.failed.add(key)
}
}
}

/**
* The label came off a handed issue (or it closed): drop that goal's drafts, and the goal with them once nothing
* of it is left, so labelling it again brings it back. Synchronous: nothing can start a draft meanwhile.
*/
private takeBack(p: Project, tracker: string, labelled: Set<number>) {
const projects = new Set(this.store.projects().filter(q => q.tracker === tracker).map(q => q.id))
// Only goals the label brought: a `yap take` of an unlabelled issue is the human's own.
const off = this.store.goals().filter(g => g.handed && g.status !== 'dropped' && projects.has(g.project_id) && g.issue !== null && !labelled.has(g.issue))
let changed = false
for (const g of off) {
const mine = this.store.tickets().filter(t => t.goal_id === g.id)
const drafts = mine.filter(t => t.status === 'draft')
for (const t of drafts) this.store.patchTicket(t.id, { status: 'dropped' })
// Still planning: its drafts are not there yet, and the next minute drops them.
const gone = g.status !== 'planning' && mine.every(t => t.status === 'draft' || t.status === 'dropped')
if (gone) this.store.patchGoal(g.id, { status: 'dropped' })
if (!drafts.length && !gone) continue
this.store.log(p.id, null, 'tracker', { did: 'taken back', issue: g.issue, dropped: drafts.map(t => t.id) })
changed = true
}
if (changed) this.changed()
}

/** A goal typed by the human, optionally filed on the tracker first so the board knows about it. */
Expand Down
13 changes: 12 additions & 1 deletion src/ports.ts
Original file line number Diff line number Diff line change
Expand Up @@ -19,12 +19,15 @@ export interface Goal {
id: number
project_id: number
text: string
status: 'planning' | 'ready' | 'failed'
/** `dropped`: handed on the board, then taken back before any of it started. */
status: 'planning' | 'ready' | 'failed' | 'dropped'
note: string
/** The tracker issue this goal came from or was filed as. */
issue: number | null
/** The issue in full, for the planner. */
brief: string
/** Brought in by the board's crew label, not by a human's `yap take`: taking the label off drops it. */
handed?: boolean
/** What the crew did, written for the person who asked, once every ticket has merged. */
summary: string
}
Expand Down Expand Up @@ -181,6 +184,8 @@ export interface Card {
column: string
priority: string
cycle: boolean
/** When the issue last changed, as the tracker says it. */
updated_at?: string
}

/** An issue board the crew can read from, file to, and report back on. */
Expand All @@ -194,6 +199,12 @@ export interface Tracker {
claim(repo: string, n: number): Promise<void>
move(repo: string, n: number, column: 'in-review' | 'blocked'): Promise<void>
comment(repo: string, n: number, text: string): Promise<void>
/** Open cards carrying `label`. Throws when the board can't be read whole: an empty answer means none. */
handed(repo: string, label: string): Promise<Card[]>
/** Who last put `label` on the issue, or null when that can't be read. */
labeler(repo: string, n: number, label: string): Promise<string | null>
/** The login the tracker acts as: the person this machine works for. */
me(): Promise<string>
}

/** The terminal multiplexer the sessions run in, when there is one: Herdr, or the Herdr app's herdr-core. */
Expand Down
Loading
Loading