172 lines
8.9 KiB
Markdown
172 lines
8.9 KiB
Markdown
# Hand-off: Gateway restart UX (spinner + "back online" message)
|
|
|
|
> This document is a hand-off. A previous attempt at this task is **incomplete
|
|
> and leaves the chat in a broken state**. Read this fully before touching code.
|
|
|
|
## 1. Original task (from the user)
|
|
|
|
On **gateway restart** the Android/desktop app had two problems:
|
|
|
|
1. A **spinner spins endlessly** (a tool card that never completes).
|
|
2. There is **no "gateway back online" message**.
|
|
|
|
The user wants the standard hermes routine (same wording on all apps):
|
|
|
|
```
|
|
⚠️ Gateway restarting — Your current task will be interrupted. Send any message after restart and I'll try to resume where you left off.
|
|
```
|
|
```
|
|
♻️ Gateway online — Hermes is back and ready.
|
|
```
|
|
|
|
## 2. Architecture (critical context)
|
|
|
|
Three layers, only two are editable:
|
|
|
|
- **`hermes-agent/`** — READ-ONLY research reference (git-ignored, pre-commit
|
|
hook blocks commits). The hermes **core** lives here. Do NOT modify it.
|
|
- **`gateway-plugin/`** — the editable Python `android` platform plugin
|
|
(symlinked into `~/.hermes/plugins/android`). `adapter.py` is the outbound
|
|
frame classifier. This is where the gateway turns core `adapter.send()` calls
|
|
into WS frames.
|
|
- **`app/`** — Compose Multiplatform (Kotlin). `:shared` holds most code
|
|
(`jvmMain` is shared by android + desktop). `IrisController` routes frames
|
|
into `ChatStore`; `ChatScreen` renders.
|
|
|
|
### How the hermes core signals a restart (verified in logs + code)
|
|
|
|
- On **shutdown/restart** the core calls `adapter.send(home_channel, "⚠️ Gateway
|
|
restarting|shutting down — …")`. The android adapter classifies this into a
|
|
frame. The core **does** send this to the android home channel (log line:
|
|
`Sent shutdown notification to home channel android:android:default`).
|
|
- On **startup** the core sends "♻️ Gateway online — …" to home channels of
|
|
*configured* platforms, but **does NOT send it to the android platform**
|
|
(no such log line ever appears). So the app must generate the "online" notice
|
|
itself.
|
|
|
|
### The gateway is a transient systemd user service
|
|
|
|
- Unit: `iris-hermes-gw.service` (transient, `/run/user/1000/systemd/transient/`).
|
|
- **It does NOT auto-revive on SIGTERM.** After a SIGTERM it goes to `failed`
|
|
and stays down until you run:
|
|
`systemctl --user restart iris-hermes-gw.service`
|
|
- Logs: `~/.hermes/logs/gateway.log`. Outbox DB: `~/.hermes/android/outbox.db`
|
|
(table `outbox(cursor, chat_id, frame, created)`).
|
|
|
|
## 3. What the previous attempt changed (all uncommitted, in working tree)
|
|
|
|
Run `git diff` to see the full patch. Summary:
|
|
|
|
### App (Kotlin)
|
|
- `app/shared/src/commonMain/kotlin/iris/util/TimeFormat.kt` +
|
|
`app/shared/src/jvmMain/kotlin/iris/util/TimeFormatJvm.kt`
|
|
— added `nowMillis(): Long` (expect/actual) for wall-clock timestamps.
|
|
- `app/shared/src/commonMain/kotlin/iris/data/ChatStore.kt`
|
|
- `MessageItem` gained `isSystem: Boolean = false`.
|
|
- `addSystemMessage(lane, text)` — appends a centered local notice.
|
|
- `finalizeInterrupted()` — marks open `ToolItem`s `done=true, ok=false` and
|
|
streaming `MessageItem`s `streaming=false`, across all lanes.
|
|
- `app/shared/src/commonMain/kotlin/iris/state/IrisController.kt`
|
|
- In the `client.state.collect` block, tracks `prevState`:
|
|
- `Reconnecting → Connected`: posts `GATEWAY_ONLINE_MSG`
|
|
("♻️ Gateway online — Hermes is back and ready.") to the current lane.
|
|
- `Connected → Reconnecting`: calls `chat.finalizeInterrupted()`.
|
|
- New constant `GATEWAY_ONLINE_MSG`.
|
|
- `app/shared/src/commonMain/kotlin/iris/ui/screens/ChatScreen.kt`
|
|
- Renders `isSystem` messages via a new centered `SystemMessage` composable
|
|
(non-selectable pill).
|
|
|
|
### Gateway plugin (Python)
|
|
- `gateway-plugin/adapter.py`
|
|
- New `_is_gateway_lifecycle_notice(content)` — true when content contains
|
|
"Gateway restarting" / "Gateway shutting down" / "Gateway online".
|
|
- In `send()`, the tool-progress branch now skips lifecycle notices so they
|
|
fall through to **commentary** instead of a `tool.start` card.
|
|
|
|
## 4. Current (BROKEN) state — what the user is seeing
|
|
|
|
After several test restarts, the chat shows a **stack of repeated entries**:
|
|
multiple "⚠️ Gateway shutting down" cards (some with a **spinning** indicator,
|
|
some with a red ✗) interleaved with "♻️ Gateway online" pills. The **last**
|
|
entry is "Gateway shutting down" even though the app is **connected**. The user
|
|
is (correctly) unhappy: the ordering is wrong and a spinner is present.
|
|
|
|
### The two concrete defects
|
|
|
|
1. **Wrong ordering / stale "shutting down" last.** On reconnect the app posts
|
|
"♻️ Gateway online", but then the **`sync` catch-up replay** re-delivers the
|
|
"⚠️ Gateway shutting down" frame that the *old* gateway parked in the outbox
|
|
during shutdown. That replayed frame lands **after** the "online" notice, so
|
|
the newest line reads "shutting down" while connected.
|
|
|
|
2. **Spinner returns.** The outbox still contains `tool.start` frames for the
|
|
"Gateway shutting down" notice that were written **before** the adapter fix
|
|
was loaded. The `sync` replay turns those into tool cards that never receive
|
|
a `tool.end`, so they spin. The adapter fix only stops *new* `tool.start`
|
|
frames; it does not clean up the already-parked ones.
|
|
|
|
### Root cause (the part the previous attempt did NOT solve)
|
|
|
|
The app's **reconnect catch-up (`sync`)** replays the outbox from the stored
|
|
cursor, and the app does **not** deduplicate or order these replayed lifecycle
|
|
frames against what it already rendered live. Consequences:
|
|
- Replayed "shutting down" frames appear after the locally-generated "online"
|
|
notice (wrong order).
|
|
- Replayed `tool.start` frames (pre-fix) become endless-spinning cards.
|
|
- Every restart adds another pair of entries (the "chaos" stack).
|
|
|
|
The previous attempt treated the symptoms (finalize on disconnect, add an online
|
|
notice, reclassify new notices) but did **not** address the replay/dedup/ordering
|
|
problem, which is what actually produces the visible mess.
|
|
|
|
## 5. What is verified vs. not
|
|
|
|
- **Verified working:** Kotlin compiles (android + desktop), 53/53 Python
|
|
`tests/gateway/test_android.py` pass, the "♻️ Gateway online" pill renders,
|
|
and *new* lifecycle notices now render as commentary (not a tool card).
|
|
- **NOT working / still broken:** the chat accumulates a mis-ordered stack of
|
|
"shutting down"/"online" entries and a spinning tool card after restarts.
|
|
|
|
## 6. Suggested direction for the next engineer
|
|
|
|
Pick the cleanest of these (or a combination); the goal is: after a restart the
|
|
chat shows at most one "⚠️ Gateway restarting" then one "♻️ Gateway online", in
|
|
that order, with **no** spinner and **no** accumulation across restarts.
|
|
|
|
1. **Dedup/order lifecycle notices in the app.** Give the restart/online notices
|
|
stable identities and reconcile them (like `MessageItem` is by `messageId`):
|
|
a replayed "shutting down" that is already present should not be re-added,
|
|
and the "online" notice should supersede the "shutting down" one (replace,
|
|
not append). Consider a single "gateway state" line that updates in place
|
|
(restarting → online) instead of appending a new line each transition.
|
|
2. **Stop the spinner at the source.** Ensure no `tool.start` is ever emitted
|
|
for a lifecycle notice (adapter fix is done for new frames) AND make the app
|
|
resilient: a `tool.start` with no matching `tool.end` should not spin
|
|
indefinitely (e.g., finalize on the next turn, on reconnect, or time out).
|
|
3. **Cursor hygiene.** Investigate why the `sync` replay re-delivers frames the
|
|
app already rendered live (live broadcasts may not advance the stored
|
|
`syncCursor`). If live frames should advance the cursor, the replay would not
|
|
re-add them. Check `GatewayClient.dial` (sends `sync`), the `TYPE_SYNC_DONE`
|
|
handler in `IrisController`, and the gateway `on_sync`/outbox cursor logic.
|
|
4. **Clean the existing mess.** The outbox (`~/.hermes/android/outbox.db`) and
|
|
the app's in-memory lanes currently hold the stacked test entries. Decide
|
|
whether to prune the outbox and/or reset the app's chat state
|
|
(`adb shell pm clear dev.iris.app`) so the user starts clean.
|
|
|
|
## 7. Commands
|
|
|
|
- Build/verify app: `cd app && ./gradlew :shared:compileKotlinDesktop :androidApp:compileDebugKotlin`
|
|
- Install on phone: `cd app && ./gradlew :androidApp:installDebug` (device `a5ca2a4b`)
|
|
- Python tests: `cd hermes-agent && scripts/run_tests.sh tests/gateway/test_android.py`
|
|
- Restart gateway: `systemctl --user restart iris-hermes-gw.service`
|
|
- Screenshot: `adb exec-out screencap -p > /tmp/shot.png`
|
|
- Launch app: `adb shell am start -n dev.iris.app/.MainActivity`
|
|
- Reset app state: `adb shell pm clear dev.iris.app`
|
|
- Gateway log: `~/.hermes/logs/gateway.log`
|
|
|
|
## 8. Environment state at hand-off time
|
|
|
|
- Gateway: **running** (systemd `iris-hermes-gw.service` active).
|
|
- App: **installed** on the phone with the (broken) changes above.
|
|
- Working tree: 6 modified files (see `git diff`), **nothing committed**.
|
|
- The phone's chat currently shows the stacked test entries described in §4. |