Files
PaperClipAI/packages
Nicky Leach 323504e41e perf(runner): enable TCP_NODELAY for loopback PRP (#22091)
## Thinking Path

> - Paperclip manages AI agents for work.
> - Native Runner exchanges commands and events over WebSocket PRP.
> - Both Runner connection modes use TCP sockets.
> - Several small frames can follow each other during a start.
> - Loopback peers can receive those frames promptly with TCP_NODELAY.

## Linked Issues or Issue Description

**What existing behavior does this improve?**

Delivery of PRP command results and events on local TCP connections.

**Subsystem affected**

Native Runner PRP transport.

**Current behavior**

Runner uses the default TCP setting for acknowledged small writes on its
accepted and outbound PRP sockets. In an A/B test with a loopback model
fixture, enabling TCP_NODELAY on the accepted Runner socket reduced
median time to observe turn.started by 29 to 52 ms, depending on the
provider and session state.

**Proposed behavior**

Enable TCP_NODELAY on accepted and outbound PRP sockets before the
WebSocket handshake when the connected peer address is loopback.

**Reason and benefit**

The controller receives turn-start events sooner. The outbound path
shares the same setup rule and has socket-option coverage.

**Breaking changes**

The change is a per-connection socket option. Existing launch arguments,
durable checkpoints, and PRP frames carry forward.

## What Changed

- Share initial stream configuration between the listener and dialer.
- Check the actual peer address before enabling TCP_NODELAY.
- Complete a real WebSocket handshake in one test for each connection
mode and read back the option.

## Verification

- `cargo fmt --manifest-path packages/paperclip-runner/runner/Cargo.toml
--all --check`
- `cargo test --offline --locked -p paperclip-runner-core --lib
durable::transport::tests` passed locally on macOS (27 passed).
- Both new tests failed on the original socket setup and passed with the
change.
- `cargo test --offline --locked -p paperclip-runner-core --lib --bins
--test listener_accept` passed locally on macOS (676 passed, 4 ignored).

## Risks

- TCP can send more small packets during high-volume local output. The
check limits the option to loopback peers. The earlier A/B measured
turn-start timing on the listener path.

## Model Used

- OpenAI GPT-6 (Codex), with source inspection and local Rust tests.

## 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
2026-11-17 23:14:48 +00:00
..