[Enrique Saurez (esaurez)]

The runtime adapter's guest agent serves the control session between the host and the guest with the adapter's own framing (#640), but its host program had no end of that session. This PR adds the host program's client, runtime_adapter::host::Client, through public APIs only, with tests of the host's part of the session with independent framing. The hypervisor scenarios that launch, reattach and stop a VM with it come in a follow-up pull request.

Part of #620
Refs #535

What changed

• runtime_adapter::host (feature host): Client attaches through nvx::host::nvxs::HostConnection::attach over any nvx::host::platform::Transport, with the launch capability, and exchanges the adapter's messages (Ping and Pong, Echo, Stop and Stopped) as the session's application data, mirroring the guest agent.
  • attach waits while the broker waits for the guest, and reports the identity of the session's epoch.
  • send sends a message in as many records as it takes. receive returns the guest agent's next message, whether it spans records or shares one with the next message.
  • ping, echo and stop send a request and check its answer: Pong, an Echo of the same bytes, and Stopped.
  • Besides the session's own buffers, the client holds at most the rest of one record and one partial message, whose header the framing's decoder checks before it takes any byte of the body.
  • A reset of the session ends the attachment, and its partial message with it: the next epoch starts with a new message, in a new attachment.
  • A failure of the session, a send that fails or times out, which the session cannot resume, a malformed message, or a message that only the host sends ends the client, and later calls fail with Ended. A receive that times out keeps what arrived. A request ends the client on any failure after the framing accepted it, a timeout included, because an answer that arrived later would answer the wrong request.
• tests/host_session.rs, in the host-only configuration: a test broker plays the broker's host-facing end of the session, and the guest agent behind it, with the public record API of nvx::protocol::nvxs, over an in-memory Transport, so the tests run on Linux and Windows. They cover:
  • the attachment: its bootstrap record with the capability, waits for the guest, a deadline that passes meanwhile, and refusals with an ERROR or by the end of the stream;
  • messages that span records both ways, up to the longest, which spans five records; records that end a message and start the next; and records whose bytes arrive in pieces down to one byte;
  • a receive that times out inside a message and then returns it whole, and a send that times out after it wrote part of a record or whose transport fails, which ends the client with the message that it held;
  • resets and disconnects in the middle of a message, with the next epoch and with a new instance, and a stream that ends inside a record;
  • the records that the client refuses: sequence, epoch and instance errors, stale and identity-less resets, record lengths, bootstrap identity, ERROR payloads, and header faults;
  • bounded buffers: a record or a message whose header declares more than the limit fails at its header, before its payload or body arrives;
  • messages that only the host sends, a message beyond the framing's limit, which the client refuses to send, and the answers that requests check, including one that arrives too late.
• Docs: the adapter's README, with a section on the host program, and its entries in doc/ci.md and doc/project-structure.md.

The adapter adds no dependency, and its binaries don't change.

Validation

At e1c767d, on dev at 916a61f. In tests/runtime-adapter, the commands of the three "Check the runtime adapter's ..." steps of check-nvx-rs:

• Linux (WSL Ubuntu, x86-64, as an unprivileged user): protocol-only, host-only, and guest-only for x86_64-unknown-linux-musl, each with cargo fmt --all --check, Clippy with -D warnings, cargo build, cargo test, and cargo +1.89 check --all-targets. All pass; tests/host_session.rs runs 9 tests.
• Windows 11: protocol-only and host-only, with the same commands. All pass; tests/host_session.rs runs 9 tests.

Also on Windows 11: cargo doc --no-deps --features host with RUSTDOCFLAGS=-D warnings in the adapter, python scripts/check_markdown_links.py, and python scripts/nvx.py verify.

The adapter declares no ignored test yet, so the microVM jobs, which a change to the adapter runs, only build its host-only configuration on each backend. I ran no hypervisor for this change.

[Copilot]

🟡 Changes recommended

Terminal send timeouts can leave the client returning buffered messages after its underlying connection has ended.

1 open issue

• Send write timeouts fail to terminate HostConnection · New

What changed in this PR

Adds the runtime adapter’s host-side client for independent framing over NVXS, complementing its guest agent. Hypervisor lifecycle scenarios remain follow-up work.

Changes:

• Adds attachment, message exchange, and request/reply APIs.
• Adds cross-platform tests for framing, session failures, and timeouts.
• Documents the host client and test coverage.

File	Description
tests/​runtime-adapter/​tests/​host_session.rs	Tests host sessions using an in-memory broker.
tests/​runtime-adapter/​src/​lib.rs	Exposes the host module behind its feature.
tests/​runtime-adapter/​src/​host.rs	Implements the host client and error handling.
tests/​runtime-adapter/​README.md	Documents client behavior and tests.
doc/​project-structure.md	Describes both adapter session endpoints.
doc/​ci.md	Documents host-side session coverage.

_{Review effort: Balanced}

[Copilot]

🟢 Approval recommended

No blocking issues remain, and the earlier send-timeout issue is fixed with targeted regression coverage.

No open issues 🎉

1 resolved since last review

• Send write timeouts fail to terminate HostConnection

_{Review effort: Balanced}

[Copilot]

🟢 Approval recommended

No blocking issues remain, and targeted regression coverage addresses the previously reported send-timeout failure.

No open issues 🎉

_{Review effort: Balanced}