Skip to content
Merged
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
43 changes: 20 additions & 23 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -1944,23 +1944,20 @@ are read from the transcript on this host, and only their names and times
leave it. The split's notes are lines a model wrote, told to name no one and
quote no message.

A checkout names its endpoint in a committed `.quest.json`:

```json
{ "records": "https://kixel.example/records" }
```

and each user pairs a token with it in `$XDG_CONFIG_HOME/quest/records.json`
(`~/.config`), so a checkout naming another endpoint, as a hostile branch
might, is never sent the token or a record:

```json
{ "https://kixel.example/records": "token" }
```

The endpoint must be HTTPS, or HTTP to `localhost`. A checkout naming none, or
an endpoint the user holds no token for, sends nothing, and the hook says so
once as a system message.
Records go to [Kixel Quest](https://kixel.quest), the same one the
[forge reads](#read-through-kixel-quest) use, at its `/records`, with the token
`$XDG_CONFIG_HOME/quest/records.json` (`~/.config`) pairs with its URL. No
repository commits a config file: a record names its repository by `owner/repo`
from its checkout's `origin` (the repository its PRs open on, for a fork), and
the token is sent only to the URL the user's own file pairs it with. The URL is
`https://kixel.quest`, or HTTPS (HTTP to `localhost`) `QUEST_KIXEL_URL` for
another Kixel Quest, such as one running locally. A user holding no token for
it sends nothing, and the hook says so once as a system message.

Kixel Quest refuses a whole upload naming a repository it does not index or
the sender cannot read, so the sender asks `GET /forge` which repositories it
serves and sends only those. The rest are dropped from this host's queue, so an
unserved repository costs no GitHub requests, and the next stop says so once.

The `Stop` hook [`quest setup`](#configure-your-agent) installs for Claude Code
and Codex only queues the session under `$XDG_STATE_HOME/quest/records`. One
Expand All @@ -1982,23 +1979,23 @@ once per outage.

Each pass runs token-max on this host from the earliest queued session's first
instant, reads the PRs updated since then, or since its last upload for that
endpoint and repository read them, if earlier, so a fix merged after its
repository read them, if earlier, so a fix merged after its
sessions were sent still goes with the next one, labels each session's new
steps for its [time split](#time-splits), and posts
`{"records": [...], "breakages": [...]}`, the breakages being those the merged
PRs among them name under `## Caused by`, as `quest usage` reports them, with
`Authorization: Bearer <token>`, one upload per endpoint and repository, each
`Authorization: Bearer <token>`, one upload per repository, each
queued session with its sub-agents, which stop without the hook naming them.
Each upload is checked with `parseUpload` before it is posted. A 2xx drops the
sessions from the queue, unless the hook queued one again meanwhile. A 401 or
403 drops them and sends that endpoint nothing more until the token changes.
403 drops them and sends Kixel Quest nothing more until the token changes.
Any other failure keeps them queued, and the next stop says so once. A failing
endpoint and repository back off, waiting a minute and doubling up to six
hours, and sit out the passes meanwhile, so they never widen the others'
repository backs off, waiting a minute and doubling up to six
hours, and sits out the passes meanwhile, so it never widens the others'
window. token-max missing is retried each pass.

A deploy or alert reports what it found with `quest records incident`, which
posts one breakage at once to the checkout's endpoint and fails loud on any
posts one breakage at once to Kixel Quest and fails loud on any
answer but a 2xx, since nothing retries it:

```console
Expand Down
67 changes: 0 additions & 67 deletions quest/m0/benchmark/records-endpoint.md

This file was deleted.

3 changes: 1 addition & 2 deletions quest/m0/github-quota/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,8 +27,7 @@ Decided 2026-11-15 (maintainer, `/quest-plan` here):
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
([records endpoint](/quest/m0/benchmark/records-endpoint.md)).
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
Expand Down
31 changes: 19 additions & 12 deletions src/cli/forge.ts
Original file line number Diff line number Diff line change
Expand Up @@ -30,12 +30,8 @@ import {
import type { GitHubDependencies } from "../github/client";
import { GitHubForge } from "../github/forge";
import { pullRequest, readRemote, remoteHost } from "./github";
import { checkedEndpoint, tokenFor, tokensPath } from "./send";
import { kixelUrl, tokenFor, tokensPath } from "./tokens";

/** Kixel Quest's own URL. */
export const KIXEL_QUEST = "https://kixel.quest";
/** The variable naming another Kixel Quest, such as one running locally. */
export const KIXEL_QUEST_URL = "QUEST_KIXEL_URL";
/** The variable that, set to `github`, reads GitHub even where Kixel Quest serves the repository. */
export const FORGE = "QUEST_FORGE";

Expand All @@ -46,11 +42,8 @@ export interface ForgeDependencies {
now(): number;
/** Called only once a read goes to GitHub, so Kixel Quest's reads need no GitHub token. */
github(): GitHubDependencies;
}

/** The Kixel Quest `env` names, without a trailing slash. */
export function kixelUrl(env: NodeJS.ProcessEnv): string {
return checkedEndpoint(env[KIXEL_QUEST_URL] || KIXEL_QUEST, KIXEL_QUEST_URL).replace(/\/+$/, "");
/** What a Kixel Quest failure tells the person to do; by default, to read GitHub instead. */
remedy?: string;
}

/** The Kixel Quest `env` names, with the person's token for it; null without a token, or when reads are on GitHub. */
Expand Down Expand Up @@ -92,6 +85,16 @@ export async function forgeFor(
: new GitHubForge(deps.github());
}

/** Kixel Quest refused the person's token, as a sender must tell from a failure that may pass. */
export class Refused extends Error {
constructor(
message: string,
readonly status: number,
) {
super(message);
}
}

/** A PR named on the command line, and whether Kixel Quest hosts its repository rather than GitHub. */
export interface Located {
pull: PullRequest;
Expand Down Expand Up @@ -194,7 +197,7 @@ export class KixelQuest {

/** A failed request, naming the setting that reads GitHub instead where Kixel Quest does not host the repository. */
#failed(method: string, path: string, why: string): Error {
const instead = this.hosted ? "" : `; set ${FORGE}=github to read GitHub`;
const instead = this.hosted ? "" : `; ${this.deps.remedy ?? `set ${FORGE}=github to read GitHub`}`;
return new Error(`Kixel Quest (${this.url}) failed ${method} ${path}: ${why}${instead}`);
}

Expand Down Expand Up @@ -228,7 +231,11 @@ export class KixelQuest {
throw failed(error instanceof Error ? error.message : String(error));
}
if (response.status === 401 || response.status === 403)
throw failed(`it refused the token ${tokensPath(this.deps.env)} pairs with it (HTTP ${response.status})`);
throw new Refused(
failed(`it refused the token ${tokensPath(this.deps.env)} pairs with it (HTTP ${response.status})`)
.message,
response.status,
);
// 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
37 changes: 14 additions & 23 deletions src/cli/main.ts
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,6 @@ import {
forgeFor,
hostedForge,
hostedRepository,
kixelUrl,
locate as locatePull,
} from "./forge";
import { PENDING_MS } from "./admission";
Expand Down Expand Up @@ -106,18 +105,11 @@ import { CHECKED_CONTEXT, USER_ASKED, questRoot } from "./rules";
import { messageLines, messages } from "./messages";
import { logWait, pullWaitKind, readWaits } from "./waits";
import { readCalls } from "./calls";
import {
CHECKOUT_CONFIG,
SEND_INTERVAL,
background,
parseInstant,
reportIncident,
runSender,
tokensPath,
} from "./send";
import { SEND_INTERVAL, background, parseInstant, reportIncident, runSender } from "./send";
import { installSender, uninstallSender } from "./service";
import { heal, init, stubFindings, uninstall } from "./setup";
import { describe, notUpstream, releaseQuest, startQuest } from "./start";
import { KIXEL_QUEST_URL, kixelUrl, tokensPath } from "./tokens";
import { CONTEXT, GUIDE, GUIDE_SECTIONS, SKILLS, guideSections, sectionHeading, skill } from "./skills";
import { type Terminal, Theme } from "./theme";
import { type Snapshot, checkout, collect, load, snapshot, under } from "./tree";
Expand Down Expand Up @@ -1413,21 +1405,20 @@ export function main(argv: string[], out: Output): number | Promise<number> {
);
});

const recordsCommand = program
.command("records")
.summary("Send agent sessions' records to the Kixel Code endpoint their checkout names");
const recordsCommand = program.command("records").summary("Send agent sessions' records to Kixel Quest");
recordsCommand
.command("sender")
.summary("Run the user's record sender until stopped, as its service does")
.description(
"Send each session record the stop hook queued, with the records of its sub-agents on this host, to the " +
`endpoint its checkout's ${CHECKOUT_CONFIG} names as records, posting {"records": [...], "breakages": [...]}, the breakages the merged PRs among them name under ## Caused by, with the token ` +
`${tokensPath()} pairs with that endpoint as a bearer token, one upload per endpoint and repository, ` +
"Send each session record the stop hook queued, with the records of its sub-agents on this host, to " +
`Kixel Quest's /records (https://kixel.quest, or the one ${KIXEL_QUEST_URL} names), posting {"records": [...], "breakages": [...]}, the breakages the merged PRs among them name under ## Caused by, with the token ` +
`${tokensPath()} pairs with its URL as a bearer token, one upload per repository, ` +
`then again every ${SEND_INTERVAL / 1000} seconds until stopped, at low priority. A record is built as quest usage ` +
"builds it, from token-max's sessions on this host since the earliest queued session's first instant and " +
"the PRs updated since then, and replaces its earlier copy, so a resend never doubles. A sent session whose " +
"the PRs updated since then, and replaces its earlier copy, so a resend never doubles. A repository Kixel " +
"Quest does not serve, as it says on GET /forge, has its sessions dropped, said once. A sent session whose " +
"latest branch, or a sub-agent's, heads no PR yet is sent again, with its sub-agents, once a pass for its " +
"repository reads a PR opened on that branch, until its transcript is gone. An endpoint that " +
"repository reads a PR opened on that branch, until its transcript is gone. A Kixel Quest that " +
"refuses the token (401 or 403) is sent nothing more until the token changes; any other failure keeps the " +
"sessions queued, retried after a minute and then twice as long each time up to six hours, and the next " +
"stop hook says so once. Before a record is built, a cheap model, " +
Expand Down Expand Up @@ -1468,13 +1459,13 @@ export function main(argv: string[], out: Output): number | Promise<number> {
"A stable ID for the incident, such as the alert's URL; a later report with it replaces this one",
)
.description(
"Post one breakage to the endpoint this checkout's " +
`${CHECKOUT_CONFIG} names, with the token ${tokensPath()} pairs with it, as {"records": [], "breakages": [...]}. ` +
"Post one breakage to Kixel Quest's /records " +
`(https://kixel.quest, or the one ${KIXEL_QUEST_URL} names), with the token ${tokensPath()} pairs with its URL, as {"records": [], "breakages": [...]}. ` +
"Without --pr the incident is open, its culprit unknown; report the same ID again with --pr to close it on " +
"its culprit, whose tier, size, writers, and local reviewers are read from its PR body, or name it on the " +
"culprit's ## Caused by line of the fix, as (incident <id>), whose record then replaces it. It posts at once " +
"and retries nothing, for a deploy or alert to call.\n\nUses GH_TOKEN, GITHUB_TOKEN, or gh auth token. " +
"Exits 0 when the endpoint took it, 2 for invalid arguments, and 1 for other failures, refusal included.",
"Exits 0 when Kixel Quest took it, 2 for invalid arguments, and 1 for other failures, refusal included.",
)
.addOption(new Option("--found <by>", "Who or what found it").choices(FINDERS).makeOptionMandatory())
.option("--pr <number>", "The PR that caused it", positiveInteger("--pr"))
Expand Down Expand Up @@ -2108,8 +2099,8 @@ export function main(argv: string[], out: Output): number | Promise<number> {
"Stop and SubagentStop refuse to end the " +
"turn, naming each command, while a `quest gate` command the ending agent started runs in Claude " +
"Code's background: one whose background ID its transcript holds. Otherwise Claude Code's and Codex's Stop " +
`queue the session's record for the endpoint the checkout's ${CHECKOUT_CONFIG} names, for quest records ` +
"sender to send; a checkout naming none, an endpoint the user holds no token for, or a host whose sender " +
"queue the session's record for Kixel Quest, for quest records " +
"sender to send; a user holding no token for it, or a host whose sender " +
"does not run says so once as a system message, as does a sender's failure. Exits 1 on malformed input or an event it " +
"does not handle.",
)
Expand Down
Loading
Loading