Crate wcode_protocol 

Wire transport for wcode sessions — the socket behind the protocol.

The kernel defines the interface (wcode_harness::protocol::Frame of Request/AgentEvent) and the in-process actor that speaks it. This crate adds the transport:

• NDJSON framing (read_frame/write_frame),
• a serve function that re-exposes a session SessionHandle to remote clients over a Unix socket,
• a Client that mirrors the handle’s send/ask/subscribe API,
• a Backend that makes the local and remote paths interchangeable,
• a Registry — the in-process A2A bus (§8 #3, §10.1): an address book plus the permitted-set routing that scopes who may message whom.

The point (design: docs/interface-protocol-brainstorm.md, §8): a caller — the REPL today, the TUI next, another session later — talks to a Backend and never knows whether the session is in this process or across a socket.

Structs

Client

A connection to a remote session, reconnecting automatically if it drops.

Closed

The session is gone — locally (the actor shut down) or remotely (the connection dropped).

DefineArgs

The arguments of a wcode_harness::protocol::Request::Define, passed to a DefineHandler. Mirrors the CLI’s worker spec.

Registry

An in-process address book and router over session mailboxes.

Enums

AskError

Why a bounded Backend::ask_within did not get a reply. ask keeps returning the narrower Closed, so its existing call sites don’t churn.

Backend

A handle to a session, local or remote.

RouteError

Why a message could not be routed (§10.1 enforcement).

Constants

FLUSH_TIMEOUT

Default bound for Client::flush and flush_all: long enough to drain a healthy socket, short enough that an unreachable or reconnecting peer never stalls a one-shot exit.

Functions

bind

Bind path, creating its parent directory and clearing a stale socket.

connect

Connect to a server listening at path.

flush_all

Best-effort flush of every live connection this process holds, so queued fire-and-forget frames are written before a one-shot exit drops the runtime. Each connection is bounded by timeout and they run concurrently, so the call returns within ~timeout even if some peers are unreachable. The hot path (Client::send/Client::send_from) stays fire-and-forget.

read_frame

Read one frame. Returns Ok(None) on a clean EOF. Blank lines are skipped, so a frame boundary never depends on a caller flushing an empty line.

serve

Bind path and serve the root session plus roster until the listener errors.

serve_at

Bind path, then serve.

serve_stdio

Serve the frame loop over the process’s own stdin/stdout — the --stdio transport (docs/vscode-extension-plan.md §3.1). Exactly one client: there is no listener, so no second connection is even expressible. Returns Ok(()) when the client’s stdin reaches EOF (clean shutdown; the spawning client owns the process lifetime).

serve_stream

Drive one connection over any byte stream: the frame loop (read → demux → actor), the per-session [fan] tasks, the live roster push, and the request replies. Transport-free — the caller supplies the bytes. Returns when the peer’s stream reaches a clean EOF (read_frame → Ok(None)) or the reader/writer errors.

write_frame

Write one frame as a single line and flush.

Type Aliases

DefineHandler

Builds a worker from DefineArgs and returns its address. A socket server uses it to answer wcode_harness::protocol::Request::Define; the composition root injects one, since this crate cannot name a session factory.

Root

A served session: the id every outbound frame carrying it is stamped with, and the handle the server reads events from / writes requests to.

Roster

The live roster of extra sessions served beside the root — a session is (SessionId, SessionHandle). Empty means “root only”; the value is refreshed by a crate::Registry as sessions are registered.