Agent context pack for a pull request

object

Everything needed to act on a pull request, in a single read-only payload — the PR-side twin of [`IssueContextResponse`]. Same composition-of-existing-DTOs discipline, with one deliberate exception: `files` is a *summary* shape ([`PrFileSummary`]) rather than the diff endpoint's `DiffFileResponse`, because a context pack is a map of the change, not the change. Carrying patch hunks would make the pack's size proportional to the diff; an agent that wants hunks has the repo checked out or calls `/diff`.

checks_summaryrequired

ChecksSummary

object

Roll-up of the check states for the merge box. Counted over the newest-run-per-context set (`neosource_forge::head_checks`), so a run that a re-run superseded is not a second check.

failedrequired

integerint32

`failure` + `error` states — both render red and both block.

pendingrequired

integerint32

skipped

integerint32

Checks whose job never ran (gated off by a job-level `if:`, or a `needs:` predecessor did not succeed). Counted separately from `success`; `success + failed + pending + skipped == total`.

successrequired

integerint32

Checks that ran and passed. Deliberately EXCLUDES skipped ones: a skipped check carries `state: success` so it cannot block a merge, but counting it as "passed" would tell the reader that work happened when it did not — the same claim the per-check `skipped` flag exists to stop the UI making.

totalrequired

integerint32

filesrequired

array

Per-file change summary, no patch text. Bounded — see `truncated`.

items

PrFileSummary

object

One changed file, as a shape rather than a patch.

additions

integer | null

Added lines, or `null` when the file was never line-counted — it is binary, or it exceeds the diff's per-file byte ceiling. `null` rather than `0` on purpose: those two cases are indistinguishable from "changed, but no lines added" if both report zero, and an agent that reads a 0 believes it. `is_binary` tells the two `null` reasons apart.

deletions

integer | null

Removed lines, or `null`. See [`PrFileSummary::additions`].

is_binaryrequired

boolean

`true` for a binary file. A `null` count with `is_binary: false` means the file was too large to diff, not that it has no text.

pathrequired

string

statusrequired

DiffFileStatus

head_commit

string | null

Resolved head commit the checks are derived against (40-char Git OID hex). `null` when the source branch has no resolved tip — `checks_summary` is then the zero roll-up.

linked_issuesrequired

array

Issues this PR links to (the inverse of [`IssueContextResponse::pull_requests`]). Only issues the caller can actually read: a link to an issue outside the caller's reach is omitted rather than leaked as a title.

items

IssueResponse

object

assignees

array | null

Who this issue is assigned to, resolved to handle + display name. ## Why this is on the list DTO at all, when it used to be forbidden The standing objection was N+1: assignees live in `issue_assignees`, so "serve them on the list" was read as "one query per row". **N+1 is a property of the CALL SHAPE, not of the data.** Assignees for a PAGE of issues are one statement — `WHERE issue_id = ANY($1)` over the ids the listing already selected (`PgIssueStore::assignees_for_issues`) — so the cost is one round trip per page, whatever the page size. The cost of the old answer was paid entirely by the UI: the issue list row had no assignee to render, so its assignee control had no resting value to sit on, so it shipped `sr-only` with `tabindex=-1` and a pointer user could not assign anyone from any list. Four controls were in that state for this one reason. **Serving it here costs the browser NOTHING.** It rides the list response that was already being fetched, so `issues-list.fresh` in `neosource-app/e2e/request-budget/budgets.ts` — asserted by EQUALITY — is unchanged. ## `None` is NOT "unassigned" — and the type says so `None` means this response did not run the enrichment; `Some([])` means it ran and the issue has nobody on it. An `Option` rather than the `Vec` this shipped as for one day, because the flat vec made those two states the same value and something downstream had already started reading the wrong one: the SPA's optimistic label/assignee patch matches its container BY SHAPE (`$lib/queries/issueProperties.ts`), and an always-empty `assignees: []` on the un-enriched detail DTO matched vacuously — so a row-side attach painted the DETAIL cache too, and the settle refetch silently reverted it. Invisible only because `IssueDetailBody` happens to read `labelKeys.issue(id)` instead. `Array.isArray(null)` is false, so the `Option` makes that match unrepresentable rather than unlikely (CLAUDE.md § "Convention → type"). Enrichment is a LIST-route concern: the routes that populate this are the two that render `IssueListRow` — `GET /api/repos/{owner}/{repo}/issues` and `GET /api/teams/{team_id}/issues`.

itemsIssueAssigneeResponse

author_display_name

string | null

author_github_login

string | null

Last-seen GitHub login for authors with a linked GitHub identity (always set for ghosts).

author_handle

string | null

Author fields resolved at read time (route-layer enrichment via the ghost-safe authors projection — plans/github-metadata-import.md §7). `None` on responses that don't enrich (mutation receipts) or when the account row is gone.

author_idrequired

string

author_kind

one of

• null

• AccountKind

blockedrequired

boolean

closed_at

integer | nullint64

closed_by

string | null

created_atrequired

integerint64

cycle_id

string | null

The cycle this issue is bound to, or `None` when it is in no cycle. At most one, by construction — `issues.cycle_id` is a single column (ADR 0071), and `PUT /api/issues/{issue_id}/cycle` is the only writer (`SetIssueCycleRequest`, where `cycle_id: null` unbinds). A deliberately OPEN id string like `primary_repo_id` / `team_id` beside it, not a closed enum: the value names a row, not a case. Present on every issue payload because every issue SELECT already reads the column. This doc comment used to end "Assignees and labels are per-issue SUB-RESOURCES and deliberately stay off this DTO for exactly that reason" — the reason being N+1. That was a false dichotomy and it is retracted; see [`IssueResponse::assignees`].

descriptionrequired

string

github_number

integer | nullint32

The GitHub issue number this issue mirrors, when it was imported by GitHub metadata sync (equal to `number` by construction). `None` for native issues — presence IS the provenance signal.

issue_idrequired

string

labels

array | null

Labels attached to this issue, resolved to name + colour. Same batched read, same reasoning, same `None`-vs-`Some([])` rule, and the same two routes as [`IssueResponse::assignees`].

itemsLabelResponse

numberrequired

integerint32

primary_repo_id

string | null

priorityrequired

IssuePriority

statusrequired

IssueStatus

team_idrequired

string

titlerequired

string

updated_atrequired

integerint64

pull_requestrequired

PullRequestResponse

object

author_display_name

string | null

author_github_login

string | null

Last-seen GitHub login for authors with a linked GitHub identity (always set for ghosts).

author_handle

string | null

Author fields resolved at read time (route-layer enrichment via the ghost-safe authors projection — plans/github-metadata-import.md §7), exactly as on [`crate::IssueResponse`]. Filled on every READ — list, detail, and both context packs. `None` on a mutation receipt (the caller already has the row it just wrote) or when the account row is gone.

author_idrequired

string

author_kind

one of

• null

• AccountKind

auto_merge_enabled_at

integer | nullint64

When auto-merge was armed (ms since epoch); set together with `auto_merge_enabled_by`.

auto_merge_enabled_by

string | null

Account id that armed auto-merge (merge-when-green); `null` = off. On an OPEN PR this means "will merge, as this account, the moment the merge gate reports mergeable". Cleared automatically when the head advances (new commits disarm).

change_idrequired

string

32-byte durable change identity (hex). Survives force-push / rebase.

created_atrequired

integerint64

descriptionrequired

string

draftrequired

boolean

head_commit

string | null

40-char Git OID hex of the source branch's current tip, or `null` before the first push resolves one.

merge_commit

string | null

40-char Git OID hex of the commit the merge minted, or `null` when it minted none: an import, or a merge whose source was already reachable from the target.

merge_method

one of

• null

• MergeMethod

merged_at

integer | nullint64

When the merge landed (ms since epoch). Unlike `updated_at` this never moves again, so it is the field to render as "merged <when>".

merged_by

string | null

Account credited with the merge, `null` until the PR merges — and also on a merged GitHub mirror, whose upstream merger the import payload does not carry. For a merge made with a service token this is the token's OWNER; the token itself is recorded in the operation log, not here.

merged_by_display_name

string | null

merged_by_github_login

string | null

merged_by_handle

string | null

Merger fields resolved at read time, exactly as the `author_*` group above and through the same batched projection call. `None` on a mutation receipt, on an unmerged PR, and when the account row is gone.

merged_by_kind

one of

• null

• AccountKind

merged_via

one of

• null

• MergedVia

mirror_head_repo

string | null

For a fork mirror, the GitHub `owner/name` of the fork the head lives in — a non-null value means "no local branch" (fork diff renders off the pinned OID). `null` for native PRs and same-repo mirrors.

numberrequired

integerint32

originrequired

PrOrigin

parent_pr_id

string | null

Parent PR id when this PR is part of a stack (its `target_branch` matches another open PR's `source_branch`). `None` for a non-stacked PR or for the bottom of a stack.

pr_idrequired

string

repo_idrequired

string

source_branchrequired

string

source_repo_idrequired

string

Repo the source branch lives in. Equals `repo_id` for a same-repo PR; the contributor's fork for a fork PR.

statusrequired

PullRequestStatus

target_branchrequired

string

titlerequired

string

updated_atrequired

integerint64

review_commentsrequired

array

Review comments on the PR (subject = pull request), oldest first.

items

CommentResponse

object

author_display_name

string | null

author_github_login

string | null

Last-seen GitHub login for authors with a linked GitHub identity (always set for ghosts).

author_handle

string | null

Author handle resolved at read time (route-layer enrichment via the ghost-safe authors projection); `None` if the account row could not be resolved.

author_idrequired

string

author_kind

one of

• null

• AccountKind

bodyrequired

string

comment_idrequired

string

created_atrequired

integerint64

deleted_at

integer | nullint64

editedrequired

boolean

parent_id

string | null

updated_atrequired

integerint64

review_threadsrequired

array

Inline review threads on the PR.

items

PrReviewThreadResponse

object

anchor_commitrequired

string

40-char Git OID hex of the commit the line is anchored at.

anchor_linerequired

integerint32

anchor_pathrequired

string

anchor_siderequired

ThreadSide

created_atrequired

integerint64

created_byrequired

string

outdated_at

integer | nullint64

pr_idrequired

string

resolved_at

integer | nullint64

resolved_by

string | null

thread_idrequired

string

updated_atrequired

integerint64

truncatedrequired

PrContextTruncation

object

What a context pack dropped to stay a fixed-size read. A field rather than a silent cap: a pack that quietly dropped 300 files reads exactly like a 4-file PR, and an agent acting on that is acting on a lie. Both counts are `0` on a pack that dropped nothing.

comments_omittedrequired

integer

Review comments present on the PR but absent from `review_comments`.

files_omittedrequired

integer

Changed files present in the PR but absent from `files`.