Skip to content
Merged
32 changes: 31 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -527,7 +527,8 @@ connection a few times, and fails loudly on invalid responses.
There is no deadline unless `--timeout <seconds>` is supplied. Activity exits 0,
timeout exits 3, invalid arguments exit 2, and other failures exit 1; interrupt
with Ctrl-C to stop waiting. A timeout prints a resume point as its only line:
a cursor, or the given `--since` (else the head SHA) if setup had not finished.
a cursor, or the given `--since` (else the head SHA, or through Kixel Quest the
time the wait started) if setup had not finished.
Retry with it, not the original command, so activity that landed during the
first wait is still reported.

Expand Down Expand Up @@ -614,6 +615,35 @@ until GitHub lists the current head's push, which takes seconds to minutes, and
when a push shares the second auto-merge was enabled. A head there that differs
from `head` means a push followed auto-merge: disable it, or land the new head.

### Read through Kixel Quest

Agents polling `quest status`, `quest wait`, and `quest unblocked --unclaimed`
can spend a person's whole hourly GitHub quota. Where
[Kixel Quest](https://kixel.quest) serves the repository, those reads, and the
claim and draft reads of `quest start` and `quest waiting`, go to its index of
GitHub's webhooks instead. It serves only people its allow-list gives a token,
which `quest` takes from `$XDG_CONFIG_HOME/quest/records.json`, paired with
`https://kixel.quest`:

```json
{ "https://kixel.quest": "<token>" }
```

Without a token, or for a repository Kixel Quest does not serve, reads go to
GitHub as above; the output is the same either way. When Kixel Quest fails, the
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.

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
`POST /forge/<read>` takes one of `status`, `pulls`, `held`, or `watch` and
answers `{"value", "asOf"}`, the read's value and the time of the newest
webhook behind it. A 400 with `{"error"}` refuses a bad argument, such as a
malformed `--since`, which `quest` reports as a usage error. `quest/core` exports each read's types and their parsers;
`quest/github`'s `GitHubForge` answers the same reads from GitHub.

## Own a pull request

Before a session pushes to an existing PR, it takes the PR, so two agents
Expand Down
1 change: 1 addition & 0 deletions bun.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

22 changes: 10 additions & 12 deletions quest/m0/benchmark/records-endpoint.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,17 +23,20 @@ repository named by its remote (rejected: a committed `.quest.json`, which
no repository had committed yet).

- Delete the `.quest.json` reader (`CHECKOUT_CONFIG` in `src/cli/send.ts`)
and the help text naming it. The token file keeps one token for Kixel
Quest, the same one the [forge reads](/quest/m0/github-quota/forge-reads.md)
use.
and the help text naming it. Send to the Kixel Quest that
`kixelQuest()` in `src/cli/forge.ts` names, `https://kixel.quest` or
`QUEST_KIXEL_URL`, with the token the forge reads use: the one
`~/.config/quest/records.json` pairs with that URL.
- Kixel Quest refuses a whole upload naming a repository it does not index
or the sender cannot read, so the sender sends only the repositories
Kixel Quest says it serves, the same answer the forge reads use, and
keeps the rest on the host as it does today for a checkout with no
endpoint.
Kixel Quest says it serves, `KixelQuest.serves()`, the same answer the
forge reads use, and keeps the rest on the host as it does today for a
checkout with no endpoint.
- Put the token on each host, and start its sender with `quest records
install`, through kixel-ai/dotfiles, which owns the maintainer's host
configuration, not by hand.
configuration, not by hand. Only once Kixel Quest serves `GET /forge`
(kixel-ai/kixel.quest's `quest/m0/read-api.md`): with that token, every
forge read goes to Kixel Quest and fails until it answers.

Tests: a session in a checkout whose remote Kixel Quest serves is sent with
its `owner/repo`; one it refuses stays queued on the host; and the override
Expand Down Expand Up @@ -62,8 +65,3 @@ records rather than losing them.
https://kixel.quest/records -o /dev/null -w '%{http_code}'` prints `401`,
not `404`; its `quest/m0/deploy.md` automates deploys, and the maintainer
can run `just deploy` there meanwhile.

## Required

- [Forge reads](/quest/m0/github-quota/forge-reads.md) - `KixelQuest.serves()`
and the shared Kixel Quest token this sends with
41 changes: 0 additions & 41 deletions quest/m0/github-quota/forge-reads.md

This file was deleted.

9 changes: 3 additions & 6 deletions quest/m1/forge-writes.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,9 @@ our private repositories move onto Cloudflare Artifacts with Kixel Quest as
their whole forge, kixel-ai/kixel.ai first as the pilot; public repositories
stay on GitHub.

- Extend the [forge interface](/quest/m0/github-quota/forge-reads.md) with
the writes, typed in `quest/core` as its reads are. This quest owns their
- Extend the forge interface (`Forge` in `src/core/forge.ts`, with its
Kixel Quest backend in `src/cli/forge.ts`) with the writes, typed and
parsed in `quest/core` as its reads are. This quest owns their
shape: kixel-ai/kixel.quest serves it (`quest/m1/forge/pulls.md` there),
so build against a fake Kixel Quest and land first.
- A pick names the head the person saw, as `Quest-Land-Head` does on GitHub;
Expand All @@ -27,7 +28,3 @@ stay on GitHub.

Tests: against a fake Kixel Quest, quest opens a PR, edits its body, readies
it, resolves a thread, claims and holds it, and queues a pick of its head.

## Required

- [Forge reads](/quest/m0/github-quota/forge-reads.md) - the interface these writes extend
12 changes: 10 additions & 2 deletions src/cli/breakage.ts
Original file line number Diff line number Diff line change
@@ -1,7 +1,15 @@
// What a PR body says about breakage: the culprits its `## Caused by` names, and, for a culprit, how it was made and
// checked, as its own body records it.
import { type Culprit, FINDERS, type Finder, SIZES, type Seat, type Size, recordedRisk } from "../core";
import type { Repository } from "../github/client";
import {
type Culprit,
type Finder,
FINDERS,
recordedRisk,
type Repository,
type Seat,
type Size,
SIZES,
} from "../core";
import { recorded } from "./models-record";
import { parseReview } from "./review-record";
import type { Pull } from "./usage";
Expand Down
46 changes: 25 additions & 21 deletions src/cli/claims.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,20 +3,16 @@
// and `quest start` records a claim the same way, judging readiness by the upstream tree.
import { git } from "./git";
import { type Remote, readRemote, remoteRepository, requireRemote } from "./github";
import { type GitHubDependencies, type Repository, GitHub, object, repositoryPath, string } from "../github/client";
import {
type Claim,
type Holdings,
type OpenPull,
held as githubHeld,
openPullRequests,
questBranches,
} from "../github/claims";
import { type GitHubDependencies, GitHub, object, repositoryPath, string } from "../github/client";
import type { Claim, Forge, Holdings, OpenPull, Repository } from "../core";
import { questBranches } from "../github/claims";
import { type Snapshot, snapshot } from "./tree";

export interface ClaimDependencies {
/** Called only when the remote is on GitHub, so other forges need no token. */
github(): GitHubDependencies;
/** The forge answering reads of a repository on GitHub, such as its claims and open PRs. */
forge(repository: Repository): Promise<Forge>;
warn(message: string): void;
}

Expand All @@ -39,6 +35,8 @@ export interface Upstream {
defaultBranch: string;
/** Where this checkout's tree sits in the repository: empty at the top level, else a path ending in `/`. */
prefix: string;
/** The forge answering reads of `repository`, chosen on first use. */
forge(): Promise<Forge>;
} | null;
}

Expand Down Expand Up @@ -73,13 +71,21 @@ export async function upstream(root: string, remote: Remote, deps: ClaimDependen
// The README where this checkout's tree sits, which may be below the top level.
const prefix = git(root, ["rev-parse", "--show-prefix"]);
const up = await base(client, self, prefix);
let forge: Promise<Forge> | undefined;
return {
// Reach an ancestor the way the remote is reached, so the same credentials work.
git: up === self ? remote.name : /^https:/.test(source.url) ? up.https : up.ssh,
get push() {
return remote.used().push;
},
github: { client, repository: up.repository, head, defaultBranch: up.defaultBranch, prefix },
github: {
client,
repository: up.repository,
head,
defaultBranch: up.defaultBranch,
prefix,
forge: () => (forge ??= deps.forge(up.repository)),
},
};
}

Expand Down Expand Up @@ -173,7 +179,7 @@ export async function reach(root: string, name: string, deps: ClaimDependencies)
}

/**
* Which of `branches` someone holds, as {@link githubHeld} decides it on GitHub. `tips` are the
* Which of `branches` someone holds, as the upstream's forge decides it on GitHub. `tips` are the
* upstream's `quest/*` branches, when already read; the fork's are read through git too. Off GitHub,
* every branch pushed upstream holds its quest.
*/
Expand All @@ -191,15 +197,13 @@ export async function held(
.map((branch) => ({ branch, url: null, pull: null })),
landed: new Map(),
};
const { client, repository, head } = up.github;
return githubHeld(
client,
{
upstream: { repository, tips },
...(same(head, repository) ? {} : { fork: { repository: head, tips: remoteBranches(root, up.push) } }),
},
branches,
);
const { repository, head } = up.github;
const forge = await up.github.forge();
const sources = {
upstream: { repository, tips },
...(same(head, repository) ? {} : { fork: { repository: head, tips: remoteBranches(root, up.push) } }),
};
return (await forge.held(sources, branches)).value;
}

/**
Expand All @@ -220,7 +224,7 @@ export async function openDrafts(root: string, name: string, deps: ClaimDependen
deps.warn(`${name} is not on GitHub, so draft PRs were skipped`);
return [];
}
const pulls = await openPullRequests(up.github.client, up.github.repository);
const pulls = (await (await up.github.forge()).pulls(up.github.repository)).value;
return pulls.filter((pull) => pull.draft).sort((a, b) => a.number - b.number);
} catch (error) {
deps.warn(`draft PRs were skipped: ${error instanceof Error ? error.message : String(error)}`);
Expand Down
Loading
Loading