@aspectlylabs/mikka 0.0.702 → 0.0.703

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -46,13 +46,54 @@ For background operation, install a service after signing in:
46
46
  mikka daemon service install --server https://app.aspectlylabs.com/mikka --device-type laptop
47
47
  ```
48
48
 
49
- For public npm installations running under launchd or systemd, the server names
50
- a newer stable release in a heartbeat, command response or refused claim. The
51
- daemon installs that exact version when idle. A failed install keeps the running
52
- version, waits 5 minutes, then 30
53
- minutes, then 2 hours before retrying that version, and is reported to the server
54
- by code. Running work drains before installation and restart. Installation runs
55
- in the background so heartbeats remain available.
49
+ ## The device session
50
+
51
+ The daemon works only while it holds one WebSocket to the server's device
52
+ gateway (decision `docs/design/decisions/2026-11-17-2215-device-session-no-heartbeat.md`).
53
+ The open socket is the device's session: it is how the server knows the device
54
+ is online and that its runs are alive. There is no heartbeat and no fallback.
55
+
56
+ - The daemon registers, takes a gateway ticket and opens the socket. It pings
57
+ every 10 seconds and drops a socket that has said nothing for 30 seconds.
58
+ - When the socket opens, and on every `work` push, the daemon reads once: run
59
+ messages and stops, device commands, repository settings and queued runs. It
60
+ then claims queued runs, delivers buffered run output and resumes runs.
61
+ - When something changed (harnesses and models, device commands it finished,
62
+ a failed update, quotas), and once after each socket opens, it sends one
63
+ report. The report renews nothing.
64
+ - A dropped socket is redialed after 0.5 seconds, then 1, 2, 4 and so on up
65
+ to 30 seconds, with jitter. A socket that stayed open for a minute resets
66
+ the wait. While the socket is down the daemon only redials: it does not read
67
+ commands, run controls or reviews, and claims nothing.
68
+ - A run keeps running while the socket is open. When the socket drops, the run
69
+ may go on for 60 seconds; if no socket opens in that time, the daemon stops
70
+ it as `device_lost`.
71
+ - A server without a gateway has no devices. The daemon asks for a ticket again
72
+ every 30 seconds and does no work until the server has one.
73
+ - A cloud worker asks for its next token once, an hour before the current one
74
+ expires.
75
+
76
+ The daemon's local timer checks run deadlines and the watchdog, rescans agent
77
+ CLIs every 5 minutes and asks them for models every 6 hours. It sends nothing
78
+ unless the result changed and the session is open. Run checkpoints are sent
79
+ only when a run's work changed.
80
+
81
+ ## Updates
82
+
83
+ A daemon older than the server's minimum gets `426 daemonUpgradeRequired` on
84
+ every request, and the gateway closes its socket with code `4001`. The daemon
85
+ then stops connecting and claims no work; `mikka daemon status` shows
86
+ `"session": "update_required"`. Update it with
87
+ `npm install -g @aspectlylabs/mikka@latest` (or update Mikka Desktop), then sign
88
+ in again if asked.
89
+
90
+ For public npm installations running under launchd or systemd, updates are
91
+ automatic. The server names a newer stable release in a report answer or a
92
+ commands read; a daemon the server refused installs the release named in the
93
+ refusal, or else npm's `latest`. The daemon installs that exact version when no
94
+ run is active. A failed install keeps the running version, waits 5 minutes,
95
+ then 30 minutes, then 2 hours before retrying that version, and is reported to
96
+ the server by code. Running work drains before installation and restart.
56
97
  The service keeps its server, data directory and device identity. Foreground,
57
98
  development and embedded daemons do not update themselves.
58
99