feat(gateway): add Photon Spectrum (iMessage) platform plugin

First-class iMessage support via Photon's managed Spectrum platform.
Targeted as a successor to the BlueBubbles adapter — Photon allocates
the iMessage line, handles delivery, and abuse-prevention so users
don't have to run their own Mac relay. Free tier uses Photon's shared
line pool.

Architecture:
- Inbound: signed JSON webhooks (X-Spectrum-Signature, HMAC-SHA256)
  delivered to a local aiohttp listener. Dedupes on message.id,
  rejects deliveries with >5min timestamp drift.
- Outbound: small supervised Node sidecar that runs the spectrum-ts
  SDK. Photon does not currently expose a public HTTP send-message
  endpoint; the sidecar is the only way to call Space.send() today.
  When Photon ships an HTTP send endpoint we collapse the sidecar
  into _sidecar_send and drop the Node dep — every other layer of
  the plugin stays the same.
- Setup: 'hermes photon login' runs the RFC 8628 device-code flow;
  'hermes photon setup' creates a Spectrum-enabled project, creates
  a shared user (free tier), installs the sidecar's npm deps.
- Webhook management: 'hermes photon webhook register|list|delete'.
- Credentials persisted under credential_pool.photon /
  credential_pool.photon_project in ~/.hermes/auth.json.

Plugin path (not built-in) — per current policy (May 2026), all new
platforms ship under plugins/platforms/. Registers itself via
ctx.register_platform() + ctx.register_cli_command(), zero edits to
core gateway code.

Tests cover:
- HMAC-SHA256 signature verification (happy path, tampered body,
  wrong secret, drift, missing v0 prefix, empty inputs, non-integer
  timestamp)
- Inbound dispatch for text DMs, group ids (any;+;...), and
  attachment metadata markers
- Deduplication window
- check_requirements gating when Node is absent
- Device-code flow: request, header-based token return,
  body-fallback token return, access_denied propagation
- Project/user/webhook API clients with mocked httpx

Known limitations (current Photon API):
- Attachments are metadata only — no download URL yet
- Outbound attachment send not wired (sidecar can add easily)
- Reactions / message effects not exposed yet

Docs: website/docs/user-guide/messaging/photon.md + sidebar entry.

plugins/platforms/photon/sidecar/README.md

@@ -0,0 +1,52 @@
+# Photon sidecar
+
+Small Node helper that bridges Hermes Agent to Photon's Spectrum SDK
+(`spectrum-ts`).  Hermes is Python; Photon has no public HTTP
+send-message endpoint today; replies therefore go through this sidecar.
+
+The sidecar:
+
+- runs `Spectrum({ projectId, projectSecret, providers: [imessage.config()] })`
+- exposes a loopback-only HTTP control channel for the Python adapter
+  to push send/typing requests (auth via `X-Hermes-Sidecar-Token`)
+- drains the inbound message stream so `spectrum-ts` keeps its
+  reconnect/heartbeat machinery alive (real inbound delivery is via
+  Photon's signed webhook hitting our Python aiohttp server)
+
+## Install
+
+```bash
+cd plugins/platforms/photon/sidecar
+npm install
+```
+
+The Hermes plugin's `hermes photon setup` command runs `npm install`
+here automatically.
+
+## Run standalone
+
+For debugging:
+
+```bash
+PHOTON_PROJECT_ID=... PHOTON_PROJECT_SECRET=... \
+PHOTON_SIDECAR_PORT=8789 PHOTON_SIDECAR_TOKEN=$(openssl rand -hex 16) \
+node index.mjs
+```
+
+In normal use, the Python adapter supervises this process — start,
+restart on crash, kill on shutdown — and never asks the user to run
+it by hand.
+
+## Why a sidecar at all?
+
+Photon publishes webhooks (inbound) but their docs state explicitly:
+
+> Pass `space.id` to `Space.send(...)` from a separate `spectrum-ts`
+> SDK instance to reply.  No public HTTP send endpoint exists today.
+
+— https://photon.codes/docs/webhooks/events
+
+When Photon ships an HTTP send endpoint, the plan is to retire this
+sidecar entirely and call it directly from Python.  The plugin's
+outbound code path is already isolated behind a single helper
+(`_sidecar_send` in `adapter.py`) to make that swap a one-file change.

plugins/platforms/photon/sidecar/index.mjs

@@ -0,0 +1,221 @@
+// Hermes Agent — Photon Spectrum sidecar
+//
+// Spawned by `plugins/platforms/photon/adapter.py` to bridge outbound
+// messaging to Photon's Spectrum platform. Inbound messages go directly
+// from Photon's webhook to Hermes' Python aiohttp receiver — this
+// sidecar handles ONLY outbound calls (which require the spectrum-ts
+// SDK because Photon has no public HTTP send endpoint today).
+//
+// Protocol:
+//   - The sidecar listens on http://127.0.0.1:${PORT} (loopback only)
+//   - Each request must include `X-Hermes-Sidecar-Token: ${TOKEN}`
+//   - POST /healthz                     -> {"ok": true}
+//   - POST /send                        -> {"ok": true, "messageId": "..."}
+//       body: {"spaceId": "...", "text": "...", "replyTo": "..." | null}
+//   - POST /typing                      -> {"ok": true}
+//       body: {"spaceId": "..."}
+//   - POST /shutdown                    -> {"ok": true}; then process exits
+//
+// On SIGINT/SIGTERM the sidecar calls `app.stop()` (3s graceful) before
+// exiting. Errors are logged to stderr; Python supervises restart.
+//
+// Env vars (all required):
+//   PHOTON_PROJECT_ID
+//   PHOTON_PROJECT_SECRET
+//   PHOTON_SIDECAR_PORT
+//   PHOTON_SIDECAR_TOKEN
+//
+// Optional:
+//   PHOTON_SIDECAR_BIND  (default 127.0.0.1)
+//   PHOTON_API_HOST      (passed through to spectrum-ts if its config
+//                         honours it)
+
+import http from "node:http";
+
+const projectId = process.env.PHOTON_PROJECT_ID;
+const projectSecret = process.env.PHOTON_PROJECT_SECRET;
+const port = parseInt(process.env.PHOTON_SIDECAR_PORT || "8789", 10);
+const bind = process.env.PHOTON_SIDECAR_BIND || "127.0.0.1";
+const sharedToken = process.env.PHOTON_SIDECAR_TOKEN;
+
+if (!projectId || !projectSecret || !sharedToken) {
+  console.error(
+    "photon-sidecar: PHOTON_PROJECT_ID, PHOTON_PROJECT_SECRET and " +
+      "PHOTON_SIDECAR_TOKEN must all be set."
+  );
+  process.exit(2);
+}
+
+// Lazy-load spectrum-ts so a missing install fails with a clear message
+// instead of a cryptic module-resolution error during import.
+let Spectrum, imessage;
+try {
+  ({ Spectrum } = await import("spectrum-ts"));
+  ({ imessage } = await import("spectrum-ts/providers/imessage"));
+} catch (e) {
+  console.error(
+    "photon-sidecar: spectrum-ts is not installed. Run `npm install` " +
+      "inside plugins/platforms/photon/sidecar/. Original error: " +
+      (e && e.stack ? e.stack : String(e))
+  );
+  process.exit(3);
+}
+
+const app = await Spectrum({
+  projectId,
+  projectSecret,
+  providers: [imessage.config()],
+});
+
+// Drain the inbound stream — Photon's webhook is the canonical inbound
+// path, but we still consume `app.messages` so spectrum-ts' internal
+// reconnect/heartbeat logic keeps running.  Each event is logged at
+// debug level; everything else is a no-op here.
+(async () => {
+  try {
+    for await (const [, message] of app.messages) {
+      console.error(
+        `photon-sidecar: drained inbound from ${message.platform} ` +
+          `space=${message.space?.id}`
+      );
+    }
+  } catch (e) {
+    console.error(
+      "photon-sidecar: inbound stream errored: " +
+        (e && e.stack ? e.stack : String(e))
+    );
+  }
+})();
+
+async function readBody(req) {
+  const chunks = [];
+  for await (const chunk of req) chunks.push(chunk);
+  const raw = Buffer.concat(chunks).toString("utf-8");
+  if (!raw) return {};
+  try {
+    return JSON.parse(raw);
+  } catch (e) {
+    throw new Error("invalid JSON body");
+  }
+}
+
+function unauthorized(res) {
+  res.statusCode = 401;
+  res.setHeader("Content-Type", "application/json");
+  res.end(JSON.stringify({ ok: false, error: "unauthorized" }));
+}
+
+function badRequest(res, msg) {
+  res.statusCode = 400;
+  res.setHeader("Content-Type", "application/json");
+  res.end(JSON.stringify({ ok: false, error: msg }));
+}
+
+function serverError(res, msg) {
+  res.statusCode = 500;
+  res.setHeader("Content-Type", "application/json");
+  res.end(JSON.stringify({ ok: false, error: msg }));
+}
+
+function ok(res, data) {
+  res.statusCode = 200;
+  res.setHeader("Content-Type", "application/json");
+  res.end(JSON.stringify({ ok: true, ...data }));
+}
+
+async function resolveSpace(spaceId) {
+  // spectrum-ts exposes the same Space methods via `app.space(spaceId)` /
+  // narrowed helpers; we fall back through a few accessor shapes to
+  // tolerate small SDK API drift.
+  if (typeof app.space === "function") {
+    return await app.space(spaceId);
+  }
+  if (app.spaces && typeof app.spaces.get === "function") {
+    return await app.spaces.get(spaceId);
+  }
+  // Last resort — the platform-narrowed helper.
+  if (imessage) {
+    const im = imessage(app);
+    if (typeof im.space === "function") {
+      try {
+        return await im.space({ id: spaceId });
+      } catch {
+        /* fall through */
+      }
+    }
+  }
+  throw new Error(`unable to resolve space id ${spaceId}`);
+}
+
+const server = http.createServer(async (req, res) => {
+  if (req.headers["x-hermes-sidecar-token"] !== sharedToken) {
+    return unauthorized(res);
+  }
+  if (req.method !== "POST") {
+    res.statusCode = 405;
+    return res.end();
+  }
+  try {
+    if (req.url === "/healthz") {
+      return ok(res, {});
+    }
+    if (req.url === "/shutdown") {
+      ok(res, {});
+      setTimeout(() => process.kill(process.pid, "SIGTERM"), 50);
+      return;
+    }
+    const body = await readBody(req);
+    if (req.url === "/send") {
+      const { spaceId, text, replyTo } = body || {};
+      if (!spaceId || typeof text !== "string") {
+        return badRequest(res, "spaceId and text are required");
+      }
+      const space = await resolveSpace(spaceId);
+      const result = replyTo
+        ? await space.send(text, { replyTo })
+        : await space.send(text);
+      return ok(res, { messageId: result?.id || result?.messageId || null });
+    }
+    if (req.url === "/typing") {
+      const { spaceId } = body || {};
+      if (!spaceId) return badRequest(res, "spaceId is required");
+      const space = await resolveSpace(spaceId);
+      if (typeof space.typing === "function") {
+        await space.typing();
+      } else if (typeof space.setTyping === "function") {
+        await space.setTyping(true);
+      }
+      return ok(res, {});
+    }
+    res.statusCode = 404;
+    res.setHeader("Content-Type", "application/json");
+    return res.end(JSON.stringify({ ok: false, error: "not found" }));
+  } catch (e) {
+    console.error(
+      "photon-sidecar: handler error: " +
+        (e && e.stack ? e.stack : String(e))
+    );
+    return serverError(res, String((e && e.message) || e));
+  }
+});
+
+server.listen(port, bind, () => {
+  console.error(`photon-sidecar: listening on ${bind}:${port}`);
+});
+
+async function shutdown(signal) {
+  console.error(`photon-sidecar: received ${signal}, stopping...`);
+  try {
+    await Promise.race([
+      app.stop(),
+      new Promise((resolve) => setTimeout(resolve, 3000)),
+    ]);
+  } catch (e) {
+    console.error("photon-sidecar: app.stop() failed: " + String(e));
+  }
+  server.close(() => process.exit(0));
+  setTimeout(() => process.exit(1), 500).unref();
+}
+
+process.on("SIGINT", () => shutdown("SIGINT"));
+process.on("SIGTERM", () => shutdown("SIGTERM"));

plugins/platforms/photon/sidecar/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@hermes-agent/photon-sidecar",
+  "private": true,
+  "version": "0.1.0",
+  "description": "Spectrum-ts bridge for the Hermes Agent Photon platform plugin.",
+  "type": "module",
+  "main": "index.mjs",
+  "scripts": {
+    "start": "node index.mjs"
+  },
+  "engines": {
+    "node": ">=18.17"
+  },
+  "dependencies": {
+    "spectrum-ts": "^0.1.0"
+  }
+}