Files
PaperClipAI/server
Devin FoleyandClaude Opus 5.5 203c10d212 fix(api): tell agents that issue count requires attention=blocked (#17596)
## 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:
"<label-id>" }`.
4. The server returns 400.

**Paperclip version or commit**

`master` at 2e47c42fad.

**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 <noreply@anthropic.com>
2026-11-20 10:32:11 -08:00
..