35 lines
2.4 KiB
Markdown
35 lines
2.4 KiB
Markdown
# quc
|
|
|
|
Hand an agent your repo, sit in the chair, watch. Live at https://quc.yolopreneur.lol/ (spec: teahubxyz/time#220).
|
|
|
|
One Cloudflare Worker, no dependencies, no build step. `npm start` serves it on :8787 (offline answers unless `VENICE_API_KEY`
|
|
is set), `npm test` runs the tests, `npm run deploy` deploys (needs `CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_ACCOUNT_ID`, and
|
|
`VENICE_API_KEY` for real models) and waits for `/api/health`.
|
|
|
|
## How a run works
|
|
|
|
1. **Start**: a public GitHub URL and one line of task. One run at a time per visitor (a cookie), 5 runs a day each, 300 a
|
|
day in all (`RUNS_PER_DAY`, `RUNS_PER_DAY_ALL`).
|
|
2. **The cage**: quc downloads the repo's tarball from GitHub and keeps the readable text files (caps: 15 MB download, 2,000
|
|
files, 40 KB a file, 4 files changed, 10 minutes). Nothing from the repo is executed, and nothing is pushed anywhere.
|
|
3. **Steps**: the chair page calls `POST /api/runs/:id/step` again and again; each call does one thing (clone, plan, rewrite
|
|
one file, wrap up), so every request stays short. A coding model (`CODER_MODEL`, default Qwen3 Coder via Venice) plans and
|
|
rewrites whole files; Grok (`PERSONA_MODEL`, default `grok-4-3` via Venice) narrates. Diffs, commits and commentary are
|
|
appended to the run's event log.
|
|
4. **The chair**: the page shows the commentary and the diffs, read-only. Only the owner sees the safeword and the box.
|
|
5. **Safeword**: ends the run at once and throws the edits away (the replay still shows what happened).
|
|
6. **Magic words** (typed in the box, matched loosely; the persona drops hints, so keep them out of marketing copy):
|
|
1. "may I say something": notes. Anything typed after this is passed to the agent as a note.
|
|
2. "not that one": vetoes. Type a file's path and the agent reverts and skips it.
|
|
3. "my repo, my rules": takes the wheel. The run ends as `unlocked` and the patch is yours.
|
|
Anything else gets mocked.
|
|
7. **Replay**: the same URL, for anyone: a scrubber over every event, plus the aftermath card and the patch download.
|
|
|
|
Storage is a KV namespace (`time-quc`): `run:<id>`, `events:<id>`, `work:<id>` (repo text and edits), `active:<visitor>`,
|
|
`cap:<day>:*`, `lock:<id>`. KV is eventually consistent and has no compare-and-set; a Durable Object per run is the upgrade
|
|
when that matters.
|
|
|
|
## Pipeline
|
|
|
|
`.github/workflows/quc.yml` deploys on pushes to `quc/**` on main, and `ci.yml` runs `npm test --prefix quc` on PRs.
|