Module http_viewer 

The viewer routes a paired device calls, served only on the viewer listener (TLS, backend::lan_listeners), never on the loopback or LAN routers (agentmux-mobile’s SPEC_AGENT_STATUS_AND_LIVE_PANE_FEED_2026_10_07 §13.2, §13.3):

• POST /agentmux/viewer/pair: a pairing code for a viewer token. The only route without a token.
• GET /agentmux/viewer/hello, GET /agentmux/viewer/agents, GET /agentmux/viewer/agents/:name/feed, GET /agentmux/viewer/panes, GET /agentmux/viewer/terminals/:block_id/feed (server::http_viewer_terminal), GET /agentmux/viewer/procs, and GET /agentmux/viewer/sysinfo and …/sysinfo/feed (server::http_viewer_sysinfo): Authorization: Bearer amxv_… only. Neither the lan_key nor the instance auth_key opens them, and the token opens nothing else: no other router knows it.

Read-only throughout. An agent hidden from paired devices is left out of the list and its feed is 404; agents of other channels on this machine are 404 too for now (they are not in this channel’s registry).

Structs

AgentProbe 🔒

What a feed asks about its agent while it runs: the block it runs in now, whether it has been hidden from paired devices, its state, and the provider of a block it moves to.

FeedSource 🔒

Where a feed reads its agent’s transcript from.

FeedTiming 🔒

A feed’s clocks.

PairBody 🔒

ProcsQuery 🔒

Snapshot 🔒

A snapshot as read: where the feed stands after it, and its lines from from_line.

ViewerCaller 🔒

The paired device a request authenticated as.

Enums

CatchUp 🔒

What FeedSource::catch_up found.

Constants

FEED_HEARTBEAT 🔒

Heartbeat comment on a quiet feed.

FOLLOW_POLL 🔒

How often a feed checks that its agent hasn’t moved to another block, and reads lines of the agent’s shared transcript that no event of this block brought (another block, or another srv instance, running the same agent). The desktop pane polls the shared transcript as often (useAgentStream.ts, SHARED_ZONE_POLL_MS).

HEARTBEAT 🔒

READ_LIMIT 🔒

The most lines one bounded read returns (blockfile:read_range’s cap).

RETRY_PREAMBLE 🔒

SETTING_TOWER_SHARE 🔒

Settings key: let paired devices see this computer’s processes in their Tower (GET /agentmux/viewer/procs). Off unless set.

SNAPSHOT_TAIL_BYTES 🔒

SNAPSHOT_TAIL_TURNS 🔒

The snapshot: the last 50 turns or 256 KB, whichever is smaller.

STATUS_POLL 🔒

How often a feed looks at its agent’s state. One controller lookup and one block read, so a second is cheap and keeps the device’s chip current.

Functions

agent_hidden 🔒

Whether the agent in block_id is hidden from paired devices: its definition (the block’s agentId) has hide_from_devices set.

append_event 🔒

bad_request 🔒

build_viewer_router

The viewer router: pairing, plus the token-gated read-only routes.

feed_stream 🔒

One feed: retry, then a snapshot (or, for a reconnect whose Last-Event-ID still holds, the lines it missed as one append), then an append per published transcript append, reset + snapshot when the transcript is rewritten or the feed loses its place, and a heartbeat on a quiet stream. A status follows each snapshot and every change of the agent’s state (feed::status_step). Ends with reset when the device falls more than 1 MB behind or the agent is hidden, and silently when the device is revoked (its lease’s token) or goes away. The lease is held until the stream is dropped.

handle_viewer_agents 🔒

GET /agentmux/viewer/agents: this channel’s agents, hidden ones left out, sorted case-insensitively.

handle_viewer_feed 🔒

GET /agentmux/viewer/agents/:name/feed: the agent’s transcript as Server-Sent Events (see feed_stream). 404 for an agent that isn’t this channel’s or is hidden; 503 past the feed caps.

handle_viewer_hello 🔒

GET /agentmux/viewer/hello: who this is, and which device is asking.

handle_viewer_pair 🔒

POST /agentmux/viewer/pair: {code, device_name, device_key?} for {token, device_id, hostname, channel, version, install_id?}; 401 for an unknown or expired code, 429 after too many wrong ones.

handle_viewer_panes 🔒

GET /agentmux/viewer/panes: every pane on this computer, window by window and tab by tab, with each agent’s shell drawer (backend::viewer::panes): names, types, the agent name a feed opens by, and whether a terminal runs. No content, command line or working directory; agents hidden from paired devices, and their shells, are left out.

handle_viewer_procs 🔒

GET /agentmux/viewer/procs?filter=: this computer’s Tower snapshot for a paired device (SPEC_TOWER_TASK_MANAGER_PANE_2026_10_08.md §8.3): its tasks and the busiest and largest of its processes, names only, never a command line. 403 unless the user turned sharing on; an agent hidden from paired devices, and its processes, are left out.

not_found 🔒

provider_of 🔒

The agent’s provider id (claude, codex, …), ‘’ when unknown.

reset_event 🔒

snapshot_event 🔒

status_event 🔒

status {state, since_ms, now_ms}; state and since_ms are null when a state the device was shown has gone (it drops its chip).

viewer_auth_middleware 🔒

Admit a request carrying a paired device’s viewer token: its SHA-256 is compared, in constant time, with every paired device’s. Stamps the device’s last_seen_ms at most once a minute.

Type Aliases

StatusProbe 🔒

The state of the agent in a block, if it has one.