Skip to content

feat(github)!: read on an installation token from Kixel Quest - #777

Open
kixelated wants to merge 4 commits into
mainfrom
quest/m0/github-quota/installation-token
Open

kixelated wants to merge 4 commits into
mainfrom
quest/m0/github-quota/installation-token

Conversation

@kixelated

@kixelated kixelated commented Nov 17, 2026 •

Copy link
Copy Markdown
Collaborator

Finishes quest/m0/github-quota/installation-token.md.

A person with a Kixel Quest token now reads GitHub on a read-only App installation token Kixel Quest mints per repository, so those reads draw on the installation's rate limit, not their 5,000 an hour. Writes stay on their own token.

Summary

  • POST /installation-token client (KixelQuest.installation, src/cli/forge.ts), and liveFor: the forge for reads that must come from GitHub itself. It backs Hosting.live() (quest start, quest review's record, quest pr list) and quest pr view. Where Kixel Quest serves the repository the index answers everything else, so those are the reads that reach GitHub.
  • Tokens are kept by Kixel Quest URL, the person's Kixel Quest token, and repository in $XDG_CACHE_HOME/quest/installation (files 0600, directory 0700) until 5 minutes before expiresAt, so a host mints about once per repository an hour. A lock file per token (created exclusively, owned by its holder, taken over after 30 seconds; a holder gets 20 seconds to mint, so a live one is never taken over) makes parallel agents on a cold or expiring cache mint once between them.
  • A 404 (not served) reads on the person's token, as does having no Kixel Quest token or QUEST_FORGE=github. A 429 (with its Retry-After), 401/403, 5xx, a malformed answer, a token for another repository, one too close to expiry, or an unusable cache directory fails the command naming QUEST_FORGE=github; none quietly spends the person's quota.
  • quest wait takes the person from the mint's login, through GitHubForge's existing viewer argument, so the person's own replies, reactions, labels, and edits do not wake it though viewer on the token is the App.
  • The client splits by type: GitHubReader (GET and GraphQL queries, built from GitHubReadDependencies with a readToken) and GitHub extends GitHubReader (built from GitHubDependencies with the person's token; adds other methods and mutations). Every read module in src/github takes a GitHubReader; a write on a read token has no constructor to go through, and a mutation sent to a reader throws.
  • The epic's README, now the last of its work, becomes the quest to record a day of quota use; the quest file is deleted. README.md documents the mint.

Public API and wire

Breaking for quest/github consumers, so !:

  • GitHubForge, pullRequestStatus, readHoldStatus, and watchPull take GitHubReadDependencies (readToken in place of token); read helpers (openPullRequests, pullView, held, requirements, ...) take a GitHubReader instead of a GitHub. To migrate, pass reading(deps) for a person's GitHubDependencies, or a GitHubReader/GitHub where a client is taken. GitHub and GitHubDependencies are unchanged.
  • New exports: GitHubReader, GitHubReadDependencies, reading.
  • ClaimDependencies gains live(repository), and Hosting.live() is async.
  • Wire: a new client of kixel.quest's POST /installation-token (kixel-ai/kixel.quest#51, merged and deployed: it answers 401 with no token). /forge is unchanged.

Decisions

  • A mint is cached per repository on disk and a cache that cannot be read or written fails the command: without it every command mints, and the per-person cap is spent within a minute. QUEST_FORGE=github is named as the way out.
  • Upstream.github.client, which quest start, quest usage, and quest eval use to probe the repository, its fork, and its parent, stays on the person's token: those probes reach repositories the installation may not cover (a private fork), and the ETag cache already makes their repeats free.
  • The lock is a plain exclusive-create file with a time in it, not flock, which macOS lacks; two waiters that take over a stale lock at once may mint twice, one more of the cap.
  • No negative cache: a repository Kixel Quest does not serve costs one extra 404 request per live() use.

Validation

  • just check and just test pass.
  • test/installation.test.ts runs a fake Kixel Quest and a fake GitHub that record each request's token: a read goes out on the minted token and a write (GitHubWrites.close) on the person's; one mint is reused across runs and replaced within 5 minutes of expiry, per repository and per Kixel Quest token; eight parallel agents on a cold cache mint once (a plain write instead of the exclusive create fails it); a stale lock is taken over and a held one waited for until the deadline; a 404 reads on the person's token, and a 429, 502, 503, 401, a malformed mint, and an unwritable cache fail naming QUEST_FORGE=github with no GitHub request made; and quest wait on a minted token (viewer answering the App) still ignores the person's own reply, reaction, label, and edit. Dropping the mint's login from liveFor fails that test. The @ts-expect-error lines in it fail tsc if a read client gains a write or a write accepts read dependencies.
  • Not exercised against the real endpoint: this host holds no Kixel Quest token. Its wire was read from the diff of kixel-ai/kixel.quest#51 and the unauthenticated endpoint answers 401.

Follow-ups

None.

Models

Size: S
Implementer: Claude Code, claude-sonnet-5-5, unknown effort (arm B)

🤖 Generated with Claude Code

(Written by Sonnet 5.5)

Review

Rewritten by quest review after each round.

  • Head: 466689d

  • Base: origin/main at 80cd2c8

  • Risk: high, The change alters quest/github’s public dependency contracts and GitHub credential handling, which can break Kixel Code integrations or expose cached repository tokens; reverting restores the code but cannot undo credential exposure or actions taken using incorrect reads.

  • Classified: high by Codex, gpt-6.1-sol, low effort, session 01a1ebd2-ab82-7860-8692-12611cc31500

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

  • Session: 01a1ebcd-38b5-7992-a6ca-31ee1a145fe2, round 3

  • Score: 10/10, The bounded mint request and ownership-aware lock release resolve the outstanding finding; code review found no new issues, and builds and tests were not run as instructed.

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

  • Findings: none

  • The last round's findings, at 549fcac:

    • Fixed: medium, src/cli/installation.ts:127: Preserve lock ownership during slow token mints; exclusive passes a 20-second deadline to the mint request, enforced through AbortSignal.timeout before the 30-second takeover threshold, and cleanup checks the lock's owner ID before removing it.
  • Reviewer: Codex, gpt-6.1-sol, low effort, shadow

  • Session: 01a1ebcd-38b9-7b12-a0fd-086bf640908f, round 3

  • Score: 10/10, The bounded mint deadline and ownership-aware lock release address the remaining finding, with no new blocking issues found in the incremental changes.

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

  • Findings: none

  • The last round's findings, at 549fcac:

    • Fixed: medium, src/cli/installation.ts:127: Keep the lock valid while its holder is still minting; exclusive now bounds minting to 20 seconds, below the 30-second takeover threshold, and releases the lock only when its owner identifier still matches.

kixelated and others added 2 commits November 17, 2026 15:08
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@kixelated kixelated changed the title Read on an installation token from Kixel Quest feat(github)!: read on an installation token from Kixel Quest Nov 17, 2026
kixelated and others added 2 commits November 17, 2026 15:21
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@kixelated
kixelated marked this pull request as ready for review November 17, 2026 23:24
@coderabbitai

coderabbitai Bot commented Nov 17, 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 27 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: 478ecaa5-741b-4fec-88b4-366ad30954ed
Commits

Reviewing files that changed from the base of the PR and between 80cd2c8 and 466689d.

Files selected for processing: 31

  • README.md
  • quest/m0/github-quota/README.md
  • quest/m0/github-quota/installation-token.md
  • src/cli/claims.ts
  • src/cli/forge.ts
  • src/cli/installation.ts
  • src/cli/main.ts
  • src/cli/review-record.ts
  • src/cli/send.ts
  • src/cli/start.ts
  • src/github/claims.ts
  • src/github/client.ts
  • src/github/duplicates.ts
  • src/github/files.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/view.ts
  • src/github/wait.ts
  • test/forge-writes.test.ts
  • test/forge.test.ts
  • test/installation.test.ts
  • test/pull-files.test.ts
  • test/start.test.ts
  • test/status-fakes.ts
  • test/status.test.ts
  • test/usage.test.ts
  • test/wait-fakes.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 commented Nov 17, 2026

Copy link
Copy Markdown

No configured credential can serve this run. Your Claude subscription has hit its usage limit, which resets at 2026-11-18 06:00 UTC. Re-trigger after it resets, or add an API key for this provider, which Pullfrog falls back to automatically.

The providers' responses
CLAUDE_CODE_OAUTH_TOKEN: 429: This request would exceed your account's rate limit. Please try again later.

Pick another model →

Pullfrog  | Rerun failed job ➔ | View workflow run | via Pullfrog | Using claude-opus-5-5

1 similar comment
@pullfrog

pullfrog Bot commented Nov 17, 2026

Copy link
Copy Markdown

No configured credential can serve this run. Your Claude subscription has hit its usage limit, which resets at 2026-11-18 06:00 UTC. Re-trigger after it resets, or add an API key for this provider, which Pullfrog falls back to automatically.

The providers' responses
CLAUDE_CODE_OAUTH_TOKEN: 429: This request would exceed your account's rate limit. Please try again later.

Pick another model →

Pullfrog  | Rerun failed job ➔ | View workflow run | via Pullfrog | Using claude-opus-5-5

@kixelated

Copy link
Copy Markdown
Collaborator Author

@pullfrog review this PR's head.

(Written by Claude Opus 5.5 with high effort)

@kixelated
kixelated enabled auto-merge November 18, 2026 00:19
@pullfrog

pullfrog Bot commented Nov 18, 2026

Copy link
Copy Markdown

No configured credential can serve this run. Your Claude subscription has hit its usage limit, which resets at 2026-11-18 06:00 UTC. Re-trigger after it resets, or add an API key for this provider, which Pullfrog falls back to automatically.

The providers' responses
CLAUDE_CODE_OAUTH_TOKEN: 429: This request would exceed your account's rate limit. Please try again later.

Pick another model →

Pullfrog  | Rerun failed job ➔ | View workflow run | via Pullfrog | Using claude-opus-5-5

This branch has not been deployed

No deployments
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