plugin.yaml 4.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596
  1. name: photon-platform
  2. label: iMessage via Photon
  3. kind: platform
  4. version: 0.3.0
  5. description: >
  6. Photon Spectrum gateway adapter for Hermes Agent.
  7. Connects to iMessage (and other Spectrum interfaces) through Photon's
  8. managed Spectrum platform. Both directions run over the `spectrum-ts`
  9. SDK's long-lived gRPC stream via a small supervised Node sidecar —
  10. inbound messages arrive on the SDK's `app.messages` stream (no webhook,
  11. no public URL, no signing secret), and outbound messages are sent over
  12. the same sidecar.
  13. The plugin ships with a `hermes photon` CLI for the one-time device
  14. login + project + user setup. Runtime credentials are written to
  15. ``~/.hermes/.env`` (``PHOTON_PROJECT_ID`` = the Spectrum project id,
  16. ``PHOTON_PROJECT_SECRET``) like every other channel, with management
  17. metadata (device token, dashboard project id) in ``~/.hermes/auth.json``.
  18. Photon's free shared-line model lets users get started without a paid plan.
  19. author: NousResearch
  20. requires_env:
  21. - name: PHOTON_PROJECT_ID
  22. description: "Spectrum project id (the project's spectrumProjectId; set by `hermes photon setup`)"
  23. prompt: "Photon Spectrum project id"
  24. url: "https://app.photon.codes/"
  25. password: false
  26. - name: PHOTON_PROJECT_SECRET
  27. description: "Project secret paired with the Spectrum project id (set by `hermes photon setup`)"
  28. prompt: "Photon project secret"
  29. url: "https://app.photon.codes/"
  30. password: true
  31. optional_env:
  32. - name: PHOTON_SIDECAR_PORT
  33. description: "Loopback port for the Node sidecar control + inbound channel (default 8789)"
  34. prompt: "Sidecar control port"
  35. password: false
  36. - name: PHOTON_SIDECAR_TOKEN
  37. description: "Shared secret for the loopback sidecar channel (default: random per start)"
  38. prompt: "Sidecar token"
  39. password: true
  40. - name: PHOTON_SIDECAR_AUTOSTART
  41. description: "Spawn the Node sidecar on connect (true/false, default true)"
  42. prompt: "Auto-start the sidecar?"
  43. password: false
  44. - name: PHOTON_NODE_BIN
  45. description: "Path to the node binary (default: PM's pinned node, then PATH)"
  46. prompt: "Node executable path"
  47. password: false
  48. - name: PHOTON_DASHBOARD_HOST
  49. description: "Photon Dashboard API host (default https://app.photon.codes)"
  50. prompt: "Dashboard host"
  51. password: false
  52. - name: PHOTON_SPECTRUM_HOST
  53. description: "Photon Spectrum API host (default https://spectrum.photon.codes)"
  54. prompt: "Spectrum API host"
  55. password: false
  56. - name: PHOTON_ALLOWED_USERS
  57. description: "Comma-separated E.164 phone numbers allowed to talk to the bot"
  58. prompt: "Allowed users (comma-separated)"
  59. password: false
  60. - name: PHOTON_ALLOW_ALL_USERS
  61. description: "Allow any sender to trigger the bot (dev only — disables allowlist)"
  62. prompt: "Allow all users? (true/false)"
  63. password: false
  64. - name: PHOTON_READ_RECEIPTS
  65. description: "Mark inbound iMessages read after forwarding to Hermes (true/false, default true)"
  66. prompt: "Send read receipts? (true/false)"
  67. password: false
  68. - name: PHOTON_REQUIRE_MENTION
  69. description: "Ignore group-chat messages unless they match a mention wake word (true/false, default false)"
  70. prompt: "Require a mention in group chats?"
  71. password: false
  72. - name: PHOTON_MENTION_PATTERNS
  73. description: "Mention wake-word regexes for group chats (JSON list or comma/newline-separated; defaults to Hermes wake words)"
  74. prompt: "Group mention patterns"
  75. password: false
  76. - name: PHOTON_HOME_CHANNEL
  77. description: "Default Photon target for cron / notification delivery: Spectrum space id, DM GUID, or bare E.164 phone number"
  78. prompt: "Home Photon target"
  79. password: false
  80. - name: PHOTON_HOME_CHANNEL_NAME
  81. description: "Human label for the home channel"
  82. prompt: "Home channel display name"
  83. password: false
  84. - name: PHOTON_TELEMETRY
  85. description: "Enable Spectrum SDK telemetry in the sidecar (true/false, default false; toggle with `hermes photon telemetry on|off`)"
  86. prompt: "Enable Spectrum telemetry? (true/false)"
  87. password: false
  88. - name: PHOTON_MARKDOWN
  89. description: "Send agent replies as markdown — iMessage renders it natively, other Spectrum platforms degrade to plain text (true/false, default true)"
  90. prompt: "Render replies as markdown? (true/false)"
  91. password: false
  92. - name: PHOTON_REACTIONS
  93. description: "Tapback 👀/👍/👎 on messages as processing status and route tapbacks on bot messages to the agent (true/false, default false)"
  94. prompt: "Enable reaction tapbacks? (true/false)"
  95. password: false