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
// GitHub events on an open task's pull request reach the task's Engineer directly (Dee, #1891, from DeepSeek's Super-agent):
// CI failed or passed, a review or comment, a merge conflict, each once, without waiting for the PM's 30-minute sync. No
// webhook reaches the backend, so the singleton worker reads them every minute with the Harness GitHub App
// (docs/plans/2026-11-03-pr-events-to-engineer-plan.md).
import type { PrismaClient } from '@prisma/client'
import { PULL_PATCH_PERMISSIONS, PULL_WATCH_PERMISSIONS, type GitHubApp } from '../github/app.js'
import { githubRepository, type GitHubRepository } from '../github/repository.js'
import type { SuperTabStore } from './store.js'
import type { PullRequestHead } from './model.js'
import { cleanMainMergeOf } from './mergeCarry.js'
import { patchId } from './pullRequestPatch.js'
import { watchedLinks } from './checkVerdicts.js'
import { logger } from '../utils/logger.js'
/** What GitHub says of one pull request, as the watch reads it (github/app.ts watchPullRequest). */
export interface PullRequestWatch {
url: string
number: number
state: 'open' | 'closed'
/** True once GitHub says it merged: a closed pull request without it was closed unmerged (task #3953). */
merged?: true
draft: boolean
/** The head commit's SHA. */
head: string
/** The branch it merges into. */
base: string
/** False on a merge conflict; null while GitHub is still working it out. */
mergeable: boolean | null
/** The head's latest check run of each name. */
checkRuns: Array<{ name: string; status: string; conclusion: string | null; completedAt: number | null }>
/** The head's check suites, with how many check runs each has. */
checkSuites: Array<{ status: string; runs: number }>
/** Each with its author's tie to the repository, GitHub's author_association (OWNER, MEMBER, COLLABORATOR, NONE...). */
reviews: Array<{ id: number; login: string; association: string; state: string; body: string; url: string }>
comments: Array<{ id: number; login: string; association: string; body: string; url: string }>
}
/** One message for the Engineer, and the key it is posted under once. */
export interface PullRequestEvent { key: string; text: string }
export const FAILED = new Set(['failure', 'timed_out', 'cancelled', 'action_required', 'startup_failure'])
const PASSED = new Set(['success', 'neutral', 'skipped'])
/** The keys a group keeps per pull request: its marks, and its newest heads' CI and conflict keys. */
export const SEEN_KEPT = 50
const QUOTE = 300
/** Whether every check run of [watch]'s head is done and passed, and every suite that has runs is done: nothing left to wait for. */
const settledGreen = (watch: PullRequestWatch): boolean => {
const suites = watch.checkSuites.filter(suite => suite.runs > 0)
return watch.checkRuns.length > 0 && suites.length > 0 && suites.every(suite => suite.status === 'completed')
&& watch.checkRuns.every(run => run.status === 'completed' && !!run.conclusion && PASSED.has(run.conclusion))
}
/** What a task's pull request shows the board (Conversation.pullRequestChecks, task #3827): `red` once a check failed, `green`
* when everything is done and passed (the rule that posts "CI passed"), else `running`: a draft, checks still going, or none read. */
export type ChecksState = 'green' | 'red' | 'running'
export function checksStateOf(watch: PullRequestWatch): ChecksState {
if (watch.draft) return 'running'
if (watch.checkRuns.some(run => !!run.conclusion && FAILED.has(run.conclusion))) return 'red'
return settledGreen(watch) ? 'green' : 'running'
}
const short = (sha: string) => sha.slice(0, 7)
const quoted = (body: string) => {
const text = body.trim().replace(/\s+/g, ' ')
return text.length > QUOTE ? `${text.slice(0, QUOTE - 1)}…` : text
}
const REVIEWED: Record<string, string> = { CHANGES_REQUESTED: 'asked for changes on', APPROVED: 'approved' }
/** Whose words reach the Engineer: the repository's own people. Anyone can comment on a public pull request, and the line
* reaches an agent as its Lead's, so anyone else's text stays on GitHub behind the link (AGENTS.md standard 7, review of #2750). */
const QUOTED = new Set(['OWNER', 'MEMBER', 'COLLABORATOR'])
const said = (association: string, body: string, url: string) => {
if (!body.trim()) return `. ${url}`
return QUOTED.has(association) ? `: "${quoted(body)}" ${url}` : `: ${url}`
}
/**
* What is new in [watch] since the keys in [seen], and the keys to keep from now on. The first read of a pull request
* ([seen] empty) records what is already there and posts only a merge conflict, which still needs acting on. Nothing from
* [botLogin], the app's own account, which the Engineer's own comments go out as. While a draft, no CI: a pull request read
* as a draft (`draft`), whatever its head, is marked when next read as ready (`ready:<ms>`), and a failure finished before
* that was a draft's own run, still the latest of its name until the ready run starts (review of #2750: a push and Ready
* in the same minute leave the new head never read as a draft). Reviews and comments are told by their ids: one newer than
* the highest seen of its kind (`review>:<id>`, `comment>:<id>`) is new, however many came before (review of #2750).
*/
export function pullRequestEvents(watch: PullRequestWatch, seen: readonly string[], botLogin: string | null, now: number): { events: PullRequestEvent[]; keys: string[] } {
const first = seen.length === 0, known = new Set(seen), events: PullRequestEvent[] = [], found: string[] = []
const { url, number, head } = watch
const add = (key: string, text: string, post = !first) => {
found.push(key)
if (!known.has(key) && post) events.push({ key, text })
}
const readyMark = seen.find(key => key.startsWith('ready:'))
if (watch.draft) found.push('draft')
else {
// Ready since a draft read: from now, unless it was ready already. On the first read everything there is recorded.
const readyAt = known.has('draft') ? now : readyMark ? Number(readyMark.slice('ready:'.length)) : null
if (readyAt !== null) found.push(`ready:${readyAt}`)
const since = !first && readyAt !== null ? readyAt : -Infinity
const failing = (run: PullRequestWatch['checkRuns'][number]) => !!run.conclusion && FAILED.has(run.conclusion)
const failed = watch.checkRuns.filter(run => failing(run) && (run.completedAt ?? now) >= since)
const stale = watch.checkRuns.some(run => failing(run) && (run.completedAt ?? now) < since)
if (failed.length) add(`ci-red:${head}`, `CI failed on your pull request #${number} (head ${short(head)}): ${failed.map(run => run.name).join(', ')}. ${url}`)
if (!failed.length && !stale && settledGreen(watch)) {
add(`ci-green:${head}`, `CI passed on your pull request #${number} (head ${short(head)}). ${url}`)
}
}
if (watch.mergeable === false) {
add(`conflict:${head}`, `Your pull request #${number} has a merge conflict with ${watch.base} (head ${short(head)}): merge ${watch.base} into its branch and push. ${url}`, true)
}
const highest = (kind: string) => Math.max(0, ...seen.filter(key => key.startsWith(`${kind}>:`)).map(key => Number(key.slice(kind.length + 2))))
const reviewed = highest('review'), commented = highest('comment')
for (const review of watch.reviews) {
if (review.login === botLogin || review.id <= reviewed) continue
add(`review:${review.id}`, `${review.login} ${REVIEWED[review.state] ?? 'reviewed'} your pull request #${number}${said(review.association, review.body, review.url)}`)
}
for (const comment of watch.comments) {
if (comment.login === botLogin || comment.id <= commented) continue
add(`comment:${comment.id}`, `${comment.login} commented on your pull request #${number}${said(comment.association, comment.body, comment.url)}`)
}
// The marks stand for the pull request as it is now and always stay; then its newest CI and conflict keys. A review's or
// comment's own key is only its message's: the marks say it was told.
const marks = [...found.filter(key => key === 'draft' || key.startsWith('ready:')),
`review>:${Math.max(reviewed, ...watch.reviews.map(r => r.id))}`, `comment>:${Math.max(commented, ...watch.comments.map(c => c.id))}`]
const told = (key: string) => /^(ci-red|ci-green|conflict):/.test(key)
const kept = [...new Set([...found, ...seen])].filter(told).slice(0, SEEN_KEPT - marks.length)
return { events, keys: [...marks, ...kept] }
}
/** What a pass asks GitHub: a pull request's watch (null: it cannot say), the patch id of its files at a new head (null: it
* cannot say, pullRequestPatch.ts), the app's own login, and `done` once it is over. */
export interface PullRequestReader {
watch(url: string): Promise<PullRequestWatch | null>
/** [base]: the branch the watch read it merging into; no id when GitHub's answer for the comparison names another. */
patch(url: string, head: string, base: string): Promise<string | null>
/** The head whose verdicts [head] carries, when it is git's own merge of that head and a commit of [base] (mergeCarry.ts,
* task #3553), else null: judged from GitHub's comparisons, never from what the pull request says. */
merge(url: string, head: string, base: string): Promise<string | null>
botLogin(): Promise<string | null>
done(): Promise<void>
}
const PULL = /^https:\/\/github\.com\/([^/]+\/[^/]+)\/pull\/([1-9][0-9]*)$/
/** A task quiet this long is not watched: its Engineer is not waiting on its pull request. */
export const WATCH_QUIET_MS = 7 * 24 * 3_600_000
/** The most tasks a pass reads, the most recently active first (AGENTS.md standard 4: no read grows without a bound). */
export const WATCH_GROUPS = 200
/** The most done tasks a pass also reads for their heads (#3394): done before the PM merges, their verdicts must still go
* stale on a push, however long the pull request stays open. Production had 31 with links, 11 quiet over a week, of 51
* finished, unarchived groups in all (2026-11-05). */
export const WATCH_DONE_GROUPS = 100
/** A head whose patch GitHub could not give is asked again after this long, not every pass. */
export const PATCH_RETRY_MS = 15 * 60_000
/** Whether a pass reads [watch]'s patch id: a head new to the task, or one GitHub could not give a patch for PATCH_RETRY_MS ago.
* A new base branch is read again like a new head (security review of #3218, round 3): the id names the branch. */
const patchNeeded = (known: PullRequestHead | undefined, watch: PullRequestWatch, now: number) =>
known?.head !== watch.head || known.base !== watch.base || (known.patch === null && now - known.at >= PATCH_RETRY_MS)
// Open again after it was read closed: the task's steps are loaded to count their verdicts at it once more (task #3953).
|| known.closed === true
/** Reads with the Harness GitHub App: one read-only token per repository for the whole pass, revoked when it is done (as the
* archive pass's, archive.ts). A repository the app is not installed on, or any GitHub failure, reads as null. */
export function appPullRequestWatch(app: GitHubApp): PullRequestReader {
// One token per repository and permission set: the watch's, and the patch reads' with contents read (PULL_PATCH_PERMISSIONS).
const tokens = new Map<string, Promise<string | null>>()
const token = (repository: GitHubRepository, permissions: typeof PULL_WATCH_PERMISSIONS | typeof PULL_PATCH_PERMISSIONS) => {
const key = `${repository.fullName.toLowerCase()} ${Object.keys(permissions).sort().join(',')}`
if (!tokens.has(key)) tokens.set(key, (async () => {
const installation = await app.installation(repository)
return installation === null ? null : (await app.createToken(installation, repository, permissions)).token
})().catch(() => null))
return tokens.get(key)!
}
const read = async <T>(url: string, permissions: typeof PULL_WATCH_PERMISSIONS | typeof PULL_PATCH_PERMISSIONS,
body: (repository: GitHubRepository, number: number, granted: string) => Promise<T | null>) => {
const match = PULL.exec(url), repository = match ? githubRepository(`https://github.com/${match[1]}`) : null
const granted = repository ? await token(repository, permissions) : null
return granted ? body(repository!, Number(match![2]), granted) : null
}
return {
watch: url => read(url, PULL_WATCH_PERMISSIONS, (repository, number, granted) => app.watchPullRequest(repository, number, granted)),
// The files at [head], from the comparison of the commits the pull request names: none once it names another head.
// Against the base the watch saw (review of #3218, round 5): a retarget between the two reads gives no id, so a patch hashed
// against one branch is never recorded under another; it is read again later.
patch: (url, head, base) => read(url, PULL_PATCH_PERMISSIONS, async (repository, number, granted) => {
const read = await app.pullRequestPatchFiles(repository, number, granted, head)
return read && read.base === base ? patchId(read.files, read.base) : null
}),
// Whether the head is git's own merge of its first parent and main, against the base the watch saw: an answer naming
// another branch carries nothing.
merge: (url, head, base) => read(url, PULL_PATCH_PERMISSIONS, async (repository, number, granted) => {
const read = await app.mainMergeSides(repository, number, granted, head)
return read && read.base === base ? cleanMainMergeOf(read.sides) : null
}),
botLogin: () => app.botLogin(),
async done() {
for (const granted of tokens.values()) {
const value = await granted
if (value) await app.revoke(value).catch(() => {})
}
tokens.clear()
},
}
}
/**
* One pass: open tasks (not steps) active in the last [WATCH_QUIET_MS] that link a pull request, at most [limit] of them, the
* most recently active first, have each open one read once, and what is new goes to its Engineer (store.ts
* pullRequestSeen). One group's failure is logged and skips that group alone. A pass that posted, or could not read a pull
* request, says so in one line: the measure of this feature (AGENTS.md standards 6 and 8). The messages posted.
*/
export async function watchPullRequests(db: PrismaClient, store: Pick<SuperTabStore, 'pullRequestSeen' | 'pullRequestHeadsWatched' | 'pullRequestClosed'>, reader: PullRequestReader, now: number,
limit = WATCH_GROUPS, doneLimit = WATCH_DONE_GROUPS): Promise<number> {
try {
// The finished mark's index, [workFinished, archived, lastActivityAt]: equality, equality, then the range, which also
// gives the sort; the rest filters what it fetches. A step's reviewOf is a string and a task has none (null matches it).
// Open tasks, then done ones, each read by that index (#3394: a done task's pull request is not merged yet, and its verdicts
// must go stale on a push however long it waits: no activity range, as only finished, unarchived groups match).
const since = { lastActivityAt: { $gte: { $date: new Date(now - WATCH_QUIET_MS).toISOString() } } }
const read = (workFinished: boolean, cap: number, more: Record<string, unknown> = {}) => cap <= 0 ? Promise.resolve([]) : db.swarmGroup.aggregateRaw({ pipeline: [
{ $match: { workFinished, archived: false, ...more, deleted: false, kind: null, 'data.reviewOf': null, 'data.pullRequestUrls.0': { $exists: true } } },
{ $sort: { lastActivityAt: -1 } },
{ $limit: cap },
{ $project: { _id: 0, tabId: 1, key: 1, urls: '$data.pullRequestUrls', heads: '$data.pullRequestHeads', steps: '$data.stepIds' } },
] }) as unknown as Promise<Array<{ tabId: string; key: string; urls: string[]; heads?: Record<string, PullRequestHead> | null; steps?: string[] | null }>>
const rows = [...await read(false, limit, since), ...await read(true, doneLimit, { 'data.assignment.status': 'done' })]
if (!rows.length) return 0
const bot = await reader.botLogin()
// One read per pull request a pass, however many tasks link it.
const reads = new Map<string, Promise<PullRequestWatch | null>>()
const watchOf = (url: string) => { if (!reads.has(url)) reads.set(url, reader.watch(url).catch(() => null)); return reads.get(url)! }
// A patch id is read only for a head the task has not recorded yet, or whose patch GitHub could not give PATCH_RETRY_MS ago
// (#3394), once a pass whatever links it.
const patches = new Map<string, Promise<string | null>>()
const patchOf = (url: string, head: string, base: string) => {
const key = `${url}@${head}@${base}`
if (!patches.has(key)) patches.set(key, reader.patch(url, head, base).catch(() => null))
return patches.get(key)!
}
// Each task's newest links (watchedLinks), with their pull request as GitHub has it now and a patch where one is needed.
// A head new to a task is asked whether it is git's own merge of another head and main (#3553), once a pass.
const merges = new Map<string, Promise<string | null>>()
const mergeOf = (url: string, head: string, base: string) => {
const key = `${url}@${head}@${base}`
if (!merges.has(key)) merges.set(key, reader.merge(url, head, base).catch(() => null))
return merges.get(key)!
}
const seen: Array<{ row: typeof rows[number]; watch: PullRequestWatch; patch: string | null | undefined; merged: string | null | undefined }> = []
const closed: Array<{ row: typeof rows[number]; url: string }> = []
for (const row of rows) {
for (const url of watchedLinks(row.urls)) {
const watch = await watchOf(url)
// A pull request the watch read before and GitHub now shows closed unmerged stops capturing the task's checks (task #3953).
if (watch?.state === 'closed' && !watch.merged && row.heads?.[url] && !row.heads[url]!.closed) closed.push({ row, url })
if (watch?.state !== 'open') continue
const known = row.heads?.[url] ?? undefined, newHead = known?.head !== watch.head || known.base !== watch.base
seen.push({ row, watch, patch: patchNeeded(known, watch, now) ? await patchOf(url, watch.head, watch.base) : undefined,
merged: newHead ? await mergeOf(url, watch.head, watch.base) : undefined })
}
}
// A task whose links moved past a head it keeps (review of #3218, round 3): that head is no longer read, so it is dropped
// and the task's verdicts on it stop counting, whether or not any head it reads changed.
const moved = rows.filter(row => {
const window = new Set(watchedLinks(row.urls))
return Object.keys(row.heads ?? {}).some(url => !window.has(url))
})
// A task from before steps were listed, at a new head or dropping one: its dormant steps are looked up once, then listed.
const unlisted = [...seen.filter(s => s.patch !== undefined).map(s => s.row), ...moved, ...closed.map(c => c.row)].filter(row => !Array.isArray(row.steps))
const listed = await listedSteps(db, unlisted)
for (const row of moved) {
try {
const lookedUp = listed.get(`${row.tabId}:${row.key}`)
await store.pullRequestHeadsWatched(row.tabId, row.key, row.steps ?? lookedUp ?? [], lookedUp !== undefined)
} catch (error) {
logger.warn('[swarm-pr-events] group skipped', { tabId: row.tabId, group: row.key, error: error instanceof Error ? error.message : String(error) })
}
}
for (const { row, url } of closed) {
try {
const lookedUp = listed.get(`${row.tabId}:${row.key}`)
await store.pullRequestClosed(row.tabId, row.key, url, row.steps ?? lookedUp ?? [], lookedUp !== undefined)
} catch (error) {
logger.warn('[swarm-pr-events] group skipped', { tabId: row.tabId, group: row.key, error: error instanceof Error ? error.message : String(error) })
}
}
let posted = 0
for (const { row, watch, patch, merged } of seen) {
try {
const lookedUp = listed.get(`${row.tabId}:${row.key}`)
posted += await store.pullRequestSeen(row.tabId, row.key, watch, bot, patch, row.steps ?? lookedUp ?? [], lookedUp !== undefined, merged ?? null)
} catch (error) {
logger.warn('[swarm-pr-events] group skipped', { tabId: row.tabId, group: row.key, error: error instanceof Error ? error.message : String(error) })
}
}
const unreadable = (await Promise.all(reads.values())).filter(watch => watch === null).length
// Heads whose patch GitHub could not give: their verdicts count only at that exact head until a later read gives it.
const unpatched = (await Promise.all(patches.values())).filter(patch => patch === null).length
const line = { groups: rows.length, pulls: reads.size, unreadable, patched: patches.size, unpatched, posted }
if (unreadable || unpatched) logger.warn('[swarm-pr-events] pass', line)
else if (posted) logger.info('[swarm-pr-events] pass', line)
return posted
} finally { await reader.done() }
}
/** A task whose pull requests a command needs read now (store.ts headsReadNow): its key, its heads as recorded, its steps. */
export interface TaskHeads { key: string; heads?: Record<string, PullRequestHead> | null; steps?: string[] | null }
/**
* Reads [urls], pull requests the task [task] links, now, as a pass reads them, and records what GitHub says (store.ts
* pullRequestSeen) before the command that needs it is judged (task #3628): a verdict at the pull request's real head was not
* counted while the minute's pass had not read the push yet (#3561). The pass's own reads, its own write: the head, its patch
* when new, whether it is git's own main merge, and the events, each posted once whichever read sees it first. A closed pull
* request is left to the pass. The pull requests GitHub could not say anything of.
*/
export async function readPullRequestsNow(db: PrismaClient, store: Pick<SuperTabStore, 'pullRequestSeen'>, reader: PullRequestReader, tabId: string,
task: TaskHeads, urls: readonly string[], now: number): Promise<string[]> {
try {
const unread: string[] = []
let bot: string | null | undefined, listed: string[] | undefined
for (const url of urls) {
const watch = await reader.watch(url).catch(() => null)
if (!watch) unread.push(url)
if (watch?.state !== 'open') continue
const known = task.heads?.[url] ?? undefined, newHead = known?.head !== watch.head || known.base !== watch.base
const patch = patchNeeded(known, watch, now) ? await reader.patch(url, watch.head, watch.base).catch(() => null) : undefined
const merged = newHead ? await reader.merge(url, watch.head, watch.base).catch(() => null) : null
// A task from before steps were listed looks its dormant steps up once, as the pass does at a new head.
if (patch !== undefined && !Array.isArray(task.steps) && listed === undefined) listed = (await listedSteps(db, [{ tabId, key: task.key }])).get(`${tabId}:${task.key}`)
if (bot === undefined) bot = await reader.botLogin().catch(() => null)
await store.pullRequestSeen(tabId, task.key, watch, bot, patch, task.steps ?? listed ?? [], listed !== undefined, merged)
}
return unread
} finally { await reader.done() }
}
/** The dormant steps of [tasks] that list none (Conversation.stepIds absent: tasks from before steps were listed), by
* `tabId:key`, an empty list for one with none: one read for the pass, by the awake-groups index's tabId, dormant and
* deleted, examining a Swarm's dormant groups once (production's largest Swarm had 3,060 groups, 2026-11-05). Each task then
* lists its steps (store.ts pullRequestSeen), so this runs again only for another task from before, at its first new head.
* Awake steps need no lookup: they load with the task. */
export async function listedSteps(db: PrismaClient, tasks: ReadonlyArray<{ tabId: string; key: string }>): Promise<Map<string, string[]>> {
const listed = new Map<string, string[]>()
if (!tasks.length) return listed
for (const task of tasks) listed.set(`${task.tabId}:${task.key}`, [])
const rows = await db.swarmGroup.aggregateRaw({ pipeline: [
{ $match: { tabId: { $in: [...new Set(tasks.map(t => t.tabId))] }, dormant: true, deleted: false, 'data.reviewOf': { $in: [...new Set(tasks.map(t => t.key))] } } },
{ $project: { _id: 0, tabId: 1, key: 1, task: '$data.reviewOf' } },
] }) as unknown as Array<{ tabId: string; key: string; task: string }>
for (const step of rows) listed.get(`${step.tabId}:${step.task}`)?.push(step.key)
return listed
}
/** Runs the pass every minute in the singleton worker, one at a time. */
export function startPullRequestWatch(db: PrismaClient, store: Pick<SuperTabStore, 'pullRequestSeen' | 'pullRequestHeadsWatched' | 'pullRequestClosed'>, reader: () => PullRequestReader, everyMs = 60_000): () => void {
let running = false
const run = () => {
if (running) return
running = true
void watchPullRequests(db, store, reader(), Date.now())
.catch(error => logger.warn('[swarm-pr-events] failed', { error: error instanceof Error ? error.message : String(error) }))
.finally(() => { running = false })
}
run()
const timer = setInterval(run, everyMs)
timer.unref()
return () => clearInterval(timer)
}