All jobs

Add Cursor Pagination to a chi API from a Linear Issue

Yes. Label the Linear issue and an agent replaces offset paging in your chi list handler with a keyset cursor, fixes the limit parsing on the way, and opens a PR.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent starts from the Linear issue and the repository in its own sandbox, and reads the list handler the issue names before touching it. In an API laid out like dhax/go-base, GET /admin/accounts is list in api/admin/accounts.go: it calls database.NewAccountFilter(r.URL.Query()), hands the filter to AdmAccountStore.List in database/admAccountStore.go, and answers accountListResponse with an accounts array and a count. AccountFilter.Apply turns the filter into a bun query with Limit, Offset, one Where("? = ?", bun.Ident(key), value) per leftover query parameter and an Order per order value, and List runs it with ScanAndCount, so every page costs a full count of the matching rows. The accounts table from database/migrations/1_initial.go has a serial id primary key, created_at, email (unique), name, active and roles, and go.mod pins uptrace/bun v1.2.15 and go-chi/chi/v5 v5.4.0.

Reading NewAccountFilter it finds a bug the issue did not mention: f.Limit = int(limit[0] - '0') and the same line for offset parse only the first character, so ?limit=25 asks for 2 rows and ?limit=100 asks for 1. The agent fixes both with strconv.Atoi, keeps the default of 10, caps limit at 100 and answers a 400 through the existing ErrRender path for anything that is not a positive integer. It says in the pull request that this is a behavior change for any client that relied on the old parsing, and that offset stays supported for one release so existing callers keep working while they move.

The cursor itself is keyset on id: an after query parameter carrying a base64url string that decodes to the last id of the previous page. Apply adds Where("id > ?", afterID), forces Order("id ASC") and asks for limit + 1 rows; List drops the extra row and reports whether there was one. The agent keeps ScanAndCount only for the first page, where count still reports the total, and uses Scan for cursor pages, which is the point of the change. A request that sends both after and order is refused with a 400, because an arbitrary sort order and a keyset on id cannot both hold, and the pull request explains why rather than silently ignoring one. The response gains a next field with the encoded cursor, built in newAccountListResponse, and the agent leaves the accounts array as it is so a client that ignores next still reads the first page it always read. A tampered cursor that does not decode answers 400 like a bad {accountID} does in accountCtx.

The AccountStore interface in api/admin/accounts.go is already mocked-shaped, so the agent adds api/admin/accounts_test.go on the pattern of auth/pwdless/api_test.go: an httptest.Server with the admin router, a fake store that returns a fixed slice, and cases for limit=25 now meaning 25, the after cursor round trip, the capped limit, the rejected after plus order combination and a garbage cursor. For the real query it installs Postgres with apt-get in its sandbox, runs go run main.go migrate, starts go run main.go serve, creates a few accounts through POST /admin/accounts with the bootstrap admin from database/migrations/2_bootstrap_users.up.sql, and walks /admin/accounts?limit=2 by following next until it is empty. It runs go test -v ./..., the command .github/workflows/test.yml runs, and regenerates routes.md with go run main.go gendoc -r, which lists every route and its middleware from the router, so the generated file matches the code.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Replace offset pagination on the admin accounts list in this chi API with a keyset cursor. Read api/admin/accounts.go, api/admin/api.go, database/admAccountStore.go, database/migrations/1_initial.go, database/migrations/2_bootstrap_users.up.sql, auth/pwdless/api_test.go, cmd/gendoc.go, routes.md and go.mod first. NewAccountFilter parses limit and offset from their first character only; fix both with strconv.Atoi, keep the default limit of 10, cap it at 100 and answer 400 on anything that is not a positive integer. Add an after parameter, a base64url cursor holding the last id, that adds where id greater than the cursor, forces order by id ascending and asks for limit plus one rows; refuse a request that sends both after and order with a 400 and say why in the pull request. Keep ScanAndCount and the count field for the first page only. Add a next field with the encoded cursor to the list response and leave the accounts array unchanged. Keep offset working for one release and say so. Write api/admin/accounts_test.go with an httptest server and a fake AccountStore covering the limit fix, the cursor round trip, the cap, the refused after plus order, and a garbage cursor. Install Postgres in your sandbox, run the migrations, start the server, create accounts as the bootstrap admin, walk /admin/accounts?limit=2 by following next, and paste the walk and go test -v ./... into the pull request. Regenerate routes.md with go run main.go gendoc -r. Change nothing in create, get, update or delete.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

The pull request links the Linear issue, changes database/admAccountStore.go and api/admin/accounts.go, adds api/admin/accounts_test.go and updates routes.md. Its description pastes the go test -v ./... output, the curl walk of /admin/accounts?limit=2 with the next value from each page fed into the following request and an empty next on the last, and the SQL bun ran, which this service prints when started with --db_debug because DBConn adds the bundebug hook, so the reviewer sees the WHERE id > ? and LIMIT 3 in the statement that ran.

The first page of /admin/accounts with no parameters answers what it always answered, plus next. The visible changes are that limit=25 now returns 25 rows rather than 2, that a limit over 100 is capped, and that a cursor page skips the count query. The description lists each of these as a line a reviewer can disagree with.

Before merging, a reviewer decides whether offset should go now or after the deprecation period the agent wrote in, whether count on the first page is worth its query, and whether an id cursor is the order their admin client wants or whether a created_at keyset, which needs a composite (created_at, id) cursor and an index to match, should be the follow-up the pull request describes.

Run it on every Linear issue labelled agent

Add an automation to the Project with this prompt and a linear trigger on linear.issue.labeled with the label you reserve for the agent in its labels. Each labelled issue starts one run with the issue as its context, on its own branch, and the trigger adds the issue after the prompt rather than filling in a placeholder; a change made by an app integration never fires it, so a comment the agent posts on the issue does not start a second run.

The automation's max_runs_per_hour cap holds a label applied across a backlog to that many runs an hour: a fire past it is created queued and starts once the hour has room, and one past a second hour's worth is skipped as rate_limited until the issue is labelled again. From your own server, the same run starts with this request and the issue URL in resources, and a request_id that is a UUID v5 of the issue id makes a retried start return the run already began.

The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.

Why run it on Rush?

A cursor change is small in the diff and large in what can go wrong: a limit + 1 off by one, a cursor on a column that is not unique, an order parameter that silently breaks the keyset, and in this codebase a limit parser that was already wrong. The agent proves each case against the real service in its own sandbox, with Postgres installed, the migrations applied and the pages walked with curl, and the pull request carries that walk rather than a promise.

The transcript keeps every command and its output, so the reviewer reads the SQL that ran, the headers each page returned and the test summary without checking the branch out. Several list endpoints across services can be converted at once, each run in its own sandbox with its own database, and nothing merges until a person reads the diff.

Frequently asked questions

Why fix the limit parsing when the issue only asked for a cursor?

Because the cursor is built on limit, and limit[0] - '0' reads one digit, so limit=25 would page in twos. Leaving it would make the new next links wrong on the first request. The fix is three lines with strconv.Atoi, it is covered by the new test, and the pull request lists it as its own behavior change so a reviewer can object.

Why is the cursor on id rather than created_at?

A keyset must be on a unique, indexed ordering, or rows that share a value at a page boundary are skipped or repeated. id is the serial primary key of accounts. created_at defaults to the insert time and is not unique, so a keyset on it needs a composite (created_at, id) cursor and a matching index, which the pull request names as the next step rather than guessing at the order your admin client wants.

What happens to clients that send offset?

They keep working for one release: offset is still parsed, now correctly, and applied when no after is present. The response carries next either way, so a client can switch when it is ready. The pull request says which release removes offset, and that line is for the reviewer to change.

Why refuse after together with order?

The cursor encodes a position in an id ordering. If a client also asks for order=name, the id > ? condition no longer means the next page, it means an arbitrary subset. Answering 400 with a message is clearer than returning rows that look like a page and are not.

Does it touch the other filter parameters?

No. The equality filters that Apply builds from leftover query parameters, such as active=true, still apply on every page, including cursor pages, because the id > ? condition is added beside them rather than in place of them. The test for the cursor round trip sends a filter too, so that combination is covered.

More chi jobs

The same job on other stacks

Keep reading