diff --git a/docs/yap.md b/docs/yap.md index fe51755..7b44fe9 100644 --- a/docs/yap.md +++ b/docs/yap.md @@ -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 diff --git a/src/crew.check.ts b/src/crew.check.ts index 2499f9e..395eb80 100644 --- a/src/crew.check.ts +++ b/src/crew.check.ts @@ -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' @@ -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; handedFails?: boolean } = {}) { let atBase = false const store = new SqliteStore(new Database(':memory:')) const merged: string[] = [] @@ -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 } @@ -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(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' }) diff --git a/src/crew.ts b/src/crew.ts index 451093e..7216bc5 100644 --- a/src/crew.ts +++ b/src/crew.ts @@ -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 @@ -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 }>() private gates = new Map>() @@ -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() + + /** 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() + /** Who labelled an issue, as of its `updated_at`: relabelling changes that, so a stale answer is never used. */ + private labellers = new Map() + /** + * 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() + 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) { + 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. */ diff --git a/src/ports.ts b/src/ports.ts index a4e0080..82f2ccc 100644 --- a/src/ports.ts +++ b/src/ports.ts @@ -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 } @@ -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. */ @@ -194,6 +199,12 @@ export interface Tracker { claim(repo: string, n: number): Promise move(repo: string, n: number, column: 'in-review' | 'blocked'): Promise comment(repo: string, n: number, text: string): Promise + /** Open cards carrying `label`. Throws when the board can't be read whole: an empty answer means none. */ + handed(repo: string, label: string): Promise + /** Who last put `label` on the issue, or null when that can't be read. */ + labeler(repo: string, n: number, label: string): Promise + /** The login the tracker acts as: the person this machine works for. */ + me(): Promise } /** The terminal multiplexer the sessions run in, when there is one: Herdr, or the Herdr app's herdr-core. */ diff --git a/src/rinai.ts b/src/rinai.ts index 7393124..63bafef 100644 --- a/src/rinai.ts +++ b/src/rinai.ts @@ -2,6 +2,7 @@ import type { Card, Tracker } from './ports' // A constant, as in gh-rinai: nothing an issue says can send the token anywhere else. const HOST = process.env.RINAI_URL ?? 'https://rinai.dev' +const GITHUB = 'https://api.github.com' const ORDER = ['ongoing', 'todo', 'in-review', 'blocked', 'future'] /** Rinai (rinai.dev), a board over GitHub issues. Acts as the user, through gh's own token. */ @@ -61,4 +62,39 @@ export class Rinai implements Tracker { async comment(repo: string, n: number, text: string) { await this.call('POST', `/api/${repo}/issues/${n}/comments`, text) } + + /** GitHub itself, for what Rinai does not answer: who applied a label, and who we are. */ + private async github(path: string, token?: string) { + const res = await fetch(GITHUB + path, { headers: { authorization: `Bearer ${token ?? (await this.auth())}`, 'user-agent': 'yap', accept: 'application/vnd.github+json' } }) + if (!res.ok) throw new Error(`github answered ${res.status}`) + return res + } + + async handed(repo: string, label: string) { + const body = JSON.parse(await this.call('GET', `/api/${repo}/issues?label=${encodeURIComponent(label)}`)) + // A capped board would make a label look like it came off. + if (body.truncated) throw new Error(`${repo} has more tasks than the board reads at once`) + return (body.issues as Card[]).filter(c => c.column !== 'done') + } + + async labeler(repo: string, n: number, label: string) { + // Events come oldest first and the latest `labeled` counts: walk back from the last page to the first that has one. + const path = `/repos/${repo}/issues/${n}/events?per_page=100` + const first = await this.github(path) + const pages = Number(first.headers.get('link')?.match(/[?&]page=(\d+)[^>]*>;\s*rel="last"/)?.[1] ?? 1) + for (let page = pages; page >= 1; page--) { + const events: any[] = await (page === 1 ? first : await this.github(`${path}&page=${page}`)).json() + const last = events.filter(e => e.event === 'labeled' && e.label?.name?.toLowerCase() === label.toLowerCase()).pop() + if (last) return (last.actor?.login as string | undefined) ?? null + } + return null + } + + /** Cached with the token it was read with: `gh auth switch` is a different person. */ + private login?: { token: string; login: string } + async me() { + const token = await this.auth() + if (this.login?.token !== token) this.login = { token, login: (await (await this.github('/user', token)).json()).login } + return this.login.login + } } diff --git a/src/server.ts b/src/server.ts index a233daf..85365d1 100644 --- a/src/server.ts +++ b/src/server.ts @@ -43,6 +43,10 @@ setInterval(ping, 30_000) const crew = new Crew(store, ws, new ClaudeCli(), new Rinai(), home, changed) await crew.recover() +// Tasks handed to the crew on the board. A pull, once a minute: nothing on the web can reach this machine. +const watch = () => void crew.watch().catch(() => {}) +watch() +setInterval(watch, 60_000) const sessions = new Sessions(ws, store, Date.now, new AnyPanes([new HerdrCore(), new Herdr()]), new Agents({ claude: new ClaudeCli(), codex: new CodexCli() }), () => settings().spawns) // The remote bridge, when `yap pair` left a pairing: one line out to the relay, answering what may be done from