mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-16 03:31:44 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - The GitHub chat channel keeps one response comment for each GitHub request. Two background sweeps (acknowledgements and terminal responses) and the acknowledgement step read the latest run of the assigned agent for the request's issue with `readGitHubResponseRun` > - That function sends two statements. Both match runs with `coalesce(native_issue_id::text, context_snapshot->>'issueId') = <issue id>`. No index has that expression, so each statement reads every run of the agent and decompresses the large `context_snapshot` of each legacy run > - On a hosted test database, these two statements were the two most expensive statements by database time. In a 701 s window, each ran 6.7 times a second, for 203 s and 137 s of database time (about 30 ms and 20 ms for each call). Together they kept about half of one database session busy > - This pull request reads the latest run with two index lookups (native binding, and legacy context without a native binding), the same way #20671 changed the terminal-response sweep. It decides request ownership on that one run in the same statement > - The benefit is that each call reads a few index entries in one statement instead of the agent's whole run history in two statements. The results do not change, and no migration is necessary ## Linked Issues or Issue Description Refs #20671 (the same rewrite for the terminal-response discovery page; its Risks section names this function as the remaining case). **What existing behavior does this improve?** `readGitHubResponseRun` in `server/src/services/chat-channels/github/response-run-state.ts`. The GitHub acknowledgement sweep calls it once for each candidate request. The terminal-response sweep and the acknowledgement step call it through `githubResponseExecution`. **Subsystem affected** GitHub chat channel: request acknowledgement and terminal-response recovery. **Current behavior** The function sends two statements: 1. The latest run of the agent for the issue that woke for the request: `heartbeat_runs` joined to the inbound `chat_message_links` row of the delivery on `wakeCommentId` or `wakeCommentIds`, ordered by `created_at desc`, limit 1. 2. The latest run of the agent for the issue, with the `responseRunColumns` projection, ordered by `created_at desc, id desc`, limit 1. Both statements filter on `coalesce(native_issue_id::text, context_snapshot->>'issueId') = $issueId`. The planner can only use `heartbeat_runs_company_agent_started_idx` or `heartbeat_runs_company_created_at_desc_idx`. It reads all runs of the agent and evaluates the `coalesce` on each row, which decompresses the context of each legacy run. On the hosted test database, `heartbeat_runs` has about 31,000 rows and 1.96 GB, because `context_snapshot` is large. **Proposed behavior** One statement: - The latest run ID comes from two disjoint branches, each `order by created_at desc, id desc limit 1`: runs with `native_issue_id = $issueId` (through `heartbeat_runs_company_native_issue_contract_id_uq`), and runs with `native_issue_id is null and context_snapshot->>'issueId' = $issueId` (through `heartbeat_runs_company_ctx_issue_created_idx`). Together the branches are exactly the rows where the old `coalesce` equals the issue ID. - The statement reads that one run by primary key with the same `responseRunColumns` projection. - An `exists` subquery on the inbound `chat_message_links` row of the delivery decides whether that run woke for the request. It uses the same `wakeCommentId` / `wakeCommentIds` match as before, but on one run only. - When the issue ID is null, the function returns no run without a query. The old statements could not match a null issue ID either. **Reason and benefit** These were the two most expensive statements on the hosted test database. On a local fixture with the hosted shape, the median call goes from 111.6 ms to 1.03 ms (about 108 times faster), and the buffers for one call go from about 73,000 to 98. **Breaking changes** None. The function signature, the returned run, and the ownership result do not change. ## What Changed - `readGitHubResponseRun` reads the latest run of the agent for the issue through the two index-backed branches, and decides request ownership on that run in the same statement. Two statements become one. - Add `response-run-state.test.ts`. It runs the old two-statement function (kept in the test as the oracle) and the new function on the same inputs, and it requires equal results. It also requires a plan bound: one call must read fewer than 150 `heartbeat_runs` rows while the agent has 1,500 unrelated runs. - Add `scripts/benchmark-github-response-run-state.ts`. It loads the baseline module from a given commit, compares the complete output of both versions for every input, measures both, and prints the plans. ## Verification Why the old statements were slow, and the thesis: each statement filters the agent's whole run history with an expression that no index has, and detoasts the context of every legacy run. If each precedence branch uses its own issue index and ownership is checked on the one latest run, the cost no longer depends on the agent's run count, and the results stay identical. Red/green regression test: - `cd server && npx vitest run src/services/chat-channels/github/response-run-state.test.ts` - Red (test file on the old `response-run-state.ts`): the plan bound fails with `expected 3597 to be less than 150`. The equivalence test passes, because the oracle is the old code. - Green (this change): 2 of 2 pass. The equivalence fixture has two companies, two agents each, 60 issues each, and one or two GitHub requests for each issue. Runs cover these cases: native binding, legacy context without a native binding, a native binding to another issue while the legacy context names this issue, another agent, another company, `wakeCommentId`, `wakeCommentIds` as an array, `wakeCommentIds` as a JSON string, a link to the outbound message of the delivery, a link to another company's comment, a link to the sibling request of the same issue, a request with no inbound comment, ties on `created_at`, and a null issue ID. It also calls with another company's endpoint. The test requires more than 20 results in each outcome (owned, latest run not owned, no run) and both binding kinds. Local benchmark with the hosted shape: ```sh pnpm --filter @paperclipai/server exec tsx ../scripts/benchmark-github-response-run-state.ts --baseline-ref=3c3e6c2d75 ``` Fixture (synthetic): one company, 4 agents with about 7,750 runs each (31,000 runs), 2,000 issues, 300 GitHub requests. Each run has about 60 KiB of incompressible context, and `heartbeat_runs` is 1,932 MB. Runs are native or legacy at random, and about half link to the request comment. Embedded PostgreSQL 18.1 on an Apple laptop. The hosted database is Neon, so absolute times are local measurements only. The benchmark compares the complete output for all 600 inputs (262 owned, 329 latest run not owned, 9 no run): equal. It then times 20 inputs with runs (two agents), with 2 warmups and 7 alternating samples. | | Statements per call | Median ms per call (range) | Buffers for one call | | --- | --- | --- | --- | | Before | 2 | 111.6 (100.9–240.5) | 18,358 hit + 26,498 read, then 14,997 hit + 13,489 read | | After | 1 | 1.03 (0.81–1.39) | 80 hit + 18 read | Plans for one call. Before: statement 1 is a `Bitmap Heap Scan` on `heartbeat_runs_company_agent_started_idx` that removes 7,674 rows by filter (75.7 ms). Statement 2 is an `Index Scan` on `heartbeat_runs_company_created_at_desc_idx` that removes 19,801 rows by filter (60.2 ms). After: one `Index Scan` on `heartbeat_runs_pkey`. Its `InitPlan` is a `Merge Append` of two `Limit` index scans on `heartbeat_runs_company_native_issue_contract_id_uq` and `heartbeat_runs_company_ctx_issue_created_idx`, and its `SubPlan` is one `Index Scan` on `chat_message_links_delivery_idx` (0.128 ms). Other checks: - `cd server && npx vitest run src/__tests__/chat-channels.integration.test.ts -t ithub`: 104 passed (all GitHub chat-channel integration tests, including the acknowledgement and terminal-response sweeps). - `cd server && npx tsc --noEmit`: passed. - `pnpm verify` exited 2 because a file under `scripts/` changed, which requires the broad CI coverage. Required CI covers the rest. Why the function runs 6.7 times a second. The acknowledgement sweep and the terminal-response sweep rebuild their candidate set when a hint arrives, and they call this function once for each candidate on each rebuild. A run milestone for a run with no issue (for example, every status change of a run without a task in `setRunStatus`, or a comment merged into an active run in the wake queue) sends a company-wide hint to both sweeps. So in a busy company, both sweeps rebuild about once a second (their minimum pass interval), and each rebuild reads every parked candidate again, although nothing about those candidates changed. In a local reproduction with 8 parked candidates (4 for each sweep) and the real coordinator and workers, 10 company-wide milestone hints a second gave 8.75 calls a second; 1 hint a second gave 7.98 calls a second; 10 hints a second for an unrelated issue gave 0 calls; and no hints gave 0 calls. So the hosted rate is consistent with about 7 parked GitHub requests in one company and a steady stream of company-wide run milestones. This pull request makes each call cheap. A separate pull request will address the repeated rebuilds. ## Risks - Low risk. The change is one function. The run match is the same set of runs: `native_issue_id::text = <uuid text>` is equal to `native_issue_id = <uuid>` for the canonical UUID text that callers pass (the issue IDs come from UUID columns), and a null `native_issue_id` makes the old `coalesce` use the legacy context. - Ownership: the old code compared the latest run that woke for the request (ordered by `created_at` only) with the latest run (ordered by `created_at, id`). That is true exactly when the latest run woke for the request, except when two runs that both woke for the request tie on `created_at` with the latest run. In that case the old result depended on the physical row order. The new code always returns the deterministic answer (the latest run woke for the request). - The number of calls does not change in this pull request. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), Anthropic. Used through Claude Code with tool use (shell, file edits, and local PostgreSQL benchmarks). ## 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 - [x] All Paperclip CI gates are green - [x] 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>