mirrors/hermes-agent
1
0
Fork 0
mirror of https://github.com/NousResearch/hermes-agent.git synced 2026-07-31 19:16:29 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2
hermes-agent/plugins/platforms/photon/sidecar
History
Teknium e68f3fd825 fix(photon): harden structured sidecar error classes + target_not_allowed 
Maintainer follow-up to the #51193 salvage:

- _send_with_retry: permanent classes (auth_or_config, target_not_allowed)
  now short-circuit BEFORE the unconditional plain-text fallback resend,
  including when a retry attempt surfaces one — no more double-sends of
  permanently-failing requests.
- sidecar classifySidecarError: new structured code target_not_allowed for
  Spectrum's 'Target not allowed for this project' AuthenticationError
  (shared/free-tier lines cannot initiate outbound sends to new targets).
  Classification applies to every handler sharing the catch-all
  serverError path (/send, /send-attachment, /react, /typing, ...).
- _standalone_send now parses the structured error body too (it reads
  sidecar responses independently of _sidecar_call) and returns
  error_class/retryable alongside the message.
- target_not_allowed maps to a canonical user-facing message in both
  paths; raw upstream error text never leaks through the structured code.

Closes the actionable halves of #50971, #51897, #52794.
2026-07-28 21:45:52 -07:00
..
.gitignore fix(photon): surface npm install failures in check_requirements() diagnostic chain 2026-07-28 18:20:06 -07:00
index.mjs fix(photon): harden structured sidecar error classes + target_not_allowed 2026-07-28 21:45:52 -07:00
package-lock.json fix(photon): upgrade spectrum-ts sidecar to v8.0.0 2026-06-27 00:51:34 -07:00
package.json fix(photon): upgrade spectrum-ts sidecar to v8.0.0 2026-06-27 00:51:34 -07:00
patch-spectrum-mixed-attachments.mjs feat(photon): upgrade spectrum-ts sidecar to v7.0.0 2026-06-27 00:51:34 -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.