feat(photon): markdown rendering, emoji reactions, sidecar lifecycle fixes, telemetry toggle (salvage #44486)

plugins/platforms/photon/README.md

@@ -35,8 +35,9 @@ talks to it over loopback.
   `GET /inbound` (NDJSON). The adapter dedupes on `messageId` and dispatches
   a `MessageEvent` to the gateway. It reconnects automatically if the stream
   drops; the sidecar owns the gRPC reconnect to Photon.
-- **Outbound**: `send` / `send_typing` are loopback POSTs to the sidecar,
-  authenticated with a shared `X-Hermes-Sidecar-Token`.
+- **Outbound**: `send` / `send_typing` / reaction tapbacks are loopback POSTs
+  to the sidecar (`/send`, `/send-attachment`, `/typing`, `/react`,
+  `/unreact`), authenticated with a shared `X-Hermes-Sidecar-Token`.
 
 ## First-time setup
 
@@ -59,7 +60,9 @@ hermes gateway start --platform photon
    a user with that number already exists).
 5. **Print the assigned iMessage line** — the number you text to reach your
    agent.
-6. **Install the sidecar deps** (`spectrum-ts`).
+6. **Install the sidecar deps** (`npm ci` — installs the committed lockfile
+   verbatim, so every setup runs the exact `spectrum-ts` version this plugin
+   was written against).
 
 There is no separate `login` command; like every other Hermes channel,
 onboarding goes through one setup surface. Re-running `setup` reuses an
@@ -116,6 +119,9 @@ All env vars are documented in `plugin.yaml`. The most important:
 | `PHOTON_ALLOWED_USERS`    | your number (set by setup) | Comma-separated E.164 allowlist      |
 | `PHOTON_REQUIRE_MENTION`  | false                      | Gate group chats on a wake word      |
 | `PHOTON_MAX_INLINE_ATTACHMENT_BYTES` | 20 MB           | Max inbound attachment size the sidecar reads & inlines |
+| `PHOTON_TELEMETRY`        | false                      | Spectrum SDK telemetry — toggle with `hermes photon telemetry on\|off` (restart the gateway to apply) |
+| `PHOTON_MARKDOWN`         | true                       | Send agent replies as markdown (iMessage renders natively). `false` strips formatting to plain text |
+| `PHOTON_REACTIONS`        | false                      | Tapback 👀/👍/👎 as processing status; tapbacks on bot messages reach the agent as `reaction:added:<emoji>` |
 
 ## Attachments & limitations
 
@@ -131,7 +137,38 @@ All env vars are documented in `plugin.yaml`. The most important:
   documents are sent via `space.send(attachment(...))` /
   `space.send(voice(...))` through the sidecar's `/send-attachment`
   endpoint; a caption is delivered as a separate text bubble after the media.
-- **Reactions, message effects, polls** — supported by `spectrum-ts` but not
-  yet exposed; the sidecar is the natural place to add them.
+- **Markdown is rendered.** Replies go out via spectrum-ts' `markdown()`
+  builder; iMessage renders bold/italics/lists/code natively and other
+  Spectrum platforms degrade to readable plain text. `PHOTON_MARKDOWN=false`
+  reverts to stripped plain text.
+- **Reactions (tapbacks) are supported** behind `PHOTON_REACTIONS` (default
+  off): the adapter tapbacks 👀 while processing and swaps it for 👍/👎 on
+  completion, and a user tapback on a bot-sent message is routed to the agent
+  as a synthetic `reaction:added:<emoji>` event. Removal after a sidecar
+  restart is best-effort — the live reaction handle is lost, so a stale
+  tapback heals when the next reaction replaces it. Group spaces stay
+  reachable across restarts via spectrum-ts v3's `space.get(id)`.
+- **Message effects, polls** — supported by `spectrum-ts` but not yet
+  exposed; the sidecar is the natural place to add them.
+
+## Upgrading spectrum-ts
+
+`spectrum-ts` is pinned to an **exact version** in `sidecar/package.json`
+(no `^` range) and installed with `npm ci`, because the SDK ships breaking
+majors (v2 removed `defineFusorPlatform`; v3 reworked space construction).
+A floating range or `npm install spectrum-ts@latest` would let a breaking
+release take down fresh setups silently. Upgrades are deliberate:
+
+1. Read the [SDK release notes](https://github.com/photon-hq/spectrum-ts/releases)
+   for every version between the current pin and the target.
+2. Bump the exact pin in `sidecar/package.json`, then run `npm install`
+   inside `sidecar/` to regenerate `package-lock.json`. Commit both.
+3. Migrate `sidecar/index.mjs` against the new typings
+   (`sidecar/node_modules/spectrum-ts/dist/*.d.ts` is the source of truth —
+   the hosted docs can lag).
+4. Run `pytest tests/plugins/platforms/photon/`.
+5. Verify end-to-end: `hermes photon status`, a DM and a group roundtrip,
+   and an agent reply into a group right after a gateway restart (exercises
+   `space.get` rehydration).
 
 [photon]: https://photon.codes/