From 203c10d2128a14afe2031edff72dbdad7cc2b49c Mon Sep 17 00:00:00 2001 From: Devin Foley Date: Fri, 20 Nov 2026 10:32:11 -0800 Subject: [PATCH] fix(api): tell agents that issue count requires attention=blocked (#17596) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Agents find REST routes through the runner API catalog (`search_api`) and call them with `call_api` > - The catalog shows `GET /api/companies/{companyId}/issues/count` as "Count issues in a company". It gives no description and no query parameters > - The route only counts blocked issues that need attention. It returns 400 when the request does not include `attention=blocked` > - Agents read the summary as a generic counter. They call the route without the filter and get a 400. A hosted instance reported these 400 responses as failed HTTP operations > - This pull request adds the route contract to the Paperclip skill API reference. It also regenerates the catalog enrichment, so `search_api` returns the contract with the operation > - The benefit is that agents get the required filter and the correct alternative before they call the route. Runtime validation does not change ## Linked Issues or Issue Description No public issue exists. I searched open pull requests for `issues/count` and found no duplicate. **What happened?** An agent called `GET /api/companies/{companyId}/issues/count` with only a `labelId` filter. The server returned `400 issues/count currently requires attention=blocked`. The catalog entry that the agent read showed only the summary "Count issues in a company", so the agent had no way to know the filter was required. **Expected behavior** The catalog tells the agent that `attention=blocked` is required. It also lists the accepted filters, says that `limit` and `offset` are rejected, and tells the agent how to count anything else by paging through the issue list. **Steps to reproduce** 1. As an agent, call `search_api` with the query `count issues`. 2. Read the `GET /api/companies/{companyId}/issues/count` result. It has no description and no `skillReference`. 3. Call the route through `call_api` with `query: { labelId: "" }`. 4. The server returns 400. **Paperclip version or commit** `master` at 2e47c42fad91df8c040b33d3bda301f4a35264cf. **Deployment mode** Hosted. The behaviour is the same in every deployment mode, because the route validation and the catalog are core code. ## What Changed - `skills/paperclip/references/api-reference.md`: - Add a row for `GET /api/companies/:companyId/issues/count` to the Issues table. The row says that `?attention=blocked` is required and that other requests return 400. It names the accepted issue-list filters and says that `?limit=` and `?offset=` are rejected. For any other count, it says to page through `GET /api/companies/:companyId/issues` with `?limit=` (default 500, maximum 1000) and increasing `?offset=` until a page is empty. A short page is not the end, because the list route filters rows for restricted actors after the database applies the limit. - Merge the two `GET /api/issues/:issueId/heartbeat-context` rows into one. The generator keeps only the last row for a route, so the first description never reached the catalog. Merging also keeps every later heading on its current line. The generated capability contract and inventory record skill headings by line number, so they stay unchanged. - `server/src/services/native-runtime/runner-api-reference.ts`: regenerate with `node scripts/generate-runner-api-reference.mjs`. The count route gets a new entry, which the catalog attaches to the operation as `skillReference`. The heartbeat-context entry gets the merged description. - `server/src/services/native-runtime/runner-api-reference.test.ts`: new regression test. It searches the catalog for `count issues` and checks that the count operation's `skillReference` describes the contract and the paging rule. ## Verification - `node scripts/generate-runner-api-reference.mjs --check` passes. The generated file matches the skill reference. - `node packages/paperclip-runner/scripts/generate-capability-contract.mjs --check` and `node packages/paperclip-runner/scripts/check-capability-inventory.mjs` pass. On the first head they failed with "Generated contract drift: generated/capability/capabilities.yaml", the cause of the Typecheck, Build, Canary and Docker context failures there. - The new test failed on `master` (no `skillReference` on the count operation) and passed on the first head. That run covered the runner-api-reference, runner-api, hiring-operational-examples and openapi-routes suites (2019 + 1 tests) and `paperclip-skill-utils` (21 tests). - The sandbox used for this revision did not have room to install workspace dependencies, so I did not rerun vitest locally. Instead I checked the regenerated catalog entry for each string the test asserts. CI runs the full suites. - I did not run `pnpm -r typecheck` or the full suite locally. CI runs both. ## Risks - Low risk. The change is documentation plus generated catalog entries. - Route behaviour, authorization and the OpenAPI document do not change. - The OpenAPI summary for the route stays "Count issues in a company". A later change can also register the route in `server/src/routes/openapi.ts` with its query schema and error responses. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - Anthropic Claude Opus 5.5 (`claude-opus-5-5`), used as an agent with tool use (shell, test execution and the GitHub connector). ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 --- .../native-runtime/runner-api-reference.test.ts | 13 +++++++++++++ .../services/native-runtime/runner-api-reference.ts | 6 +++++- skills/paperclip/references/api-reference.md | 4 ++-- 3 files changed, 20 insertions(+), 3 deletions(-) create mode 100644 server/src/services/native-runtime/runner-api-reference.test.ts diff --git a/server/src/services/native-runtime/runner-api-reference.test.ts b/server/src/services/native-runtime/runner-api-reference.test.ts new file mode 100644 index 00000000000..33bb2467d13 --- /dev/null +++ b/server/src/services/native-runtime/runner-api-reference.test.ts @@ -0,0 +1,13 @@ +import { describe, expect, it } from "vitest"; +import { searchRunnerApi } from "./runner-api-catalog.js"; + +describe("runner API skill reference enrichment", () => { + it("tells agents that the issue count route requires the blocked attention filter", () => { + const operationId = "GET /api/companies/{companyId}/issues/count"; + const match = searchRunnerApi({ query: "count issues", limit: 10 }).results + .find((entry) => entry.operationId === operationId); + expect(match?.skillReference?.description).toContain("`?attention=blocked` is required"); + expect(match?.skillReference?.description).toContain("rejects `?limit=` and `?offset=`"); + expect(match?.skillReference?.description).toContain("page through `GET /api/companies/:companyId/issues`"); + }); +}); diff --git a/server/src/services/native-runtime/runner-api-reference.ts b/server/src/services/native-runtime/runner-api-reference.ts index cc6bfdbe9e8..0ff4be47633 100644 --- a/server/src/services/native-runtime/runner-api-reference.ts +++ b/server/src/services/native-runtime/runner-api-reference.ts @@ -81,13 +81,17 @@ export const runnerApiReference: Record