Files
PaperClipAI/server
DottaandClaude Opus 5.5 a82fa96540 perf(run-events): collect deltas that arrive while a batch commits into one next batch (#21520)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The control plane port commits streamed text deltas of a run in
batches (#21460): the first text at once, later deltas after at most 250
ms
> - Each batch is cut when its timer fires, even when the previous batch
of the same run has not committed yet
> - When the database is slow, every run then queues one small batch per
250 ms behind its slow commit. The number of statements stays the same
exactly when the database has the least room for them, and the queue
grows
> - This pull request cuts a batch only when the previous batch of the
run has committed. Deltas that arrive while a batch commits all join the
next batch
> - The benefit is fewer, larger statements under load, with no change
when the database keeps up, and no longer wait for any delta

## Linked Issues or Issue Description

Refs #21460 (batched deltas). Refs #21511 (one statement per delta
batch). Refs #21418 (agent scaling plan and load model).

**What existing behavior does this improve?**
How `PaperclipControlPlanePort` groups queued text deltas into batches
when a batch commit is slower than the batch time.

**Subsystem affected**
Server run event ingest:
`server/src/services/native-runtime/paperclip-control-plane-port.ts`.

**Current behavior**
`#flushStreamingEvents` takes the queued deltas when it runs (on the 250
ms timer, at 100 deltas, or before any other event) and chains their
commit behind the previous batch. If one commit takes two seconds, the
run queues about eight batches, each one statement, behind it.

**Proposed behavior**
`#flushStreamingEvents` chains one cut behind the previous batch and
takes the queued deltas when that cut runs. While a cut waits, later
flush requests join it. A run has at most one batch committing and one
cut waiting.

**Reason and benefit**
Under load, the number of delta statements per run falls to about one
per commit time instead of one per 250 ms. When commits are faster than
250 ms, nothing changes.

**Breaking changes**
None. Rows, receipts, order and the first-text rule are the same.

## What Changed

- `#flushStreamingEvents` queues one cut on the run's commit chain
(`#streamingFlushQueued`). The cut takes every delta queued at that
time, sets the first-text flag, commits the batch, and then releases the
pending count of that batch.
- A flush while a cut waits returns the same chain, so a caller that
waits for it (every other event, `checkpointSession`, `completeRun`,
`replayEvents`, `provesNoRunProviderWork`) still waits for every delta
queued before it.
- A batch can now hold more than 100 deltas when commits are slow. The
100-delta rule still asks for a flush; the batch is one statement with a
fixed number of bind parameters (#21460, #21511).

## Verification

- Red/green: new port test "collects the deltas that arrive while a
batch commits into one next batch, before the next other event"
(`paperclip-control-plane-port.test.ts`). A transaction holds the run
row, so the first batch waits. Six more deltas arrive 15 ms apart with a
5 ms batch time, then a non-streaming event. Before: 8 inserts (one per
timer). After: 3 inserts (the waiting batch, one batch of six, the other
event). Rows are stored 1–9 in order and every receipt resolves.
- The whole port suite with its conformance suite passes: 101 tests.
Other suites, one file at a time: `native-observer-replay` (1),
`paperclip-semantic-conformance` (1), `native-interaction-bridge` (7),
`chat-native-progress-work` (35). I ran the four streaming port tests
two more times; they pass each time.
- `pnpm --filter @paperclipai/server run typecheck` passes. `pnpm
check:module-boundaries` passes.
- Load model (`scripts/benchmark-agent-scaling-load.ts` as merged in
#21418). The model applies the port's batching rules itself, so for
these runs I changed my local copy only (not in this pull request): with
`DELTA_COALESCE=1`, `flushDeltas` queues one cut on the agent's append
chain and takes the queued deltas when the cut runs, as the port now
does. All rows run with #21511. Default pool of 10 connections; embedded
PostgreSQL on the same, shared machine; runs one after the other with a
pause between them. No run had a failed operation, a failed checkpoint
save or a lost lease.

| Agents | Batching | Window | Load avg | Event-loop utilization |
Statements/s | Delta lateness p50 / p99 (ms) | Other events done /
offered | Other event lateness p50 / p99 (ms) |
  | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| 200 | this change | 60 s | 9.7 | 0.51 | 3,832 | 151 / 3,087 | 12,000 /
12,000 | 3 / 3,994 |
| 400 | cut on timer (before) | 60 s | 12.7 | 0.74 | 5,465 | 1,129 /
6,040 | 18,719 / 24,000 | 5,721 / 15,238 |
| 400 | this change | 60 s | 12.5 | 0.78 | 7,010 | 892 / 3,131 | 23,993
/ 24,000 | 1,896 / 4,193 |
| 600 | cut on timer (before) | 60 s | 10.0 | 0.69 | 6,158 | 2,357 /
9,483 | 18,771 / 36,000 | 2,280 / 30,985 |
| 600 | this change | 120 s | 11.4 | 0.72 | 6,730 | 1,147 / 6,335 |
61,158 / 72,000 | 11,678 / 21,212 |
| 600 | this change (repeat) | 120 s | 13.6 | 0.74 | 6,498 | 1,225 /
6,057 | 58,984 / 72,000 | 11,465 / 25,361 |
| 800 | this change | 60 s | 11.5 | 0.80 | 6,228 | 2,054 / 7,186 |
24,877 / 48,000 | 24,544 / 31,331 |

The process does more work per second with this change (more other
events finish), so statements per second rise; delta lateness falls. 600
agents are still not carried reliably: other events fall behind. #21528
removes two statements from each such event and one from each checkpoint
save; its description has the stacked results.

## Risks

- A delta never waits longer than before: it already waited for the
previous batch of its run. When the database keeps up, batches are the
same as before.
- Under load, one batch can be large. The live view then gets one larger
step instead of several small steps behind the same wait.
- A failed batch now rejects more deltas at once (every delta that
joined it). The runner resends them, as before; each resend is
idempotent.

## 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>
2026-11-13 19:00:08 -06:00
..