Agent Update Progress

The portal shows each phase of an OTA self-update as it happens.

RPCs

RPC	Caller	Purpose
PortalGatewayService.UpdateGatewayAgent	portal	Record the desired version, seed a scheduled phase, send update_agent
GatewayInternalService.ReportAgentUpdate	realtime DO	Persist a phase reported by the agent
PortalGatewayService.GetAgentUpdateStatus	portal	Read the current phase (read-only)

Reporting path

sequenceDiagram
    participant A as Edge agent
    participant DO as realtime DO
    participant N as Nexus
    participant P as Portal

    A->>DO: WS {type: agent_update, phase, target_version, from_version, error}
    DO->>N: GatewayInternalService.ReportAgentUpdate
    N->>N: persist phase, record a device event
    P->>N: GetAgentUpdateStatus
    N-->>P: current phase

The agent never calls nexus directly for this. It writes to its WebSocket, and the Durable Object makes the internal call, just as it does for ConfigReport.

The device is the only party that knows where it is in the update. While it downloads, verifies, swaps and restarts, it is briefly unreachable, so the last reported phase is what tells the operator where it stopped.

Relationship to the watchdog

Progress reporting is for observability only. The watchdog is what reverts a failed update. A device can roll back and report that it did. If it hangs badly enough to report nothing, the stalled phase in the timeline tells the operator that.

The installed version comes from the regular state report, so the fleet view shows what is running rather than what was last requested.