mirrors/hermes-agent
1
0
Fork 0
mirror of https://github.com/NousResearch/hermes-agent.git synced 2026-06-09 08:21:50 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 10
hermes-agent/plugins/platforms/photon/sidecar
History
underthestars-zhy 4e4d27875f feat(photon): gRPC-native iMessage channel (no webhook) 
Make Photon iMessage a first-class persistent-connection channel like
Discord/Slack, using the spectrum-ts gRPC stream for both directions.

- Inbound: the sidecar forwards the SDK's app.messages gRPC stream to the
  adapter over a loopback GET /inbound (NDJSON) instead of webhooks. Drops
  the aiohttp webhook server, HMAC signature verification, public URL, and
  PHOTON_WEBHOOK_* config; adapter reconnects with backoff.
- Management plane: device login uses client_id=photon-cli against the
  single dashboard host (Bearer), matching the official photon-hq/cli;
  find-or-create "Hermes Agent" project, enable Spectrum, rotate secret,
  register user (with phone dedup), surface the assigned iMessage line.
- SDK projectId is the project's spectrumProjectId, not the dashboard id;
  runtime creds persist to ~/.hermes/.env like every other channel.
- CLI: 6-step setup, webhook subcommands removed.
- Tests/docs updated for the gRPC flow; sidecar pins spectrum-ts ^1.17.1.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-08 21:03:58 -07:00
..
index.mjs feat(photon): gRPC-native iMessage channel (no webhook) 2026-06-08 21:03:58 -07:00
package.json feat(photon): gRPC-native iMessage channel (no webhook) 2026-06-08 21:03:58 -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.