# Automatic Agent transport chunking ## Status and scope **Offline only.** The user explicitly held deployment on 2026-11-09. Development, isolated tests, and ordinary source commits are authorized; live service updates and replacement of published installers for this feature are not. The shared `internal/agentwire` package splits a logical protobuf message into bounded packets and assembles it before the existing Agent handler sees it. Scripts, output, large inline commands, stdin, and reconciliation all use the same transport path. Business-level script/output chunks remain unchanged. This handles messages larger than a wire packet, not requests exceeding the configured logical limits. The normal 1 MiB envelope, 768 KiB execution spec, 64 KiB raw chunk and 10 MiB script limits, existing quotas, and Control API admission rules still apply. A request beyond its logical limit is rejected; fragmentation does not raise limits or make unbounded snapshots valid. ## Negotiation and compatibility Both WebSocket endpoints advertise `rvbox.agent.v1.chunked` using the standard `Sec-WebSocket-Protocol` handshake. Framing is enabled only if that exact subprotocol is selected. Otherwise the existing one-binary-message-per-envelope format remains in use. No client-version guessing, protobuf capability fields, database migration, or operator configuration knob is required. New client/old server and old client/new server retain the raw format. Old clients do not gain a reassembler from a server upgrade; their existing 32 KiB reader can still reject large inline commands, stdin, or reconciliation. The server's existing 16 KiB script chunks continue to support pending uploads to those clients. Proxy configurations must preserve the negotiated subprotocol header in both directions. ## Packet format Each negotiated packet is one binary WebSocket message of at most 16,384 bytes. The WebSocket library enforces that aggregate message bound even when a peer fragments it into native WebSocket continuation frames. Compression remains disabled at the WebSocket layer. | First byte | Remaining bytes | Meaning | | --- | --- | --- | | `0` | Serialized logical message | Complete message; payload is 1–16,383 bytes. | | `1` | uint32 total length, uint32 offset, data | Fragment of a data-lane message. | | `2` | uint32 total length, uint32 offset, data | Fragment of a control-lane message. | Integers use big-endian order. Fragment headers occupy nine bytes including the kind; data is nonempty and at most 16,375 bytes. Fragmented messages have total length at least 16,384 bytes. The declared length is checked against the local logical envelope ceiling before allocation. Offset starts at zero and must equal the assembled prefix length; total length must stay constant. Gaps, overlaps, duplicate prefixes, changed totals, unknown kinds, empty packets, overflowing ranges, and oversized messages are fatal framing errors. There is no recursive interpretation of an assembled payload as another transport packet. The final fragment is identified by offset plus data length equalling total length. The next logical message starts again at offset zero. Ordered WebSocket delivery and one in-flight message per lane remove the need for fragment UUIDs, extra event sequences, final flags, or transport acknowledgements. Existing payload/request hashes remain validated after assembly; no additional transport checksum or durable fragment ledger is introduced. ## Ordering, liveness, and bounds One connection-scoped decoder owns two bounded partial buffers, one per lane. Complete small messages can overtake either partial message. A large control message can complete while a data message is paused. The server's sole writer keeps lane order, checks heartbeat state between packets, and drains a bounded control burst between data packets so data also progresses. Write deadlines apply to each packet; a slow complete logical message can take longer than one packet deadline while continuing to make progress. Parent operation deadlines still apply. `Written` and `OnWritten` remain whole-message barriers. A partially transmitted dispatch cannot release dependent stdin or signals, and a partial reconciliation result cannot enable new work. The decoder delivers no partial envelope to protobuf validation, storage, execution, or acknowledgement handlers. One read pump per connection handles control frames even when the application is sending a large message. It has one complete-message delivery slot. Partial buffers are individually limited by the logical ceiling; the queued/in-flight complete messages are also bounded. Valid packet traffic updates server liveness before assembly finishes. Socket close cancels the pump, including a blocked delivery. There is no goroutine, queue, or persistence record per packet. Client concurrent logical writes are serialized. The server uses its existing single writer, with bounded control preemption and separate fragment lanes. On disconnect, partial buffers are discarded with the connection. A new connection cannot finish an old tail. Existing durable commands/events/stdin and reconciliation supply replay; IDs, event digests, sequences, newline behavior, and idempotency are unchanged. ## Offline verification Run `scripts/build verify` in the established Docker toolchain. Focused checks: ```sh docker compose -f deploy/compose.yaml run --rm toolchain \ go test -race ./internal/agentwire ./internal/client/agent \ ./internal/server/session ./test/integration/clientagent ``` The tests cover exact packet/logical boundaries, malformed declarations and ordering, bounded allocation, two-lane preemption, whole-message write barriers, heartbeat/Pong progress, concurrent writes, partial-disconnect replay, TLS, old/new fallback in both directions, large output/dispatch/reconciliation, and large stdin preserving one write sequence/newline/idempotency result. Fuzz seeds exercise the decoder during normal tests; run a longer fuzz campaign in the same isolated toolchain when needed. None of these commands deploys the feature or contacts the live workstation.