Two-way relay over the uplink #1016

Part of #1013.

Scope

A gateway module can hold a byte channel to a worker module open in both directions for as long as it needs, instead of one request then one response. Nothing user-facing uses it yet; #1017's input socket is its first caller. Through the relay's own test target, a caller sees bytes flow both ways, a silent worker cut off after 15 s, and an uplink drop end every such relay on both sides.

In short

Today a relay carries one HTTP exchange: once the worker's module answers, the rest of what the gateway sends is dropped (F3). A two-way relay keeps both directions open. Ending one direction ends only that direction: a worker that has finished sending can still read what the gateway writes. The relay ends when both directions have ended, or when either side aborts. Bytes are carried as they are; the relay never parses them. While the worker's direction is open, a two-way relay ends with WORKER_UNREACHABLE when 15 s pass with no byte from the worker, counted from the head or from the last byte the relay read off the channel from the worker. The relay reads the worker's direction itself into the module's readable, so a module that reads slowly does not make a live worker look silent. It reads ahead at most 64 KiB; past that it stops reading until the module catches up, and the link holds the rest.

sequenceDiagram
  participant M as Gateway module
  participant R as Gateway relay
  participant WR as Worker relay
  participant T as Worker module two-way target (NEW)
  M->>R: relayTwoWay(worker, request, tenant, leaseId) NEW
  R->>WR: relay.request {twoWay: true} on a channel CHANGED
  WR->>T: request
  T-->>WR: head 200, then pipe
  WR-->>R: relay-head 200
  R-->>M: {readable, writable}
  M->>T: bytes (gateway → worker)
  T-->>M: bytes (worker → gateway), at least every 15 s
  Note over R: worker direction open and 15 s with no byte from it → WORKER_UNREACHABLE
  T-->>R: END (worker direction done; the gateway may still write)
  M->>R: END → both ended, relay done

If this goes wrong, a user of #1017's input socket would notice it cut while they only watch, or a socket that never ends after the worker went away.

Technical spec

Facts

Commit e1f2f43.

Modules touched

Searches: relay.request, relayRequest, RelayTarget, ModuleRelayTarget, relayTargets, GatewayRelay, GatewayRelayCall, DEFAULT_IDLE_MS, hasBody across src/.

• src/contract/operations.ts: relay.request gains twoWay: true (optional); src/contract/protocol.ts: the bump.
• src/daemon/relay.ts: a two-way run: no body cut-off, the target gets both directions.
• src/daemon/main.ts, src/modules/types.ts, src/modules/host.ts: WorkerModule.relayTwoWay targets collected by module name beside relayTarget; GatewayContext.relayTwoWay.
• src/gateway/relay.ts: GatewayRelay.relayTwoWay, with the 15 s silence bound.
• src/gateway/AGENTS.md, src/daemon/AGENTS.md, docs/internal/flows/ if a flow names the relay.

flowchart LR
  gm[gateway module] --> host[modules host CHANGED]
  host --> grelay[gateway relay CHANGED]
  grelay --> link[link channels]
  grelay -->|relay.request CHANGED| contract[contract CHANGED]
  wrelay[worker relay CHANGED] --> contract
  wrelay --> wt[worker module two-way target NEW]
  link --> wrelay

Surface and extension points

• GatewayContext.relayTwoWay(workerId, request, tenant, leaseId?) → Promise<Response | TwoWayRelay>. A refusal (non-2xx head) is a Response with its body, as today. A 2xx head gives TwoWayRelay: { status, headers, readable, writable }, where readable carries bytes from the worker and writable bytes to it; cancelling readable or aborting writable aborts the relay.
• WorkerModule.relayTwoWay?: (request, tenant, leaseId, pipe) → Promise<Response>. The target answers a refusal Response before touching pipe, or a 2xx Response with no body and then uses pipe = { readable, writable, signal } until it ends. One per module, keyed by the module's name, like relayTarget (F5).

Contract and event changes

relay.request gains twoWay: z.literal(true).optional(). With twoWay, method must be GET and hasBody false, else BAD_REQUEST, by a second refine beside F16's; the head is still relay-head (F2); the answer comes once both directions have ended, or { cancelled: true }. A worker with no two-way target of that name answers RELAY_TARGET_MISSING (F6). This PR bumps the protocol by one. No event changes.

Other code on the same state

Searches: openChannel( (2 hits: gateway/relay.ts, simlock-client), relays.abortAll (1 hit: daemon/server.ts), relay.cancel (3 hits: contract, gateway relay, worker dispatcher).

• Today's one-way relays (agent-device, stream) share the 64 channels per link (F13) with two-way relays. A two-way relay holds its channel for its whole life; the 65th open waits on its caller's signal, as today.
• relay.cancel and abortAll (F10) end a two-way relay as they end a one-way one.
• Input socket for a lease #1017 is the only caller; it writes and reads the bytes (Shared values: Channel framing on Let a lease holder watch and interact with its device's screen #1013).

Failure modes

State written: none persisted. A restart of either daemon closes the uplink: the uplink row above.

Rules in play

• Architecture rule 11, "Every wait that crosses a process boundary is bounded": the head keeps its 330 s deadline (Input socket for a lease #1017 bounds its own open tighter with a signal); after it, 15 s of silence from the worker ends the relay while the worker's direction is open, never reset by bytes from the gateway.
• Architecture rule 10, "A rule is enforced in exactly one place": only src/gateway/relay.ts bounds silence; modules do not time the channel.
• src/contract/AGENTS.md, "Every change to a contract shape bumps it by one in the same PR": the bump above.
• ADR 0028 (byte channels) is extended by ADR 0049 §5: the link is unchanged; only the relay keeps both directions open.

Tests

Seam: src/daemon/relay-gateway.e2e.test.ts (a real gateway and worker, a fake relay target) for the carrying, refusal and uplink rows; the silence row on src/gateway/relay.test.ts, with a FakeClock passed through GatewayRelayOptions.clock (F18), since that file uses real timers today; the BAD_REQUEST case on src/contract/operations.test.ts.

• A gateway module's two-way relay carries bytes both ways at once until either side ends: both directions together; worker ends its direction and the gateway still writes; gateway ends; both ended, relay done (the worker's answer comes only once both directions have ended, and a caller abort after that sends no relay.cancel); gateway module aborts, the worker target's signal aborts; the worker target aborts its writable, the gateway's readable errors (decided in delivery, pending the maintainer: the worker-side rows may run on src/daemon/relay.test.ts, the cancel row on src/gateway/relay.test.ts).
• A gateway module opening a two-way relay gets the worker's refusal or an error: non-2xx head as a Response; no two-way target RELAY_TARGET_MISSING; twoWay with POST or a body BAD_REQUEST.
• A two-way relay with no bytes from the worker for 15 s ends with WORKER_UNREACHABLE; bytes every 5 s keep it open: silent 15 s while the gateway writes; a byte every 5 s for 60 s; worker's direction ended, no limit.
• An uplink that drops ends every two-way relay on both sides: gateway side gets WORKER_UNREACHABLE; worker target's signal aborts.

The existing one-way tests in both files stay unchanged and prove one-way relays keep their 330 s bounds and body cut-off.

Done when

• pnpm test passes with the four tests above and the existing relay tests unchanged.
• PROTOCOL_VERSION_RANGE moves by one, and node .agents/scripts/protocol-bump-check.mjs passes.
• src/gateway/AGENTS.md (its timer table) and src/daemon/AGENTS.md (section "Uplink and relays (worker side)") describe the two-way relay and its 15 s bound.

Out of scope

• What travels on the channel: framing, heartbeat, close reasons (Input socket for a lease #1017).
• Any HTTP route or WebSocket (Input socket for a lease #1017).

Depends on

Written by an agent.