KrustyPlanet/hermes-agent
6
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
hermes-agent/plugins/platforms/photon/sidecar
History
underthestars-zhy a652131c42 fix(photon): stop gateway restarts from orphaning the sidecar on its port 
A hard gateway exit (crash, SIGKILL, supervisor restart) left the
detached Node sidecar running with a token the next gateway run doesn't
know, so it could never be told to /shutdown. Every replacement spawn
then died on EADDRINUSE, failing each 30→300s reconnect attempt while
the orphan kept consuming the inbound gRPC stream.

Two layers:
- Lifetime binding: the adapter now holds the sidecar's stdin as a
  pipe, and the sidecar (PHOTON_SIDECAR_WATCH_STDIN=1) shuts down on
  stdin EOF — fired by the OS on any parent death, including SIGKILL.
- Startup reaping: before spawning, the adapter probes the port and
  terminates a stale listener, but only after verifying its command
  line is a Photon sidecar; a foreign listener raises a clear error
  instead of being signalled.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-06-12 01:07:38 -07:00
..
index.mjs fix(photon): stop gateway restarts from orphaning the sidecar on its port 2026-06-12 01:07:38 -07:00
package-lock.json feat(photon): upgrade to spectrum-ts 3.0.0 (pinned) with markdown + reactions 2026-06-12 01:07:38 -07:00
package.json feat(photon): upgrade to spectrum-ts 3.0.0 (pinned) with markdown + reactions 2026-06-12 01:07:38 -07:00
README.md feat(gateway): add Photon Spectrum (iMessage) platform plugin 2026-06-08 13:38:30 -07:00

README.md

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

cd plugins/platforms/photon/sidecar
npm install

The Hermes plugin's hermes photon setup command runs npm install here automatically.

Run standalone

For debugging:

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.