mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-16 11:59:26 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - One server process stores every event of every running native agent in `heartbeat_run_events` > - After #21460, text deltas commit in batches, but each batch still takes five statements: BEGIN, the run lock, a replay probe, one insert, and COMMIT. A single event without a wake takes four > - In the agent scaling load model, the process issues about 36 statements per agent per second and saturates its one thread between 200 and 400 agents > - This pull request writes a batch of in-order native events, or one such event, with one statement that commits on its own > - The benefit is about half the statements per agent, less CPU per agent on the main thread, and less time on a pool connection, with the same rows, receipts, cursor and locks ## Linked Issues or Issue Description Refs #21460 (batched deltas). Refs #21435 (source cursor). Refs #21418 (agent scaling plan and load model). **What existing behavior does this improve?** The append of native source events that continue their source's stored cursor: batched text deltas, the first delta after another event, and every other native event that registers no wake. **Subsystem affected** Server run event ingest: `server/src/services/heartbeat-run-events.ts`, and the port comment in `paperclip-control-plane-port.ts`. **Current behavior** A delta batch takes BEGIN, a run lock read (`for no key update`), a replay probe, one insert, and COMMIT: five statements. One delta that commits at once takes four. In the load model at 200 agents the process sends about 6,700 statements per second at event-loop utilization 0.72. **Proposed behavior** The same append is one statement. Its update of the run row takes the same row lock. It requires the stored cursor to end just before the batch, requires the `next_event_seq` that its own snapshot read, and finds no replayed event. Then it moves the sequence and the cursor and inserts every row. If any check fails, it writes nothing and the append takes the existing locked transaction. **Reason and benefit** Fewer statements free the main thread and the shared pool for other agents. In the load model at 200 agents, statements per second fall from about 6,700 to about 3,300 and event-loop utilization falls from 0.72 to 0.56. **Breaking changes** None. No schema change. Rows, receipts and the cursor are the same. Servers from before this change keep working on the same runs. ## What Changed - `appendNewNativeSourceEvents` (`heartbeat-run-events.ts`) is one statement: a CTE reads `next_event_seq` from the statement snapshot, an `update heartbeat_runs ... returning` locks the run row and moves `next_event_seq` and the source cursor, and an `insert ... select from jsonb_array_elements($9)` writes every row. The text is fixed, with nine bind parameters for any batch size. - **Why the `next_event_seq` check.** A statement that waits for the run row lock keeps the snapshot it took before the wait. Its replay probe cannot see events that the lock holder committed. Every event append (native, ordinary, the run coordinator store, the retry queue) moves `next_event_seq` in its own transaction. So the update requires the value that its snapshot read. PostgreSQL re-checks that condition on the newest row version after the wait, and any append committed meanwhile makes the statement write nothing. The unique indexes on `(run_id, source_event_id)` and `(run_id, source_instance_id, source_seq)` are a second guard: a unique violation from this statement also falls back. - A source without a cursor starts at 0. The probe still finds any stored event of that source, so a run that an older server wrote falls back and recounts. - `appendHeartbeatRunEventBatch` and `appendHeartbeatRunEvent` try the one statement first for native events without a wake, outside a caller's transaction. Every other case (a replay, a gap, an event with a wake, a cursor that lags, a run changed meanwhile, a binding mismatch, a run deleted meanwhile, a caller's transaction) takes the existing transaction, unchanged. - Inside a caller's transaction the append keeps its SAVEPOINT path. A failed statement there would abort the caller's transaction, and the fallback could not run. - `assertWritable` runs before the statement is sent and after it returns (see Risks). ## Verification - Red/green on embedded PostgreSQL. I ran the new tests against the previous `heartbeat-run-events.ts` and saw 9 of them fail; all 25 tests in the file pass with the change (`server/src/__tests__/heartbeat-run-event-atomic-append.test.ts`): - One statement for an in-order event and for a batch (before: 4 and 5). - A writer revoked before the send sends nothing; a statement that fails on its third row stores no row and no sequence; the resend commits. - A writer revoked while the statement runs: the rows stay, the receipt is rejected, and the resend is a replay with the same rows. - A batch waits for Stop on the run row and appends after it; a batch and a single event that wait for a run deletion fail with `heartbeat_run_event_binding_mismatch` and store nothing. - An older server stores events 2 and 3 while it holds the run row, without the cursor: the waiting batch 2–4 falls back, returns duplicate, duplicate, committed, and the cursor ends at 4. - Two connections append the same 200-event stream in batches of 10: each event is stored once, in source order, sequences 1–200 without a gap, one `committed` and one `duplicate` receipt per event. - A 7,000-event batch (more than any bind parameter limit at 10 parameters per row) is one statement. Before: it fell back to one statement per event and timed out at 15 s. - A run without a cursor starts at its first event; a run with events from an older server replays and then continues. - Equivalence: 12 random streams of 30 steps (in-order batches, gaps, replays of earlier ranges, fills of gaps, ordinary events, conflicting replays). Each step goes to two runs, one through the new path and one forced through the one-by-one locked path. Receipts, errors, rows, `next_event_seq` and cursors are equal at every step. - Mutation check: with the `next_event_seq` check and the unique-violation fallback removed, the older-server race test fails. - The port suite (`paperclip-control-plane-port.test.ts`, with the package conformance suite) passes: 125 tests. Two tests changed: the streamed-event test now expects one statement and the new revocation behavior, and the batch test checks that the five deltas are one statement sent before the boundary event. - Other focused suites pass, one file at a time: `heartbeat-run-event-sequencing` (5), `native-event-boundary-golden` (1), `native-observer-replay` (1), `paperclip-semantic-conformance` (1), `native-interaction-bridge` (7), `chat-native-progress-work` (19), `heartbeat-native-restart-suspension` (115), `live-recovery-work` (51). In 2 of 3 runs with this change, all 51 tests passed but the file's `afterAll` (closing the side pools and the embedded database) hit its 30 s timeout on this busy machine; the third run passed cleanly, and one run on `origin/master` passed. The native events in that file all register a wake, so they do not take the new path. - `pnpm --filter @paperclipai/server run typecheck` and `pnpm check:module-boundaries` pass. - Load model: `scripts/benchmark-agent-scaling-load.ts` as merged in #21418 (per-source counts stop when the window closes). I did not change its batching rules for this pull request. Model rates: 20 deltas/s, 1 other event/s, 0.3 API requests/s per agent; default pool of 10 connections; embedded PostgreSQL on the same, shared machine. I ran "before" (`origin/master`) and "after" one after the other, with a pause between runs, and I give the load average at the start of each run. The machine was busy with other work (load 10–15 on 18 cores), so compare rows that ran close together. No run had a failed operation, a failed checkpoint save or a lost lease. | Agents | Code | Window | Load avg | Event-loop utilization | Statements/s | Delta lateness p50 / p99 (ms) | Other events done / offered | Other event lateness p50 / p99 (ms) | | --- | --- | --- | --- | --- | --- | --- | --- | --- | | 200 | before | 60 s | 9.6 | 0.56 | 7,043 | 283 / 3,368 | 12,000 / 12,000 | 278 / 3,895 | | 400 | before | 60 s | 11.8 | 0.59 | 7,158 | 9,927 / 18,779 | 6,068 / 24,000 | 1,904 / 60,154 | | 400 | after | 60 s | 12.7 | 0.74 | 5,465 | 1,129 / 6,040 | 18,719 / 24,000 | 5,721 / 15,238 | | 600 | before | 60 s | 15.0 | 0.85 | 12,419 | 7,108 / 11,017 | 7,836 / 36,000 | 10,822 / 52,171 | | 600 | after | 60 s | 10.0 | 0.69 | 6,158 | 2,357 / 9,483 | 18,771 / 36,000 | 2,280 / 30,985 | | 600 | after, `DELTA_BATCH_MS=0` | 60 s | 10.8 | 0.68 | 8,014 | 36,135 / 52,222 | 36,000 / 36,000 | 698 / 3,422 | At 200 agents an earlier pair gave 0.61 → 0.43 event-loop utilization and 7,051 → 3,210 statements/s. One process with this change alone still does not carry 600 agents: at 400 and above the 10-connection pool and the shared database are the limit (event-loop utilization stays below 0.75 while other events fall behind). #21520 and a third pull request for the remaining statements of other events and checkpoint saves continue from here; their description has the stacked results. - Statements: a delta batch 5 → 1; one delta or one native event without a wake 4 → 1. Unchanged: an event with a wake (6) and a checkpoint save (5). ## Risks - **`assertWritable` window (read first).** Before, the writer check ran inside the transaction, before the first statement and before COMMIT. A revocation while the statements ran rolled the append back. Now a revocation while the one statement runs does not roll it back: the rows commit, and the caller gets the error instead of the receipt, so no observer runs and the runner gets no ack. This check guards a controller that hands its run to a successor at restart (`nativeRunsDetachingForRestart`). I think this is acceptable: (1) the earlier check was not atomic with COMMIT either, so a revocation during the COMMIT round trip already committed; the window grows from one COMMIT round trip to one statement round trip plus its wait for a pool connection; (2) the append is idempotent by source event id and payload hash, so the successor sees the committed row as a replay of the event that the runner resends; (3) the old controller never acts on the rejected receipt. A new test covers exactly this. - A crash loses nothing new: the statement commits or not as a whole, and a resend after an unknown outcome is a replay. - The check on `next_event_seq` makes the statement write nothing whenever any other event of the run committed after its snapshot. Under heavy contention on one run, more appends take the fallback. The fallback is the previous code path. - The statement text is fixed SQL sent through the driver (`$client.unsafe`), like the rest of the event stream statements. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, with tool use and code execution in Claude Code. ## 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>