Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -636,6 +636,20 @@ command fails too, naming `QUEST_FORGE=github`, which reads GitHub instead.
`QUEST_KIXEL_URL` names another Kixel Quest, such as one running locally, whose
token the same file pairs with its URL.

A read that must come from GitHub itself, such as `quest pr view` or the
open-PR checks of `quest start`, uses a read-only App installation token Kixel
Quest mints for that repository, so it draws on the installation's rate limit,
not the person's. `POST /installation-token` takes `{"repository":
"owner/repo"}` and answers `{token, expiresAt, repository, login}`; a 404 means
Kixel Quest does not serve the repository, and `quest` reads it with the
person's own token. `quest` keeps each token in
`$XDG_CACHE_HOME/quest/installation` (else `~/.cache/quest/installation`) until
five minutes before it expires, since a person may mint only so many an hour,
and a 429 or any other failure fails the command, naming `QUEST_FORGE=github`.
Writes, such as comments, pushes, and merges, always use the person's own token,
so they are made in their name; `quest wait` takes the person from the mint's
`login`, because on an installation token GitHub names the App as the viewer.

Its read API lives under `/forge`, with the token as a bearer token:
`GET /forge` answers `{"login", "repositories"}`, the person the token names
and the lowercase `owner/repo` of each repository served to them, and
Expand Down
47 changes: 17 additions & 30 deletions quest/m0/github-quota/README.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,14 @@
# Spend less of a person's GitHub quota
# [S] Record a day of GitHub quota use under the new reads

## Goal

Agents polling `quest status`, `quest wait`, and `quest unblocked` stop
draining the GitHub quota of the person running them. Three changes, each
useful alone: every REST GET revalidates with an ETag, reads use an App
installation token from Kixel Quest instead of the person's, and a forge
interface lets quest read pull request state from Kixel Quest's index.
Agents polling `quest status`, `quest wait`, and `quest unblocked` no longer
drain the GitHub quota of the person running them: every REST GET revalidates
with an ETag, reads use an App installation token from Kixel Quest, and a forge
interface reads pull request state from Kixel Quest's index. All three have
landed; what remains is the evidence. Record the person's REST `core` and
GraphQL use over a day of the maintainer's agents, from `gh api rate_limit`,
beside the outage day's, in this quest's PR, then delete this quest.

Non-goals: emulating GitHub's API in Kixel Quest, and anything new for
outside contributors, who keep reading GitHub with their own token.
Expand All @@ -15,27 +17,12 @@ outside contributors, who keep reading GitHub with their own token.

Decided 2026-11-15 (maintainer, `/quest-plan` in kixel-ai/kixel.quest,
[kixel-ai/kixel.quest#48](https://github.com/kixel-ai/kixel.quest/pull/48),
"we're rate limited by github"): ✅ all three of reads from Kixel Quest,
ETags on every GET, and reads on an installation token (rejected: any one
alone). That day REST `core` sat at 0 of 5,000 on the maintainer's token
while about 20 agents checked PR status.

Decided 2026-11-15 (maintainer, `/quest-plan` here):

- ✅ quest has Kixel Quest's URL built in, overridable by an environment
variable for development, and names a repository by `owner/repo` from its
remote (rejected: a committed `.quest.json` naming the endpoint, which no
repository had committed yet and which could drift from what Kixel Quest
indexes). Kixel Quest says which repositories it serves; the rest use
GitHub. Session records route the same way.
- ✅ Kixel Quest is used only by a person holding a Kixel Quest token, which
its admin-managed allow-list gives out; outside contributors stay a
non-goal for now (rejected: a self-serve contributor role, picked and then
withdrawn in the same interview).
- ✅ A chosen Kixel Quest backend that errors fails the command and names the
setting that forces GitHub (rejected: falling back to GitHub, which hides
a broken index and spends the quota this saves).

The epic's closing PR records the person's REST `core` and GraphQL use over a
day of the maintainer's agents, from `gh api rate_limit`, beside the outage
day's.
"we're rate limited by github"): all three of reads from Kixel Quest, ETags on
every GET, and reads on an installation token. That day REST `core` sat at 0 of
5,000 on the maintainer's token while about 20 agents checked PR status.

An installation token serves only reads that go to GitHub itself, such as `quest
pr view` and the verifying reads of `quest start`; where Kixel Quest serves the
repository, its index answers the rest. Compare the person's own `core` and
GraphQL `used` per hour, from `gh api rate_limit`, on a day the maintainer's
agents ran as usual.
58 changes: 0 additions & 58 deletions quest/m0/github-quota/installation-token.md

This file was deleted.

9 changes: 5 additions & 4 deletions src/cli/claims.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,6 @@ import { type Remote, readRemote, remoteHost, remoteRepository, requireRemote }
import { type GitHubDependencies, GitHub, object, repositoryPath, string } from "../github/client";
import type { Claim, Forge, ForgeWrites, Holdings, OpenPull, Repository } from "../core";
import { questBranches } from "../github/claims";
import { GitHubForge } from "../github/forge";
import { landingCheck } from "./landed";
import { GitHubWrites } from "./writes";
import { type Snapshot, snapshot } from "./tree";
Expand All @@ -16,6 +15,8 @@ export interface ClaimDependencies {
github(): GitHubDependencies;
/** The forge answering reads of a repository on GitHub, such as its claims and open PRs. */
forge(repository: Repository): Promise<Forge>;
/** The forge answering a read of a repository on GitHub from GitHub itself, never an index that may lag. */
live(repository: Repository): Promise<Forge>;
/** Kixel Quest, for remotes on it; without it, no remote is. */
kixel?: {
/** The repository `url` on Kixel Quest names, or null for none. */
Expand All @@ -38,7 +39,7 @@ export interface Hosting {
/** The forge answering reads of `repository`, chosen on first use. */
forge(): Promise<Forge>;
/** The forge's own answers, never an index that may lag, for a read that verifies or rewrites what it read. */
live(): Forge;
live(): Promise<Forge>;
/** The forge taking writes to `repository`, created on first use. */
writes(): ForgeWrites;
/** A link to `path` on the default branch, where the forge shows files. */
Expand Down Expand Up @@ -91,7 +92,7 @@ export async function upstream(root: string, remote: Remote, deps: ClaimDependen
defaultBranch: defaultBranch(root, remote.name),
prefix: git(root, ["rev-parse", "--show-prefix"]),
forge: async () => forge(),
live: forge,
live: async () => forge(),
writes: forge,
link: () => null,
},
Expand Down Expand Up @@ -121,7 +122,7 @@ export async function upstream(root: string, remote: Remote, deps: ClaimDependen
defaultBranch: up.defaultBranch,
prefix,
forge: () => (forge ??= deps.forge(up.repository)),
live: () => new GitHubForge(deps.github()),
live: () => deps.live(up.repository),
writes: () => (writes ??= new GitHubWrites(deps.github(), landingCheck(root))),
link: (path: string) =>
`https://github.com/${owner}/${repo}/blob/${up.defaultBranch}/${encodeURI(prefix + path)}`,
Expand Down
128 changes: 123 additions & 5 deletions src/cli/forge.ts
Original file line number Diff line number Diff line change
@@ -1,7 +1,9 @@
// Which forge answers a repository's reads and takes its writes. A repository Kixel Quest hosts, named by a remote or
// PR URL on Kixel Quest, is read and written there alone. For one on GitHub, reads go to Kixel Quest's index for a
// person holding its token when it serves the repository, else GitHub, and writes go to GitHub. A Kixel Quest failure
// fails the command, naming the setting that reads GitHub instead where that would help.
// fails the command, naming the setting that reads GitHub instead where that would help. A read that goes to GitHub
// anyway, to verify what an index said or because Kixel Quest does not serve the repository, runs on a read-only
// installation token Kixel Quest mints, so it draws on the installation's rate limit rather than the person's.
import {
type Answer,
type ClaimSources,
Expand Down Expand Up @@ -29,9 +31,18 @@ import {
parseForgeInfo,
Refusal,
} from "../core";
import type { GitHubDependencies } from "../github/client";
import { type GitHubDependencies, reading } from "../github/client";
import { GitHubForge } from "../github/forge";
import { pullRequest, readRemote, remoteHost } from "./github";
import {
type Installation,
LockDeadline,
REUSE_MARGIN,
exclusive,
installationDirectory,
keep,
kept,
} from "./installation";
import { kixelUrl, tokenFor, tokensPath } from "./tokens";

/** The variable that, set to `github`, reads GitHub even where Kixel Quest serves the repository. */
Expand All @@ -42,6 +53,7 @@ export interface ForgeDependencies {
env: NodeJS.ProcessEnv;
fetch: typeof fetch;
now(): number;
sleep(milliseconds: number): Promise<unknown>;
/** Called only once a read goes to GitHub, so Kixel Quest's reads need no GitHub token. */
github(): GitHubDependencies;
/** What a Kixel Quest failure tells the person to do; by default, to read GitHub instead. */
Expand Down Expand Up @@ -84,7 +96,25 @@ export async function forgeFor(
const kixel = kixelQuest(deps);
return kixel !== null && (await kixel.serves(repository, deadline))
? new KixelQuestForge(kixel)
: new GitHubForge(deps.github());
: new GitHubForge(reading(deps.github()));
}

/**
* The forge that answers `repository`'s reads from GitHub itself, never an index that may lag. For a person holding a
* Kixel Quest token it reads on the installation token Kixel Quest mints for the repository, and on the person's own
* where Kixel Quest does not serve it or the reads are forced onto GitHub. Minting gives up at `deadline`.
*/
export async function liveFor(
repository: Repository,
deps: ForgeDependencies,
deadline = Infinity,
): Promise<GitHubForge> {
const kixel = kixelQuest(deps);
const installation = kixel === null ? null : await kixel.installation(repository, deadline);
const person = reading(deps.github());
return installation === null
? new GitHubForge(person)
: new GitHubForge({ ...person, readToken: installation.token }, installation.login);
}

/** Kixel Quest refused the person's token, as a sender must tell from a failure that may pass. */
Expand Down Expand Up @@ -177,6 +207,82 @@ export class KixelQuest {
);
}

/**
* A read-only token for `repository`, or null when Kixel Quest does not serve it to this person. Minted at most
* once an hour per repository: a kept token with time left is reused, so a command mints none.
*/
async installation(repository: Repository, deadline = Infinity): Promise<Installation | null> {
const directory = installationDirectory(this.deps.env);
const instead = `set ${FORGE}=github to read GitHub with your own token`;
const keeping = (what: string, error: unknown) =>
new Error(
`cannot ${what} installation tokens in ${directory}: ${error instanceof Error ? error.message : String(error)}; ${instead}`,
);
try {
const have = kept(directory, this.url, this.token, repository, this.deps.now());
if (have !== null) return have;
} catch (error) {
throw keeping("read", error);
}
const path = "/installation-token";
const name = `${repository.owner}/${repository.repo}`;
const mint = async (until: number): Promise<Installation | null> => {
// Another agent may have minted while this one waited for the lock.
try {
const have = kept(directory, this.url, this.token, repository, this.deps.now());
if (have !== null) return have;
} catch (error) {
throw keeping("read", error);
}
const { response, text } = await this.#fetch("POST", path, { repository: name }, until);
if (response.status === 404) return null;
if (response.status === 429) {
const wait = Number(response.headers.get("retry-after"));
throw this.#failed(
"POST",
path,
`you have minted as many installation tokens this hour as one person may${Number.isFinite(wait) && wait > 0 ? `; try again in ${Math.ceil(wait)} seconds` : ""}`,
);
}
if (!response.ok) throw this.#failed("POST", path, `HTTP ${response.status}${reason(text)}`);
const installation = this.#minted(text, name);
try {
keep(directory, this.url, this.token, repository, installation);
} catch (error) {
throw keeping("keep", error);
}
return installation;
};
try {
return await exclusive(directory, this.url, this.token, repository, this.deps, deadline, mint);
} catch (error) {
if (error instanceof LockDeadline) throw this.#failed("POST", path, error.message);
if ((error as NodeJS.ErrnoException).code !== undefined) throw keeping("lock", error);
throw error;
}
}

/** The token in a mint's answer, `{token, expiresAt, repository, login}`, for `name`. */
#minted(text: string, name: string): Installation {
const path = "/installation-token";
let json: unknown;
try {
json = JSON.parse(text);
} catch {
throw this.#failed("POST", path, "its answer is not JSON");
}
const { token, expiresAt, repository, login } = (json ?? {}) as Record<string, unknown>;
const at = typeof expiresAt === "string" ? Date.parse(expiresAt) : NaN;
if (typeof token !== "string" || token === "" || typeof login !== "string" || login === "" || Number.isNaN(at))
throw this.#failed("POST", path, "its answer lacks a token, an expiry, or a login");
if (typeof repository !== "string" || repository.toLowerCase() !== name.toLowerCase())
throw this.#failed("POST", path, `it minted a token for ${String(repository)}, not ${name}`);
// A token that is already inside its reuse margin would be minted again by every command.
if (at - this.deps.now() <= REUSE_MARGIN)
throw this.#failed("POST", path, `its token expires at ${expiresAt}, too soon to reuse`);
return { token, expiresAt: at, login };
}

/** The time now, epoch milliseconds. */
now(): number {
return this.deps.now();
Expand All @@ -203,8 +309,13 @@ export class KixelQuest {
return new Error(`Kixel Quest (${this.url}) failed ${method} ${path}: ${why}${instead}`);
}

/** The JSON answer to a request, or an error naming the setting that reads GitHub instead. */
async #send(method: "GET" | "POST", path: string, body: unknown, deadline: number): Promise<unknown> {
/** The answer to a request, as text; Kixel Quest's refusal of the person's token and any network failure throw. */
async #fetch(
method: "GET" | "POST",
path: string,
body: unknown,
deadline: number,
): Promise<{ response: Response; text: string }> {
const failed = (why: string) => this.#failed(method, path, why);
const remaining = deadline - this.deps.now();
if (remaining <= 0) throw failed("its deadline passed");
Expand Down Expand Up @@ -238,6 +349,13 @@ export class KixelQuest {
.message,
response.status,
);
return { response, text };
}

/** The JSON answer to a request, or an error naming the setting that reads GitHub instead. */
async #send(method: "GET" | "POST", path: string, body: unknown, deadline: number): Promise<unknown> {
const failed = (why: string) => this.#failed(method, path, why);
const { response, text } = await this.#fetch(method, path, body, deadline);
// A malformed wait point, token, thread, or body is the caller's to fix on any forge; the other reads take no
// free-form argument, so their 400 means the CLI and Kixel Quest disagree on the wire, which reading GitHub
// sidesteps.
Expand Down
Loading
Loading