Input socket for a lease #1017

Part of #1013.

Scope

After this PR, a client with an agent token opens WS /v1/leases/{id}/input on a gateway or a standalone worker. It gets 0x83, then 0x82, and its serve-sim messages reach the worker that holds the lease. No device takes input yet: every device reports "inputUnavailable":true until #1018 and #1019 add the Android and iOS device inputs. The socket ends when the lease ends, when either end goes quiet, and when the daemon stops.

This task adds the new optional module input, the upgrade routing in ports, the lease socket seam and the device input port. It is the feature's widest task (five Behaviours rows, about 18 modules); it does not split further, because the socket, its gateway relay and its lifecycle are one path a test drives end to end.

In short

A lease holder's app opens one WebSocket for its lease and gets 0x83 (input admitted), then 0x82 {"width":1179,"height":2556,"orientation":"portrait","inputUnavailable":true}. Through a gateway, the socket rides #1016's two-way relay to the lease's worker. It closes with 4001 and the lease-end reason (explicit, killed, expired, device-lost) when the lease ends.

New term: device input, what turns messages into taps on one device. One per lease, shared by up to 8 sockets (Shared values, "Device input port"). This task adds the port and a placeholder that answers inputUnavailable on every platform.

flowchart LR
  App[App] -- WS upgrade --> P[ports upgrade router NEW]
  P --> H[http: lease resolve for the caller]
  H --> GI[input module, gateway side NEW]
  GI -- two-way relay #1016 --> WI[input module, worker side NEW]
  H --> WI
  WI -- WorkerContext.inputs NEW --> D[device input: none yet → inputUnavailable]

Messages a client sees, word for word: the refusal for a 9th socket is close 1013 with reason Input is unavailable for this lease; lease end is close 4001 with the reason text explicit, killed, expired or device-lost; worker unreachable is close 1011 Worker <workerId> stopped answering; daemon stop is close 1001 Simlock is stopping.

Input turned off on the lease's worker behind a gateway, before the upgrade:

$ websocat -H "Authorization: Bearer $AGENT_TOKEN" wss://gw:7480/v1/leases/L-42/input
websocat: WebSocketError: Received unexpected status code (503 Service Unavailable)
# body: {"error":{"code":"INPUT_UNAVAILABLE","message":"Worker w1 does not take input for lease L-42; turn on capabilities.input.enabled there"}}

If this goes wrong, a user sees T3 Code's device panel say "input socket refused" or never mark input as connected.

Technical spec

Facts

Commit e1f2f43.

Modules touched

Searches: upgrade, WebSocketServer, onServerCreated, ModuleMount, relayTarget, ModuleScreens, screens:, beforeDeviceReclaim, optionalModules, capabilities.stream over src/, website/, ui/src.

• src/input/ (new): definition.ts, index.ts, worker.ts, gateway.ts, the session (messages, sharing, heartbeat, lease end) and its manual AGENTS.md.
• src/core/input.ts (new), src/core/index.ts: message tags and JSON shapes from the feature's Shared values "Input messages".
• src/ports/: an upgrade router beside the uplink (uplink-websocket.ts and a new file), its index.ts and AGENTS.md.
• src/modules/types.ts, src/modules/host.ts: the lease socket handler on WorkerModule and GatewayModule, WorkerContext.inputs.
• src/http/: the lease socket resolution next to A lease holder streams its lease's screen #1015's lease route.
• src/daemon/main.ts: router on both listeners, inputs from DriverCatalog.
• src/drivers/ catalog: an openInput that answers "unavailable" for every platform.
• src/module-registry/index.ts: add inputModule.
• website/src/content/docs/docs/using-devices/watching-the-screen.mdx, .../reference/configuration.mdx, .../gateway/access-control.mdx.

flowchart LR
  daemon[daemon/main.ts *] --> ports[ports upgrade router *]
  daemon --> host[modules/host.ts *]
  ports --> http[http lease resolution *]
  http --> input[input module NEW]
  host --> input
  input --> core[core/input.ts NEW]
  input -- GatewayContext.relayTwoWay --> gw[gateway relay #1016]
  input -- WorkerContext.inputs --> drivers[driver catalog *]

sequenceDiagram
  participant App
  participant GW as Gateway (ports, http, input)
  participant W as Worker (input)
  App->>GW: GET /v1/leases/L-42/input, Upgrade: websocket
  GW->>GW: authenticate, resolve L-42 for the caller
  alt not theirs or unknown
    GW-->>App: 404 UNKNOWN_LEASE, socket destroyed
  else
    GW->>W: two-way relay, target input, lease L-42
    alt input off on the worker
      W-->>GW: RELAY_TARGET_MISSING
      GW-->>App: 503 INPUT_UNAVAILABLE, socket destroyed
    else
      GW-->>App: 101 Switching Protocols
      W-->>App: 0x83, 0x82
      App->>W: 0x03 touch
      W-->>GW: 0xF0 every 5 s (dropped)
      Note over GW,W: 15 s with no bytes from W
      GW-->>App: close 1011
    end
  end

Surface and extension points

• src/input/index.ts exports inputModule, an OptionalModuleDefinition (F15, F23). Its worker factory returns a WorkerModule with capability, a lease socket handler, relayTwoWay (the worker end of Two-way relay over the uplink #1016's two-way relay, see the feature's Two-way relay row), and hooks.beforeDeviceReclaim and hooks.beforeDrain. Its gateway factory returns a lease socket handler and hooks.beforeDrain.
• Lease socket seam: WorkerModule.socket and GatewayModule.socket, a handler (socket, identity, lease), written to the feature's Shared values "Lease socket". The socket type is a small port interface (send, close(code, reason), onMessage, onClose), so no module imports ws (F3).
• ports gains one upgrade router per HTTP server: /v1/uplink goes to the uplink as today; /v1/leases/{id}/<segment> goes to http's lease resolution; anything else gets 404 and is destroyed (F1). A worker's HttpGateway gets the router through onServerCreated too (F2).
• WorkerContext.inputs: ModuleInputs, modeled on ModuleScreens (F9): openInput(platform, device, signal) → a device input (send(message), onConfig(listener), close()). This task's driver side answers "unavailable" for every platform; Android input through scrcpy's control channel #1018 and iOS simulator input through the HID injector #1019 are the two implementations, so the port is added now (architecture rule 19: "when a second implementation exists or is being built").

Contract and event changes

none. Searched src/contract/ for relay, capability and error shapes: #1016 makes the relay change and bumps the protocol; INPUT_UNAVAILABLE is a module error code declared in src/input/definition.ts (F14); the capability input uses the existing {name, state, reason?} shape. No event is added; opening and refusing sockets is logged only.

New wire fields, all from the client: each WebSocket message is one tag byte and UTF-8 JSON (feature Shared values "Input messages"); a message over 64 KiB, bad JSON, an unknown tag, or a position outside 0..1 is dropped and the socket stays open (F17's server does the same). Config capabilities.input.enabled: boolean, default false.

Other code on the same state

Searches: on("upgrade" (1 hit, F1), handleUpgrade (1), beforeDeviceReclaim (2: stream, agent-device none), beforeDrain (module host, 2 daemons), leases.onRemoved (1: agent-device relay-host-link).

• The uplink's upgrade handling (F1): now behind the router; an uplink upgrade must behave byte for byte as today. src/ports/uplink-websocket.test.ts already proves it and must stay green unchanged.
• The stream module's beforeDeviceReclaim (F10): both modules hear the same lease end; neither waits for the other, and each closes only its own sockets.
• A lease holder streams its lease's screen #1015's lease route (feature Shared values "Lease route"): this task reuses its lease resolution for upgrades; a plain GET to /v1/leases/{id}/input with no upgrade answers 426.
• HttpGateway.stop (F12): the input module closes its sockets with 1001 in beforeDrain, which runs first, so no socket is destroyed without a close frame.

Failure modes

State: the device input per lease and its socket set, in memory only. A worker restart drops them; through a gateway the uplink closes, so its sockets close 1011; standalone, the TCP connection closes. Two sockets opening at once for one lease share one device input: the first open runs, the second waits for it.

Rules in play

• Architecture rule 11, "Every wait that crosses a process boundary is bounded": the relay open (30 s), the worker silence (15 s) and the client pong (15 s) are each counted from a fixed point.
• Architecture rule 10, "A rule is enforced in exactly one place": lease ownership is checked only by http's lease resolution; the module trusts the lease it is handed.
• Architecture rule 15, "Dependencies point from the optional to the required": input imports modules, core and contract; nothing required imports input.
• Architecture rule 18, "A module hands out a capability, not its parts": index.ts exports only inputModule.
• Architecture rule 19, "An extension point is added when a second implementation is named": ModuleInputs has Android input through scrcpy's control channel #1018 and iOS simulator input through the HID injector #1019 as its implementations.
• src/ports/AGENTS.md:53, "Only uplink-websocket.ts imports ws": the router lives beside it in ports and owns the only other ws import; the rule's wording changes to name both files.
• Documentation rule 9, "A change to the public surface updates the website in the same change": the route, capabilities.input.enabled and INPUT_UNAVAILABLE go on the three pages under Modules touched.
• ADR 0049 §1–§6: lease routes, the module lease route, expo serve-sim messages, the shared device input, the two-way relay's heartbeat and lease end.

Tests

Seam: the gateway and standalone worker HTTP listeners with a faked device input, in a new src/daemon/input-lease.e2e.test.ts modeled on src/daemon/stream-gateway.e2e.test.ts; the session's message handling in src/input/ modeled on src/stream/worker-link.test.ts.

• A caller opens WS /v1/leases/{id}/input and gets 0x83 then 0x82, or a refused upgrade: own lease; another's 404; unknown 404; operator; input off on the answering daemon 404; off on the lease's worker 503 INPUT_UNAVAILABLE; no token 401; a 9th socket closed 1013; a platform with no device input gets "inputUnavailable":true.
• A client following T3 Code's order drives a faked device through a gateway: waits for 0x83; touch begin/move/end, key, button arrive in order.
• A client sending a bad message keeps its socket and nothing reaches the device: bad JSON; unknown tag; x outside 0..1; 0x10 answered 0x90 {ok:false}.
• An input socket closes with 4001 and the reason when the lease ends, and a reconnect gets 404: explicit, expired, killed, device-lost.
• An input socket closes when either end goes quiet or away: client misses its pong (worker and gateway); worker heartbeat stops (1011); uplink drops (1011); daemon stops (1001); the gateway sees the lease go (4001).

The uplink's upgrade, unchanged, stays proven by src/ports/uplink-websocket.test.ts.

Done when

• pnpm test passes, including src/daemon/input-lease.e2e.test.ts and src/ports/uplink-websocket.test.ts unchanged.
• With capabilities.input.enabled true on a standalone worker, an agent token's upgrade to its own lease's /v1/leases/{id}/input gets 0x83 then 0x82 with "inputUnavailable":true; another token gets 404.
• pnpm openapi lists GET /v1/leases/{id}/input with 101, 401, 404, 426 and 503 INPUT_UNAVAILABLE.
• The three website pages under Modules touched describe the input socket, capabilities.input.enabled and INPUT_UNAVAILABLE.

Out of scope

• Any device actually taking input: Android in Android input through scrcpy's control channel #1018, iOS simulators and physical iPhones in iOS simulator input through the HID injector #1019, iOS rotation in iOS simulator rotation through Simulator.app #1020.
• The two-way relay itself and its protocol bump (Two-way relay over the uplink #1016).
• The lease stream route and the lease route seam for plain HTTP (A lease holder streams its lease's screen #1015).
• Input from the console; a preview {url, token}.

Depends on

• A lease holder streams its lease's screen #1015
• Two-way relay over the uplink #1016

Written by an agent.