Skip to content

feat(forge)!: read PR, claim, and wait state through a forge with a Kixel Quest backend - #753

Merged
kixelated merged 9 commits into
mainfrom
quest/m0/github-quota/forge-reads
Nov 17, 2026
Merged

kixelated merged 9 commits into
mainfrom
quest/m0/github-quota/forge-reads

Conversation

@kixelated

@kixelated kixelated commented Nov 15, 2026 •

Copy link
Copy Markdown
Collaborator

Finishes quest/m0/github-quota/forge-reads.md: quest's polled reads go through one forge interface with a GitHub backend and a Kixel Quest backend, so a person holding a Kixel Quest token stops spending their own GitHub quota on them.

Summary

  • Interface and wire format, in quest/core (src/core/forge.ts): Forge with viewer, status, pulls, held, and watch; every read answers {value, asOf}, asOf being the time of the newest webhook behind it, or null for a live read. The read types (Status, OpenPull, Holdings, ClaimSources, WaitEvent, WatchPoll, PullRequest, Repository, ...) moved here from src/github, with strict parsers for each request and answer (parseForgeRequest, parseForgeAnswer, parseForgeInfo) and forgeJson for maps. Kixel Quest's API: GET /forge → {login, repositories}, POST /forge/<read> → {value, asOf}, bearer token.
  • GitHub backend, in quest/github (GitHubForge): the existing readers, unchanged in behavior. quest wait's GitHub logic moved from src/cli/wait.ts to Worker-safe src/github/wait.ts behind a Watch handle (poll() and resume), so Kixel Quest can serve a read its index cannot answer by falling through to it, as the Plan asks. src/cli/wait.ts keeps only the poll schedule and timeout.
  • Kixel Quest backend and selection (src/cli/forge.ts): forgeFor(repository) reads through Kixel Quest when ~/.config/quest/records.json pairs a token with its URL and GET /forge lists the repository; otherwise GitHub. QUEST_FORGE=github forces GitHub; QUEST_KIXEL_URL names another Kixel Quest. Any Kixel Quest failure (network, non-2xx, refused token, malformed answer) fails the command naming QUEST_FORGE=github, except a 400 on watch, which refuses a bad --since and exits 2 as a usage error, as GitHub's backend does. A 400 on status, pulls, or held, which take no free-form argument, means the two sides disagree on the wire, so it names the override like any other failure. Until Kixel Quest first answers a wait, its resume point is --since, else the time the wait started, so a first poll that times out still prints a point a retry reports later pushes from. quest wait --timeout covers choosing the forge too, and the viewer read runs on the watch's deadline-bound client.
  • Commands on the interface: quest status, quest wait, and the claim and open-PR reads of quest unblocked --unclaimed, quest start, quest waiting, and quest mv. Output is unchanged.
  • Identity is part of the interface: Forge.viewer() names the person. quest wait ignores that person's own activity whichever credential reads: Kixel Quest's token's person, or on GitHub a viewer passed in (the installation-token quest's hook) or else read once.
  • "Which repositories Kixel Quest serves", for records-endpoint: kixelQuest(deps)?.serves(repository). Its Plan now points there.
  • README gains "Read through Kixel Quest"; the help of status, wait, unblocked, start, and waiting says when reads go there.

What stays on GitHub, since it's outside the Goal: upstream discovery (GET /repos/{repo}, one REST call per --unclaimed run, which #754's ETag cache makes free), write commands and the reads they verify a write with (iterate, ready, release, merge, start's post-claim race check, start --release), and the host's quest land daemons. forge-writes extends the same interface with the writes.

Choices made without asking (reviewable)

  • Token: reuse the records token file (records.json, keyed by endpoint URL), the per-person token kixel.quest already issues, rather than a new file or variable.
  • Served list: an explicit GET /forge answering the person and their repositories, read once per command, rather than inferring "not served" from a 404 on each read, which can't tell an unserved repository from a missing PR.
  • Wait over the wire: watch is one stateless poll per request, {pull, from} → {events, cursor, pollInterval}, where the cursor belongs to the backend. The CLI keeps the poll schedule. Kixel Quest can fall through by running GitHubForge.watch(...).poll() once per request.
  • asOf: carried by every answer. Only quest wait uses it: a timeout through Kixel Quest says how current the index's last answer was. quest status output stays unchanged.
  • Override names: QUEST_FORGE=github and QUEST_KIXEL_URL.
  • quest waiting keeps its existing warn-and-skip for unreadable drafts, so a Kixel Quest failure there warns (naming the override) rather than failing; it spends no GitHub quota either way.
  • Records-endpoint sequencing: added to its Plan that hosts get the token only once Kixel Quest serves GET /forge, since with a token every forge read goes there.

Decisions

  • Kixel Quest 400s (Pullfrog, r4579755450): ✅ usage error only on /forge/watch; elsewhere a failure naming QUEST_FORGE=github (rejected: append the override to every 400 while keeping it a usage error, since a wire mismatch is not the user's argument to fix).
  • A wait's resume point before Kixel Quest's first answer (Pullfrog, r4579755463; the maintainer's decision, comment): ✅ the time the wait started, taken before it asks which forge to read and rounded down to the second GitHub times activity in (rejected: read the head through status first to resume from its SHA, as GitHub's backend does, since that read can time out too and costs a request per wait). The trade-off: a retry after such a timeout skips activity on the head from before the first wait started, which that wait never reported either.

Public API and wire

  • Breaking for quest/github consumers (kixel-ai/kixel.quest): the read types (Status, Check, Review, Reaction, Thread, ReviewRecord, HoldFact, Signal, OpenPull, Claim, Holdings, Repository, PullRequest) are now exported from quest/core; Source/Sources are renamed ClaimSource/ClaimSources, since quest/core already exports a Source. Migrate by importing them from quest/core. quest/github adds GitHubForge.
  • New wire API that Kixel Quest serves (its quest/m0/read-api.md): described above and in the README.
  • CLI: new QUEST_FORGE and QUEST_KIXEL_URL variables; output and exit codes unchanged. Kixel Quest's live site does not serve /forge yet, and no host holds a token, so nothing changes for anyone until both happen.

Validation

  • just check and just test pass (1421 tests) after merging main: feat(github)!: revalidate every REST GET by ETag against an on-disk cache #754's ETag-cached list/all reads replace the wait's hand-rolled conditional pager in src/github/wait.ts, and records-endpoint drops its Required link to this quest. A regression test times out a wait's first Kixel Quest poll, moves the head, and retries from the printed point, which reports the push; it fails without the fix.
  • test/forge.test.ts runs the same scenarios against a fake GitHub directly and through a fake Kixel Quest that serves each read by running GitHubForge on that fake GitHub: three status scenarios (byte-identical --json), open PRs and claims with landed branches, and three wait scenarios (identical lines, cursors, and sleeps). It also covers an unserved repository reading GitHub (case-insensitively), no token or QUEST_FORGE=github never contacting Kixel Quest, a 503, a refused token, and a malformed answer each failing with the override named, the timeout's asOf message, the timeout covering forge discovery, a rate-limited GitHub viewer read giving up at the timeout, a Kixel Quest 400 staying a usage error, failed viewer and GET /forge reads being retried rather than cached, and the wire parsers refusing missing, extra, or ill-typed fields.
  • Mutation check: swapping two fields' order in the Status parser fails all three status scenarios, and dropping the tips from the held request fails the claims scenario.
  • Real surface: the built dist/quest.js against a local Kixel Quest stand-in (Bun.serve on localhost, serving /forge by falling through to real GitHub with my token, QUEST_KIXEL_URL=http://localhost:18787):
  • Not measured: quota saved on real hosts, which needs kixel.quest to serve /forge and hosts to hold tokens. The epic's closing PR records it.

Follow-ups

None new. kixel-ai/kixel.quest's quest/m0/read-api.md already owns serving this API; it waits on this PR's types landing in its pinned quest.

Models

Size: L
Implementer: Claude Code, claude-opus-5-5, unknown effort
Implementer: Claude Code, claude-opus-5-5 (iterate, S)
Implementer: Claude Code, claude-opus-5-5 (iterate, XS)

Review

Rewritten by quest review after each round.

  • Head: 28dade9

  • Base: origin/main at f293c54

  • Risk: high, Removing quest/github exports and routing status and claim reads through a new forge API can break Kixel Code and repository automation; reverting restores the code but cannot undo actions agents already took from incorrect state.

  • Classified: high by Codex, gpt-6.1-sol, low effort, session 01a1e8b0-70de-78b0-a9c7-684df1912c67

  • Reviewer: Codex, gpt-6.1-sol, xhigh effort

  • Session: 01a1e084-45eb-7a43-93fe-158098bb5956, round 6

  • Score: 10/10, The merge preserves the reviewed forge behavior and carries main’s ETag changes into the relocated watcher, with no new issues found by code inspection.

  • Rounds: 6; first round 3 (medium 3); findings 6 (medium 6): fixed 6, refuted 0, open 0

  • Findings: none

  • Reviewer: Codex, gpt-6.1-sol, high effort, shadow

  • Session: 01a1e084-45ea-76d0-843b-45185f2098db

  • Rounds: 2; first round 2 (medium 2); findings 2 (medium 2): fixed 2, refuted 0, open 0

kixelated and others added 4 commits November 15, 2026 10:19
…ixel Quest backend

quest status, quest wait, and the claim and draft reads of quest unblocked
--unclaimed, quest start, and quest waiting go through a Forge interface.
GitHubForge reads GitHub as before; KixelQuestForge reads Kixel Quest's
/forge API for a person holding its token, for the repositories it says
it serves. The read types and wire parsers move to quest/core.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kixelated kixelated changed the title Forge interface with a Kixel Quest backend for reads feat(forge)!: read PR, claim, and wait state through a forge with a Kixel Quest backend Nov 15, 2026
kixelated and others added 2 commits November 15, 2026 10:48
… keep usage errors

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kixelated
kixelated marked this pull request as ready for review November 15, 2026 18:53
@coderabbitai

coderabbitai Bot commented Nov 15, 2026 •

Copy link
Copy Markdown

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 32 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 80587846-d6df-4a6e-8c09-55cce99f64a5
Commits

Reviewing files that changed from the base of the PR and between f293c54 and 28dade9.

Files ignored due to path filters: 1

  • bun.lock is excluded by !**/*.lock
Files selected for processing: 42

  • README.md
  • quest/m0/benchmark/records-endpoint.md
  • quest/m0/github-quota/forge-reads.md
  • quest/m1/forge-writes.md
  • src/cli/breakage.ts
  • src/cli/claims.ts
  • src/cli/forge.ts
  • src/cli/github.ts
  • src/cli/hold.ts
  • src/cli/land-apply.ts
  • src/cli/land-bump.ts
  • src/cli/land-daemon.ts
  • src/cli/land-head.ts
  • src/cli/land-queue.ts
  • src/cli/land-watch.ts
  • src/cli/land.ts
  • src/cli/main.ts
  • src/cli/review-eval.ts
  • src/cli/send.ts
  • src/cli/start.ts
  • src/cli/status.ts
  • src/cli/usage.ts
  • src/cli/wait.ts
  • src/core/forge.ts
  • src/core/index.ts
  • src/github/claims.ts
  • src/github/client.ts
  • src/github/forge.ts
  • src/github/hold.ts
  • src/github/index.ts
  • src/github/online-review.ts
  • src/github/signals.ts
  • src/github/status.ts
  • src/github/wait.ts
  • test/forge.test.ts
  • test/online-review.test.ts
  • test/start.test.ts
  • test/status-fakes.ts
  • test/status.test.ts
  • test/usage.test.ts
  • test/wait-fakes.ts
  • test/wait.test.ts
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ℹ️ No critical issues. Two rough edges in the Kixel Quest backend, inline, and one wire-design question below.

Reviewed changes

I reviewed the whole PR: the new forge interface and its wire format, the GitHub and Kixel Quest backends, and the commands moved onto them.

  • Forge interface in quest/core: Forge (viewer, status, pulls, held, watch), the read types moved out of src/github, InputError in place of GitHubInputError, and strict parsers that rebuild field order so --json stays byte-identical.
  • GitHubForge and src/github/wait.ts: the existing readers behind the interface. quest wait's GitHub logic moves into a Worker-safe Watch, and the viewer is read once and dropped after a failure.
  • Kixel Quest backend (src/cli/forge.ts): picks the backend from records.json, QUEST_FORGE, and QUEST_KIXEL_URL. GET /forge is cached and dropped after a failure. Requests are bounded by the deadline and refuse redirects. A failure names QUEST_FORGE=github.
  • Commands: status, wait, and the claim and draft reads of unblocked --unclaimed, start, waiting, and mv now read through forgeFor. src/cli/wait.ts keeps only the poll schedule and the timeout.
  • Docs and quests: a README section for reading through Kixel Quest, help text for the affected commands, the finished quest deleted, and follow-up quests repointed.

ℹ️ Strict extra-field rejection makes additive wire changes break across deploys

shape() refuses unknown fields in both requests and answers, and both sides parse with it. The CLI and kixel.quest's pinned quest/core are deployed separately, so any new field breaks every request until both sides upgrade. If Kixel Quest adds a Status field first, older CLIs fail. If a newer CLI sends a field first, the older server returns 400. The error names the override in most cases, so users can recover, but the two sides must upgrade in lockstep for every schema change. That fits "neither side guesses", but it's worth deciding on purpose.

Technical details
# Strict wire parsing vs. independent deploys

## Affected sites
- src/core/forge.ts:318-331 — `shape` fails on any key not in `fields` (`expected no such field`)
- src/cli/forge.ts:106 — CLI parses answers with `parseForgeAnswer` (strict)
- Kixel Quest parses requests with `parseForgeRequest` (strict), per README

## Required outcome
- A deliberate policy for wire evolution between the CLI and kixel.quest's pinned `quest/core`.

## Open questions for the human
- Is lockstep upgrading acceptable (the error names `QUEST_FORGE=github`), or should answers ignore unknown fields while requests stay strict (or carry a version)?
- Determinism of `--json` comes from rebuilding fields in parser order, which stays true if unknown answer fields are dropped instead of refused.

Pullfrog  | Fix all ➔ | Fix 👍s ➔ | View workflow run | Using claude-opus-5-5 | 𝕏

Comment thread src/cli/forge.ts Resolved
Comment thread src/cli/forge.ts Resolved

@kixelated kixelated left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Automated review by review (OpenAI)

Reviewed head: c2556e664e070b4746670894cd28600f04da1472.

Static catch-up review of the forge wire parsers, backend selection and error handling, GitHub watch extraction, CLI wait scheduling, and claim/draft-read routing. No additional actionable finding beyond the existing review threads.

I independently confirmed the timeout-resumption gap already tracked in the existing thread: KixelQuestForge.watch only sets its cursor after a successful answer. With no --since, a first-poll timeout leaves resume undefined, unlike the GitHub backend, which preserves the original head during setup. A retry can therefore start after activity that occurred during the timed-out wait. Preserve a recoverable baseline before that first remote poll, and add a regression covering a first-poll timeout followed by a head change and retry. Please keep the fix/discussion in the existing thread rather than opening a duplicate.

The extracted GitHub Watch does restart from the returned cursor after an eventful poll, and the post-claim race validation remains on GitHub rather than trusting cached remote state. Those boundaries look consistent with the intended design.

Limits: code/diff inspection only; I did not run tests or exercise the deployed Kixel Quest service. This COMMENT is not an approval or merge recommendation.

…nswer, and name the override on a read's 400

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
pullfrog[bot]
pullfrog Bot previously approved these changes Nov 17, 2026

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ No new issues found. Both earlier inline findings are fixed.

Reviewed changes

I reviewed the two commits pushed since the last Pullfrog review at c2556e6.

  • Limited Kixel Quest 400s that count as usage errors: a 400 from Kixel Quest is now an InputError only on /forge/watch, where it rejects a bad --since. A 400 on status, pulls, or held fails through failed(...), and that error names QUEST_FORGE=github. A new test covers this.
  • Added a resume point for a Kixel Quest wait before its first answer: src/cli/wait.ts records started before it chooses a forge. KixelQuestForge.watch turns that time into its fallback resume, rounded down to the second. The first poll still sends from: null when --since is absent.
  • Updated docs and tests for the new resume point: the README and wait --help now name the time the wait started as the resume point through Kixel Quest. A new regression test times out the first poll, moves the head within that first second, and checks that the retry reports the push.

Pullfrog  | View workflow run | Using claude-opus-5-5 | 𝕏

@kixelated kixelated left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Automated review by review (OpenAI) · 00dfac4a30580b7a9fd9b8d07e4ffa68029fe645

No new blocker in this delta. The first remote watch timeout now returns a resume timestamp from before discovery, rounded down to GitHub’s precision, until a real cursor is received. That preserves a first-second push during a slow discovery, which the fixture covers. The added GitHub fallback guidance is useful; a timeout in discovery itself still has no new resume point, as before. Static re-review only; I did not run the tests.

@kixelated

Copy link
Copy Markdown
Collaborator Author

Maintainer decision (from the maintainer's /quest-run round, 2026-11-17):

  • Where a Kixel Quest wait resumes before its first answer: ✅ keep the wait's start time, as the head does (rejected: reading the head through status first, which costs a request per wait and can time out too).
  • Merge pick: ✅ /quest-merge once the branch merges main (it conflicts after feat(github)!: revalidate every REST GET by ETag against an on-disk cache #754) and its head is landable.

(Written by Claude Opus 5.5 with high effort)

Port #754's ETag-cached pager and edits reads into src/github/wait.ts, give
the wait fakes a response cache, and drop records-endpoint's Required link to
forge-reads, which this branch finishes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kixelated

Copy link
Copy Markdown
Collaborator Author

Applied the maintainer's decision in #issuecomment-6943118557: head 28dade9 keeps a Kixel Quest wait without --since resuming from the wait's start time (src/cli/forge.ts), recorded as the maintainer's in the body's ## Decisions. This head also merges main, porting #754's ETag-cached reads into src/github/wait.ts.

(Written by Claude Opus 5.5)

@kixelated kixelated left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Automated review by review (OpenAI) · 28dade9dee0165cd756c057e27996a583e7e12b5

No new blocker in the wait/ETag merge. The pager still follows the next link and polls from the last page; it now leaves revalidation to the GitHub client, which deliberately rereads a full last page without a next link. The wait’s seen-event checks still discard rows replayed by a cached 304. Edited comments still restart their updated-since scan at page one. Static re-review of the merge resolution only; I did not run the wait tests.

@kixelated
kixelated enabled auto-merge November 17, 2026 08:50

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ No new issues found. The merge carries main's ETag cache into the relocated wait logic correctly.

Reviewed changes

I reviewed the merge of origin/main (28dade9) since the last Pullfrog review at 00dfac4.

  • Moved the wait pager onto the cached client: pager in src/github/wait.ts now reads with github.list(path) and no longer runs its own ETag/304 handling. A 304 replays the cached body under the cached headers, so the next link still resolves, and fresh() drops rows the wait has already seen. The client's settled() declines to cache a full last page that has no next link, so a new next page is still found.
  • Simplified edits: it uses github.all(...), which still restarts the update-filtered comment list from page one on every poll.
  • Wired the response cache: the CLI's GitHub dependencies get the disk cache, and the wait test fakes now provide an in-memory cache. src/cli/wait.ts keeps no leftover paging code after the merge.
  • Updated the records-endpoint quest: it took main's text, including the Required link to this quest.

bun test test/wait.test.ts test/forge.test.ts passes (93 tests).

Pullfrog  | View workflow run | Using claude-opus-5-5 | 𝕏

@kixelated
kixelated added this pull request to the merge queue Nov 17, 2026
Merged via the queue into main with commit e35b3f5 Nov 17, 2026
17 checks passed
@kixelated
kixelated deleted the quest/m0/github-quota/forge-reads branch November 17, 2026 08:56
kixelated added a commit that referenced this pull request Nov 17, 2026
Main's #753 moved the status types to quest/core behind a strict forge
wire parser, so `Duplicate` and `Status.duplicates` move there with a
parser entry, and the duplicate fakes move into test/status-fakes.ts.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant