Add Cursor Pagination to a Django REST Framework API from a Linear Issue

The agent starts from the Linear issue and the repository in its own cloud sandbox, and reads how pagination is done before it adds a second kind. In a project laid out like HackSoftware/Django-Styleguide-Example, styleguide_example/api/pagination.py holds a get_paginated_response(*, pagination_class, serializer_class, queryset, request, view) helper and a LimitOffsetPagination subclass with default_limit = 10, max_limit = 50 and a get_paginated_response that returns limit, offset, count, next, previous and results in that order. styleguide_example/users/apis.py uses it in UserListApi, which nests a Pagination class with default_limit = 1, validates id, is_admin and email through a FilterSerializer, and hands user_list(filters=...) to the helper. styleguide_example/users/selectors.py builds that queryset as BaseUser.objects.all() filtered by BaseUserFilter, with no ordering at all, which is the first thing a cursor needs.

It reads the model next. BaseUser in styleguide_example/users/models.py extends BaseModel from styleguide_example/common/models.py, so it carries created_at with db_index=True and default=timezone.now, plus updated_at, a unique email, is_active, is_admin and a jwt_key. A cursor over created_at alone can repeat or skip rows when two users share a timestamp, so the agent orders by ("-created_at", "-id") and says in the pull request why both fields are there. It then writes a CursorPagination subclass in api/pagination.py on top of rest_framework.pagination.CursorPagination, with a page_size, a max_page_size and that ordering, and gives it the same shape of get_paginated_response the limit-offset class has, minus count, which a cursor cannot give without a second query. The get_paginated_response helper already takes any pagination_class, so UserListApi switches by changing its nested Pagination base class and nothing else in the view.

The tests follow the one that already exists. styleguide_example/api/tests/pagination/test_get_paginated_response.py builds an ExampleListApi with APIRequestFactory, creates users through user_create, and asserts the exact OrderedDict of the first page, including the next link http://testserver/some/path?limit=1&offset=1. The agent adds a sibling test for the cursor class that creates three users, requests the first page, follows the cursor query parameter it gets back, checks that the second page carries the remaining rows and a previous link, and checks that a user created between the two requests does not shift the page. It runs the suite the way .github/workflows/django.yml does: pytest with DJANGO_SETTINGS_MODULE = config.django.test from pytest.ini, where config/django/test.py swaps in MD5PasswordHasher and an in-memory cache, against the postgres service the workflow starts.

Before opening the pull request it runs the other two checks from that workflow, ruff check . under the 120-column pyproject.toml configuration and mypy --config mypy.ini styleguide_example/, which loads mypy_django_plugin and mypy_drf_plugin, and it updates the "Example List API" section of README.md, which shows the limit/offset response shape for /api/users/, so the documented shape matches the endpoint the issue changed. Endpoints the issue does not name keep LimitOffsetPagination.

What comes back is a pull request on its own branch that changes styleguide_example/api/pagination.py to add the cursor class, styleguide_example/users/apis.py to use it in the views the issue names, a new test module under styleguide_example/api/tests/pagination/, and the response example in README.md. The description links the Linear issue, shows a first-page response with its next cursor link, and gives the ordering and the reason for the tie-breaker on id.

The transcript at GET /o/{org}/sessions/{id}/messages holds the ruff, mypy and pytest runs with their full output, and GET /o/{org}/p/{project}/sessions/{id}/changes lists each changed file with its diff. Checks that do not pass end the run needs_review rather than as a pull request that claims to be green.

Before merging, a reviewer checks that the ordering matches an index (created_at is indexed on BaseModel; the pair with id uses the primary key), that no endpoint outside the issue changed, and that clients which read count from the old response have a plan for its absence. A follow-up on the same session can switch a second endpoint once the first is in.

In the console, add an automation to the Project with this prompt and a linear trigger on linear.issue.labeled, filtered to the agent label and to the team whose issues name endpoints. When someone labels an issue such as "users list should page by cursor, offset pages drift under inserts", the trigger puts the issue after the prompt and the run scopes itself to the endpoints it names. Only label changes made by a person in your Rush org fire the trigger; changes made by an app integration never do, and the automation starts at most max_runs_per_hour runs in an hour.

From your own server, the same body goes to POST /o/{org}/sessions with the repository in resources and the issue's URL beside it, read through your Linear connection, plus a request_id made from the issue id so a retried call does not open a second pull request for the same issue.

Pagination changes look small and break quietly: a cursor over a non-unique column skips rows, and the only way to see it is to insert data between requests and read both pages. In its own sandbox the agent runs the real test database the workflow uses, writes that scenario as a test, and runs ruff, mypy and pytest exactly as django.yml does before it opens anything.

The record stays with the result. Every command and its output is in the transcript, the diff is readable from the session, and several issues can run at once, each in a separate sandbox, so a cursor change on one endpoint never waits on an unrelated one.

Does it switch every list endpoint?

Why order by created_at and id rather than created_at alone?

What happens to the count field?

Does it need Postgres to run the tests?