index.mjs 47 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294
  1. // Hermes Agent — Photon Spectrum sidecar
  2. //
  3. // Spawned by `plugins/platforms/photon/adapter.py` to bridge BOTH directions
  4. // of messaging to Photon's Spectrum platform via the `spectrum-ts` SDK (the
  5. // SDK is TypeScript-only, so a Node sidecar is unavoidable — there is no
  6. // Python SDK and no public HTTP message API).
  7. //
  8. // Inbound (gRPC -> Hermes): the SDK's `app.messages` async iterator is a
  9. // long-lived gRPC stream. We serialize each `[space, message]` to a
  10. // normalized JSON event and stream it to the Python adapter over a
  11. // loopback `GET /inbound` (NDJSON). We pause pulling from the stream while
  12. // no consumer is attached so a backlog isn't pulled-and-lost before the
  13. // gateway connects.
  14. // Outbound (Hermes -> gRPC): `/send` drives `space.send(...)`; `/typing`
  15. // sends the documented `typing("start" | "stop")` content builder.
  16. //
  17. // Protocol (all requests require `X-Hermes-Sidecar-Token: ${TOKEN}`):
  18. // - GET /inbound -> 200 NDJSON stream; one JSON event per line, blank
  19. // lines are heartbeats. One consumer at a time.
  20. // - POST /healthz -> {"ok": true}
  21. // - POST /send -> {"ok": true, "messageId": "..."}
  22. // body: {"spaceId": "...", "text": "...",
  23. // "format": "text" | "markdown" (default "text")}
  24. // - POST /send-richlink -> {"ok": true, "messageId": "..."}
  25. // body: {"spaceId": "...", "url": "https://..."}
  26. // - POST /send-attachment -> {"ok": true, "messageId": "..."}
  27. // body: {"spaceId": "...", "path": "...", "name": "..." | null,
  28. // "mimeType": "..." | null, "caption": "..." | null,
  29. // "kind": "attachment" | "voice"}
  30. // - POST /react -> {"ok": true, "reactionId": "..." | null}
  31. // body: {"spaceId": "...", "messageId": "<target msg id>",
  32. // "emoji": "👀"}
  33. // - POST /unreact -> {"ok": true} | 400 soft failure
  34. // body: {"spaceId": "...", "messageId": "<target msg id>",
  35. // "reactionId": "..." | null (restart-recovery fallback)}
  36. // - POST /send-poll -> {"ok": true, "messageId": "..."}
  37. // body: {"spaceId": "...", "title": "...", "options": ["...", "..."]}
  38. // Sends a native poll (orange iMessage poll bubble). A tap streams
  39. // back inbound as a `poll_option` event ({title, selected}).
  40. // - POST /send-effect -> {"ok": true, "messageId": "..."}
  41. // body: {"spaceId": "...", "text": "...", "effect": "confetti" | ...}
  42. // - POST /typing -> {"ok": true}
  43. // body: {"spaceId": "...", "state": "start" | "stop"}
  44. // - POST /shutdown -> {"ok": true}; then process exits
  45. //
  46. // On SIGINT/SIGTERM the sidecar calls `app.stop()` (3s graceful) before
  47. // exiting. Logs go to stderr; Python supervises restart.
  48. //
  49. // Requires a pinned spectrum-ts version — the SDK ships breaking majors; see
  50. // README "Upgrading spectrum-ts".
  51. //
  52. // Env vars (required):
  53. // PHOTON_PROJECT_ID (== the project's spectrumProjectId)
  54. // PHOTON_PROJECT_SECRET
  55. // PHOTON_SIDECAR_PORT
  56. // PHOTON_SIDECAR_TOKEN
  57. // Optional:
  58. // PHOTON_SIDECAR_BIND (default 127.0.0.1)
  59. // PHOTON_SIDECAR_WATCH_STDIN "1" = exit when stdin hits EOF (set by the
  60. // adapter, which holds our stdin pipe — parent-death
  61. // detection so a dead gateway can't orphan us)
  62. // PHOTON_TELEMETRY enable Spectrum SDK telemetry ("true"/"1"/"on"/"yes";
  63. // default off — toggle with `hermes photon telemetry`)
  64. import http from "node:http";
  65. import crypto from "node:crypto";
  66. import { once } from "node:events";
  67. import { patchSpectrumTs } from "./patch-spectrum-mixed-attachments.mjs";
  68. import { chooseSendFormat } from "./send-format.mjs";
  69. import {
  70. classifyProbeRejection,
  71. createProbeMessageId,
  72. shouldProbe,
  73. isZombieSuspect,
  74. } from "./stream-staleness.mjs";
  75. const projectId = process.env.PHOTON_PROJECT_ID;
  76. const projectSecret = process.env.PHOTON_PROJECT_SECRET;
  77. const port = parseInt(process.env.PHOTON_SIDECAR_PORT || "8789", 10);
  78. const bind = process.env.PHOTON_SIDECAR_BIND || "127.0.0.1";
  79. const sharedToken = process.env.PHOTON_SIDECAR_TOKEN;
  80. const telemetry = /^(1|true|yes|on)$/i.test(
  81. (process.env.PHOTON_TELEMETRY || "").trim()
  82. );
  83. // Inbound binary content is read into memory and base64-inlined on the NDJSON
  84. // event so the Python adapter can cache the real bytes (and the agent can see
  85. // images / transcribe voice). Cap the size we inline — above it we forward
  86. // metadata only and the adapter surfaces a text marker, so one large clip can't
  87. // balloon a single NDJSON line. Override via PHOTON_MAX_INLINE_ATTACHMENT_BYTES.
  88. const MAX_INLINE_ATTACHMENT_BYTES =
  89. Number(process.env.PHOTON_MAX_INLINE_ATTACHMENT_BYTES) || 20 * 1024 * 1024;
  90. const DM_CHAT_GUID_RE = /^any;-;(\+\d{6,})$/;
  91. const E164_RE = /^\+\d{6,}$/;
  92. const MAX_KNOWN_SPACES = 2048;
  93. const MAX_KNOWN_MESSAGES = 1024;
  94. const MAX_REACTION_HANDLES = 512;
  95. const STREAM_DEGRADED_RESTART_MS =
  96. Number(process.env.PHOTON_STREAM_DEGRADED_RESTART_MS) || 90 * 1000;
  97. const STREAM_INTERRUPTED_DEGRADE_COUNT =
  98. Number(process.env.PHOTON_STREAM_INTERRUPTED_DEGRADE_COUNT) || 3;
  99. // Zombie-stream (half-open gRPC) watchdog. The inbound iterator can hang
  100. // forever without erroring; we track when it last yielded and, once it has
  101. // been silent past this threshold, drive a cheap authenticated probe. Silence
  102. // alone NEVER degrades the stream (shared lines can be quiet for hours) and a
  103. // rejected probe is INCONCLUSIVE, never proof either way — degradation
  104. // requires silence past the threshold plus a probe-proven live channel.
  105. // A non-positive threshold disables the watchdog.
  106. const STREAM_SILENCE_PROBE_MS = (() => {
  107. const raw = Number(process.env.PHOTON_STREAM_SILENCE_PROBE_MS);
  108. return Number.isFinite(raw) ? raw : 10 * 60 * 1000;
  109. })();
  110. const STREAM_PROBE_COOLDOWN_MS =
  111. Number(process.env.PHOTON_STREAM_PROBE_COOLDOWN_MS) || 2 * 60 * 1000;
  112. const STREAM_PROBE_TIMEOUT_MS =
  113. Number(process.env.PHOTON_STREAM_PROBE_TIMEOUT_MS) || 10 * 1000;
  114. const STREAM_WATCHDOG_TICK_MS = 30 * 1000;
  115. const streamHealth = {
  116. state: "starting",
  117. degradedSince: null,
  118. lastHealthyAt: null,
  119. lastIssueAt: null,
  120. lastIssue: null,
  121. issueCount: 0,
  122. };
  123. let streamRestartTimer = null;
  124. // Zombie-watchdog runtime state (see stream-staleness.mjs for the rules).
  125. const staleness = {
  126. lastInboundAt: Date.now(),
  127. lastProbeAt: 0,
  128. lastProbeOutcome: null, // "alive" | "inconclusive" | null
  129. zombieSuspected: false,
  130. };
  131. function noteInboundYield() {
  132. staleness.lastInboundAt = Date.now();
  133. staleness.zombieSuspected = false;
  134. }
  135. function stalenessSnapshot(now) {
  136. return {
  137. lastInboundAt: new Date(staleness.lastInboundAt).toISOString(),
  138. silentForMs: now - staleness.lastInboundAt,
  139. silenceThresholdMs: STREAM_SILENCE_PROBE_MS,
  140. lastProbeAt:
  141. staleness.lastProbeAt > 0
  142. ? new Date(staleness.lastProbeAt).toISOString()
  143. : null,
  144. lastProbeOutcome: staleness.lastProbeOutcome,
  145. zombieSuspected: staleness.zombieSuspected,
  146. };
  147. }
  148. function streamHealthSnapshot() {
  149. const now = Date.now();
  150. const degradedForMs =
  151. streamHealth.degradedSince === null ? 0 : now - streamHealth.degradedSince;
  152. return {
  153. ok: streamHealth.state !== "degraded",
  154. state: streamHealth.state,
  155. degradedForMs,
  156. restartAfterMs: STREAM_DEGRADED_RESTART_MS,
  157. lastHealthyAt: streamHealth.lastHealthyAt,
  158. lastIssueAt: streamHealth.lastIssueAt,
  159. lastIssue: streamHealth.lastIssue,
  160. issueCount: streamHealth.issueCount,
  161. staleness: stalenessSnapshot(now),
  162. };
  163. }
  164. function markStreamHealthy() {
  165. streamHealth.state = "healthy";
  166. streamHealth.degradedSince = null;
  167. streamHealth.lastHealthyAt = new Date().toISOString();
  168. streamHealth.issueCount = 0;
  169. if (streamRestartTimer) {
  170. clearTimeout(streamRestartTimer);
  171. streamRestartTimer = null;
  172. }
  173. }
  174. function scheduleStreamRestart() {
  175. if (STREAM_DEGRADED_RESTART_MS <= 0 || streamRestartTimer) return;
  176. streamRestartTimer = setTimeout(() => {
  177. streamRestartTimer = null;
  178. if (streamHealth.state !== "degraded" || streamHealth.degradedSince === null) {
  179. return;
  180. }
  181. const degradedForMs = Date.now() - streamHealth.degradedSince;
  182. if (degradedForMs < STREAM_DEGRADED_RESTART_MS) {
  183. scheduleStreamRestart();
  184. return;
  185. }
  186. console.error(
  187. `photon-sidecar: upstream stream degraded for ${degradedForMs}ms; ` +
  188. "exiting so Hermes can restart the Photon adapter"
  189. );
  190. process.exit(75);
  191. }, STREAM_DEGRADED_RESTART_MS + 1000);
  192. streamRestartTimer.unref();
  193. }
  194. function markStreamDegraded(reason) {
  195. const now = Date.now();
  196. if (streamHealth.state !== "degraded") {
  197. streamHealth.degradedSince = now;
  198. }
  199. streamHealth.state = "degraded";
  200. streamHealth.lastIssueAt = new Date(now).toISOString();
  201. streamHealth.lastIssue = reason;
  202. streamHealth.issueCount += 1;
  203. scheduleStreamRestart();
  204. }
  205. function markStreamRecovering(reason) {
  206. if (streamHealth.state !== "recovering") {
  207. streamHealth.issueCount = 0;
  208. }
  209. streamHealth.state = "recovering";
  210. streamHealth.lastIssueAt = new Date().toISOString();
  211. streamHealth.lastIssue = reason;
  212. streamHealth.issueCount += 1;
  213. if (streamHealth.issueCount >= STREAM_INTERRUPTED_DEGRADE_COUNT) {
  214. markStreamDegraded(reason);
  215. }
  216. }
  217. function classifyStreamLog(text) {
  218. if (!text.includes("[spectrum.stream]")) return;
  219. const reason = text.split("\n", 1)[0];
  220. if (text.includes("persistently failing")) {
  221. markStreamDegraded(reason);
  222. } else if (text.includes("stream interrupted")) {
  223. markStreamRecovering(reason);
  224. }
  225. }
  226. // spectrum-ts routes its stream telemetry through @photon-ai/otel's
  227. // createLogger, which sends severity >= ERROR to console.error and
  228. // everything else (WARN/INFO) to console.log. The two lines we key off
  229. // land on *different* channels: `log.error("stream persistently failing")`
  230. // -> console.error, but `log.warn("stream interrupted; reconnecting")`
  231. // -> console.log. Patch both so the recovering/degraded counters see the
  232. // interrupt bursts, not just the terminal "persistently failing" line.
  233. const originalConsoleError = console.error.bind(console);
  234. console.error = (...args) => {
  235. const text = args
  236. .map((arg) => (arg && arg.stack ? arg.stack : String(arg)))
  237. .join(" ");
  238. classifyStreamLog(text);
  239. originalConsoleError(...args);
  240. };
  241. const originalConsoleLog = console.log.bind(console);
  242. console.log = (...args) => {
  243. const text = args
  244. .map((arg) => (arg && arg.stack ? arg.stack : String(arg)))
  245. .join(" ");
  246. classifyStreamLog(text);
  247. originalConsoleLog(...args);
  248. };
  249. // Upstream liveness probe (see `/probe` handler). A synthetic DM space id +
  250. // a unique-per-probe bogus message id drive a cheap unary read over the same
  251. // gRPC channel the inbound stream uses, so we can tell a live channel from a
  252. // half-open ("zombie") one. `space.get` is purely local in shared/dedicated
  253. // mode (no chat is created or messaged); only the message read hits the wire.
  254. const PROBE_SPACE_ID = process.env.PHOTON_PROBE_SPACE_ID || "any;-;+10000000000";
  255. if (!projectId || !projectSecret || !sharedToken) {
  256. console.error(
  257. "photon-sidecar: PHOTON_PROJECT_ID, PHOTON_PROJECT_SECRET and " +
  258. "PHOTON_SIDECAR_TOKEN must all be set."
  259. );
  260. process.exit(2);
  261. }
  262. // Lazy-load spectrum-ts so a missing install fails with a clear message
  263. // instead of a cryptic module-resolution error during import. Apply Hermes'
  264. // pinned-sdk compatibility patch first so existing installs self-heal at
  265. // runtime, not only during npm postinstall.
  266. try {
  267. const patchResult = patchSpectrumTs();
  268. if (patchResult.patched) {
  269. console.error(
  270. `photon-sidecar: spectrum mixed attachment patch applied: ${patchResult.file}`
  271. );
  272. }
  273. } catch (e) {
  274. console.error(
  275. "photon-sidecar: spectrum mixed attachment patch failed. " +
  276. "Run `npm install` inside plugins/platforms/photon/sidecar/ or " +
  277. "upgrade the Photon sidecar patch for the pinned spectrum-ts version. " +
  278. "Original error: " +
  279. (e && e.stack ? e.stack : String(e))
  280. );
  281. }
  282. let Spectrum,
  283. imessage,
  284. attachment,
  285. voice,
  286. spectrumText,
  287. spectrumMarkdown,
  288. spectrumRichlink,
  289. spectrumTyping,
  290. spectrumPoll,
  291. imessageEffect;
  292. try {
  293. ({
  294. Spectrum,
  295. attachment,
  296. voice,
  297. poll: spectrumPoll,
  298. text: spectrumText,
  299. markdown: spectrumMarkdown,
  300. richlink: spectrumRichlink,
  301. typing: spectrumTyping,
  302. } = await import("spectrum-ts"));
  303. ({ imessage, effect: imessageEffect } = await import("spectrum-ts/providers/imessage"));
  304. } catch (e) {
  305. console.error(
  306. "photon-sidecar: spectrum-ts is not installed. Run `npm install` " +
  307. "inside plugins/platforms/photon/sidecar/. Original error: " +
  308. (e && e.stack ? e.stack : String(e))
  309. );
  310. process.exit(3);
  311. }
  312. const app = await Spectrum({
  313. projectId,
  314. projectSecret,
  315. providers: [imessage.config()],
  316. options: { flattenGroups: true },
  317. telemetry,
  318. });
  319. // Effect-name → native effect id map. Optional chaining: an SDK build
  320. // without the iMessage effect surface (or a test stub) must not crash the
  321. // sidecar at import — /send-effect then rejects with "unsupported effect".
  322. const MESSAGE_EFFECTS = imessage?.effect?.message || {};
  323. // ---------------------------------------------------------------------------
  324. // Inbound: forward `app.messages` (gRPC stream) to the Python consumer.
  325. // At most one Python consumer is attached at a time (the gateway adapter).
  326. let consumerRes = null;
  327. let consumerWaiters = [];
  328. const knownSpaces = new Map();
  329. // Inbound Message objects by id, so /react can usually skip a
  330. // `space.getMessage` round trip when tapping back on a recent message.
  331. const knownMessages = new Map();
  332. // One reaction handle per reacted-to message (key `${spaceId}\0${messageId}`,
  333. // value {emoji, handle}) — mirrors iMessage's one-tapback-per-sender
  334. // semantics; a new /react on the same target overwrites the slot. The handle
  335. // is the outbound reaction Message returned by `target.react()`, kept so
  336. // /unreact can `unsend()` it later.
  337. const reactionHandles = new Map();
  338. function lruSet(map, key, value, cap) {
  339. if (map.has(key)) map.delete(key);
  340. map.set(key, value);
  341. if (map.size > cap) {
  342. const oldest = map.keys().next().value;
  343. if (oldest !== undefined) map.delete(oldest);
  344. }
  345. }
  346. function rememberKnownSpace(id, space) {
  347. if (!id || typeof id !== "string" || !space) return;
  348. lruSet(knownSpaces, id, space, MAX_KNOWN_SPACES);
  349. }
  350. function rememberKnownMessage(message) {
  351. const id = message?.id;
  352. if (!id || typeof id !== "string") return;
  353. lruSet(knownMessages, id, message, MAX_KNOWN_MESSAGES);
  354. }
  355. function phoneTargetFromSpaceId(spaceId) {
  356. if (typeof spaceId !== "string") return null;
  357. if (E164_RE.test(spaceId)) return spaceId;
  358. const dmGuid = spaceId.match(DM_CHAT_GUID_RE);
  359. return dmGuid ? dmGuid[1] : null;
  360. }
  361. function rememberInboundSpace(space, message) {
  362. const msgSpace = message?.space || {};
  363. const ids = [space?.id, msgSpace.id];
  364. for (const id of ids) {
  365. rememberKnownSpace(id, space);
  366. const phone = phoneTargetFromSpaceId(id);
  367. if (phone) rememberKnownSpace(phone, space);
  368. }
  369. }
  370. function waitForConsumer() {
  371. if (consumerRes) return Promise.resolve();
  372. return new Promise((resolve) => consumerWaiters.push(resolve));
  373. }
  374. function setConsumer(res) {
  375. consumerRes = res;
  376. const waiters = consumerWaiters;
  377. consumerWaiters = [];
  378. for (const resolve of waiters) resolve();
  379. }
  380. function clearConsumer(res) {
  381. if (consumerRes === res) consumerRes = null;
  382. }
  383. // Write one NDJSON line to the active consumer. Blocks until a consumer is
  384. // connected; if the write fails (consumer vanished mid-flight) we wait for a
  385. // new consumer and retry, so a message is never silently dropped here.
  386. async function deliver(line) {
  387. for (;;) {
  388. await waitForConsumer();
  389. const res = consumerRes;
  390. if (!res) continue;
  391. try {
  392. const flushed = res.write(line + "\n");
  393. if (!flushed) await once(res, "drain");
  394. return;
  395. } catch {
  396. clearConsumer(res);
  397. }
  398. }
  399. }
  400. async function normalizeBinaryContent(content) {
  401. const meta = {
  402. type: content.type,
  403. id: content.id ?? null,
  404. name: content.name ?? null,
  405. mimeType: content.mimeType ?? null,
  406. size: typeof content.size === "number" ? content.size : null,
  407. };
  408. if (content.type === "voice" && typeof content.duration === "number") {
  409. meta.duration = content.duration;
  410. }
  411. // Read the bytes eagerly and base64-inline them as `data` so the Python
  412. // adapter can cache the real file (the agent then sees images and can run
  413. // STT on voice notes). Spectrum content objects may not outlive this stream
  414. // iteration, so a lazy/on-demand fetch isn't safe. Over-cap content (when
  415. // size is known up front) is forwarded as metadata only and the adapter falls
  416. // back to a text marker. A read failure must never break the inbound loop.
  417. const label = `${content.type} ${meta.name ?? meta.id ?? "(unnamed)"}`;
  418. if (meta.size !== null && meta.size > MAX_INLINE_ATTACHMENT_BYTES) {
  419. console.error(
  420. `photon-sidecar: ${label} (${meta.size} bytes) ` +
  421. `exceeds inline cap ${MAX_INLINE_ATTACHMENT_BYTES}; forwarding metadata only`
  422. );
  423. return meta;
  424. }
  425. if (typeof content.read === "function") {
  426. try {
  427. const buf = await content.read();
  428. // Guard the case where size was unknown but the bytes turn out to be
  429. // over the cap.
  430. if (buf && buf.length > MAX_INLINE_ATTACHMENT_BYTES) {
  431. console.error(
  432. `photon-sidecar: ${label} (${buf.length} bytes) ` +
  433. `exceeds inline cap after read; forwarding metadata only`
  434. );
  435. return meta;
  436. }
  437. meta.data = Buffer.from(buf).toString("base64");
  438. meta.encoding = "base64";
  439. } catch (e) {
  440. console.error(
  441. `photon-sidecar: failed to read ${content.type} bytes ` +
  442. "(forwarding metadata only): " +
  443. (e && e.stack ? e.stack : String(e))
  444. );
  445. }
  446. }
  447. return meta;
  448. }
  449. // Best-effort text preview of a reaction's resolved target Message, so the
  450. // Python adapter can populate the gateway's `reply_to_text` (context: WHAT was
  451. // tapped back). The SDK only emits a reaction once it has resolved the full
  452. // target Message (toReactionMessages bails otherwise), so `target.content` is
  453. // hydrated here — no extra round trip. Handles plain text and our patched mixed
  454. // text+attachment groups (first text child); null for attachment/voice-only
  455. // targets. Capped so one long bubble can't balloon the NDJSON line.
  456. const REACTION_TARGET_TEXT_CAP = 2000;
  457. function reactionTargetText(target) {
  458. const c = target && typeof target === "object" ? target.content : null;
  459. if (!c || typeof c !== "object") return null;
  460. let text = null;
  461. if (c.type === "text") {
  462. text = c.text;
  463. } else if (c.type === "richlink") {
  464. text = c.url;
  465. } else if (c.type === "group") {
  466. for (const item of Array.isArray(c.items) ? c.items : []) {
  467. const ic = item && typeof item === "object" ? item.content : null;
  468. if (ic && ic.type === "text" && ic.text) {
  469. text = ic.text;
  470. break;
  471. }
  472. if (ic && ic.type === "richlink" && ic.url) {
  473. text = ic.url;
  474. break;
  475. }
  476. }
  477. }
  478. if (typeof text !== "string" || !text) return null;
  479. return text.length > REACTION_TARGET_TEXT_CAP
  480. ? text.slice(0, REACTION_TARGET_TEXT_CAP)
  481. : text;
  482. }
  483. async function normalizeContent(content) {
  484. if (!content || typeof content !== "object") {
  485. return { type: "unknown" };
  486. }
  487. if (content.type === "text") {
  488. return { type: "text", text: content.text || "" };
  489. }
  490. if (content.type === "richlink") {
  491. const out = { type: "richlink", url: content.url || "" };
  492. if (typeof content.title === "string") {
  493. out.title = content.title;
  494. }
  495. if (typeof content.summary === "string") {
  496. out.summary = content.summary;
  497. }
  498. return out;
  499. }
  500. if (content.type === "attachment" || content.type === "voice") {
  501. return await normalizeBinaryContent(content);
  502. }
  503. if (content.type === "group") {
  504. const items = [];
  505. for (const item of Array.isArray(content.items) ? content.items : []) {
  506. items.push({
  507. id: item && typeof item === "object" ? item.id ?? null : null,
  508. content: await normalizeContent(item?.content),
  509. });
  510. }
  511. return { type: "group", items };
  512. }
  513. if (content.type === "read") {
  514. // spectrum-ts v12.5+ surfaces an inbound read receipt only after it has
  515. // verified that the target is one of our outbound messages. Keep the
  516. // receipt lightweight: Python records it as telemetry, never as an agent
  517. // prompt.
  518. return {
  519. type: "read",
  520. targetMessageId: content.target?.id ?? null,
  521. targetDirection: content.target?.direction ?? null,
  522. };
  523. }
  524. if (content.type === "reaction") {
  525. const target = content.target;
  526. return {
  527. type: "reaction",
  528. emoji: content.emoji || "",
  529. targetMessageId: target?.id ?? null,
  530. // Lets Python gate "is this a reaction to one of MY messages" without
  531. // tracking every outbound id. May be null if the provider doesn't
  532. // hydrate the target — Python falls back to its own sent-id cache.
  533. targetDirection: target?.direction ?? null,
  534. // Text of the reacted-to message, so Python can correlate the tapback to
  535. // the gateway's reply_to_text. Null for attachment/voice-only targets.
  536. targetText: reactionTargetText(target),
  537. };
  538. }
  539. // iMessage threaded (swipe) reply: spectrum 12.x wraps it as
  540. // {type: "reply", content: <inner Content>, target: <Message>}. Normalise the
  541. // inner content with the normal ladder and carry a light pointer to the
  542. // quoted message, so Python can unwrap it instead of dropping the user's
  543. // words as "content type not handled" (#100663).
  544. if (content.type === "reply") {
  545. const target = content.target;
  546. return {
  547. type: "reply",
  548. content:
  549. content.content && typeof content.content === "object"
  550. ? await normalizeContent(content.content)
  551. : { type: "unknown" },
  552. targetMessageId: target?.id ?? null,
  553. targetDirection: target?.direction ?? null,
  554. targetText: reactionTargetText(target),
  555. };
  556. }
  557. // A user tapping a poll choice arrives as `poll_option` carrying the chosen
  558. // option title + whether it was selected (true) or deselected (false). This
  559. // is how a native iMessage poll's vote streams back — Python turns a
  560. // selection into the answer that resolves a pending `clarify`.
  561. if (content.type === "poll_option") {
  562. return {
  563. type: "poll_option",
  564. title: content.option?.title ?? content.title ?? "",
  565. selected: content.selected !== false,
  566. pollTitle: content.poll?.title ?? null,
  567. };
  568. }
  569. // The poll message itself (its creation) — surfaced for completeness so the
  570. // agent isn't told "content type not handled" if it sees the echo.
  571. if (content.type === "poll") {
  572. return {
  573. type: "poll",
  574. title: content.title ?? "",
  575. options: Array.isArray(content.options)
  576. ? content.options.map((o) => o?.title ?? "")
  577. : [],
  578. };
  579. }
  580. return { type: content.type || "unknown" };
  581. }
  582. // The iMessage SDK exposes `message.read()` for inbound messages. Mark after
  583. // the event has crossed the sidecar boundary: this means the gateway has
  584. // actually received it, while a transient agent/tool delay does not leave the
  585. // sender staring at Delivered. Receipt events themselves must never recurse.
  586. const readReceiptsEnabled =
  587. (process.env.PHOTON_READ_RECEIPTS || "true").trim().toLowerCase() !==
  588. "false";
  589. async function acknowledgeInboundRead(message) {
  590. if (!readReceiptsEnabled) return;
  591. if (message?.content?.type === "read") return;
  592. if (typeof message?.read !== "function") return;
  593. try {
  594. await message.read();
  595. } catch (error) {
  596. // Read receipts are presence polish, not a delivery dependency.
  597. console.warn(
  598. "photon-sidecar: failed to mark inbound message read: " +
  599. (error?.message || String(error))
  600. );
  601. }
  602. }
  603. async function normalizeEvent(space, message) {
  604. try {
  605. const msgSpace = message.space || {};
  606. const ts = message.timestamp;
  607. return {
  608. messageId: message.id ?? null,
  609. platform: message.platform || space.__platform || "iMessage",
  610. space: {
  611. id: space.id ?? msgSpace.id ?? null,
  612. // iMessage spaces carry `type` ("dm"|"group") and `phone` directly.
  613. type: space.type ?? msgSpace.type ?? "dm",
  614. phone: space.phone ?? msgSpace.phone ?? null,
  615. },
  616. sender: { id: message.sender ? message.sender.id : null },
  617. content: await normalizeContent(message.content),
  618. timestamp:
  619. ts instanceof Date ? ts.toISOString() : ts ? String(ts) : null,
  620. };
  621. } catch (e) {
  622. console.error(
  623. "photon-sidecar: failed to normalize inbound message: " + String(e)
  624. );
  625. return null;
  626. }
  627. }
  628. function inboundStreamErrorMessage(e) {
  629. const msg = e && e.message ? e.message : String(e);
  630. let out = "photon-sidecar: inbound stream errored — restarting: " + msg;
  631. // The Spectrum SDK surfaces Photon cloud CatchUpEvents failures as an
  632. // iMessage internal error. Local Hermes allowlists cannot cause or fix this:
  633. // inbound messages stop before they reach the gateway. Add an explicit hint
  634. // so operators know to retry/restart or escalate to Photon support instead
  635. // of chasing PHOTON_ALLOWED_USERS / pairing configuration.
  636. const details = String(e?.cause?.details || e?.details || "");
  637. const path = String(e?.cause?.path || e?.path || "");
  638. const code = String(e?.code || "");
  639. if (
  640. path.includes("EventService/CatchUpEvents") ||
  641. details.includes("Unknown server error occurred") ||
  642. (code === "internalError" && msg.includes("Unknown server error"))
  643. ) {
  644. out +=
  645. " | Photon Spectrum CatchUpEvents returned an internal server error; " +
  646. "this is upstream of Hermes, so inbound iMessages may not be delivered " +
  647. "until Photon recovers or the stream is re-established.";
  648. }
  649. return out;
  650. }
  651. // spectrum-ts handles in-session gRPC reconnects internally, but if the async
  652. // iterator itself throws or ends, this consumer would stop forever. Wrap it in
  653. // a re-subscribe loop with capped exponential backoff + jitter so inbound
  654. // always recovers (the adapter dedupes any catch-up replay).
  655. (async () => {
  656. let backoff = 1000;
  657. for (;;) {
  658. try {
  659. for await (const [space, message] of app.messages) {
  660. backoff = 1000; // healthy traffic — reset
  661. markStreamHealthy();
  662. // Every yield — any direction — proves the inbound stream is live.
  663. noteInboundYield();
  664. // Only forward inbound messages (ignore our own outbound echoes).
  665. if (message && message.direction && message.direction !== "inbound") {
  666. continue;
  667. }
  668. rememberInboundSpace(space, message);
  669. rememberKnownMessage(message);
  670. const event = await normalizeEvent(space, message);
  671. if (!event) continue;
  672. await deliver(JSON.stringify(event));
  673. await acknowledgeInboundRead(message);
  674. }
  675. console.error("photon-sidecar: inbound stream ended — re-subscribing");
  676. markStreamRecovering("inbound stream ended");
  677. } catch (e) {
  678. const reason = e && e.message ? e.message : String(e);
  679. console.error(inboundStreamErrorMessage(e));
  680. markStreamRecovering(reason);
  681. }
  682. await new Promise((r) =>
  683. setTimeout(r, backoff + Math.random() * backoff * 0.2)
  684. );
  685. backoff = Math.min(backoff * 2, 30000);
  686. }
  687. })();
  688. // ---------------------------------------------------------------------------
  689. // Zombie-stream watchdog: detect a half-open gRPC stream the SDK can't see.
  690. //
  691. // The inbound iterator above can hang forever on a half-open socket — no
  692. // error, no end — so the re-subscribe loop never fires and classifyStreamLog
  693. // never sees a "[spectrum.stream]" line. We track the iterator's last yield
  694. // (noteInboundYield) and, once it has been silent past
  695. // STREAM_SILENCE_PROBE_MS, drive a cheap unary read (space.getMessage on a
  696. // synthetic id) over the same authenticated channel. Decision rules (see
  697. // stream-staleness.mjs):
  698. // probe proves connectivity while the stream is silent -> the stream itself
  699. // is the dead part -> markStreamDegraded -> existing exit-75 restart path.
  700. // probe inconclusive (rejected/hung) -> do NOTHING: the network may just be
  701. // down, and in that case the iterator eventually throws and the
  702. // re-subscribe loop recovers on its own. Never restart on silence alone —
  703. // shared lines can be legitimately quiet for hours.
  704. async function probeUpstream() {
  705. if (typeof app?.stop !== "function") {
  706. return { alive: false, hung: false, reason: "spectrum app not constructed" };
  707. }
  708. const probeId = createProbeMessageId();
  709. let timer = null;
  710. const timeout = new Promise((resolve) => {
  711. timer = setTimeout(
  712. () => resolve({ alive: false, hung: true, reason: "probe timed out" }),
  713. STREAM_PROBE_TIMEOUT_MS
  714. );
  715. timer.unref();
  716. });
  717. const attempt = (async () => {
  718. try {
  719. const im = imessage(app);
  720. const space = await im.space.get(PROBE_SPACE_ID);
  721. await space.getMessage(probeId);
  722. // Resolving for a synthetic id is unexpected but is still a completed
  723. // round-trip: the channel is alive.
  724. return { alive: true, hung: false, reason: "round-trip completed" };
  725. } catch (e) {
  726. const verdict = classifyProbeRejection(e);
  727. return { alive: verdict.alive, hung: false, reason: verdict.reason };
  728. }
  729. })();
  730. const outcome = await Promise.race([attempt, timeout]);
  731. if (timer) clearTimeout(timer);
  732. staleness.lastProbeAt = Date.now();
  733. staleness.lastProbeOutcome = outcome.alive ? "alive" : "inconclusive";
  734. return outcome;
  735. }
  736. let watchdogProbeInFlight = false;
  737. async function zombieWatchdogTick() {
  738. if (watchdogProbeInFlight) return;
  739. const now = Date.now();
  740. const silentForMs = now - staleness.lastInboundAt;
  741. if (
  742. !shouldProbe(
  743. silentForMs,
  744. STREAM_SILENCE_PROBE_MS,
  745. now - staleness.lastProbeAt,
  746. STREAM_PROBE_COOLDOWN_MS
  747. )
  748. ) {
  749. return;
  750. }
  751. watchdogProbeInFlight = true;
  752. try {
  753. const outcome = await probeUpstream();
  754. if (isZombieSuspect(silentForMs, STREAM_SILENCE_PROBE_MS, outcome)) {
  755. staleness.zombieSuspected = true;
  756. const reason =
  757. `inbound stream silent for ${silentForMs}ms while an upstream probe ` +
  758. "succeeded — half-open (zombie) gRPC stream suspected";
  759. console.error("photon-sidecar: " + reason);
  760. markStreamDegraded(reason);
  761. }
  762. // Inconclusive: deliberately no action (see block comment above).
  763. } catch (e) {
  764. console.error(
  765. "photon-sidecar: zombie watchdog tick failed: " +
  766. (e && e.message ? e.message : String(e))
  767. );
  768. } finally {
  769. watchdogProbeInFlight = false;
  770. }
  771. }
  772. if (STREAM_SILENCE_PROBE_MS > 0) {
  773. const watchdogTimer = setInterval(zombieWatchdogTick, STREAM_WATCHDOG_TICK_MS);
  774. watchdogTimer.unref();
  775. }
  776. // ---------------------------------------------------------------------------
  777. // HTTP control + inbound server (loopback only).
  778. // Control-message bodies are tiny; cap the body so a compromised local peer
  779. // can't OOM the sidecar by streaming an unbounded request (defence-in-depth on
  780. // the loopback channel).
  781. const MAX_BODY_BYTES = 2 * 1024 * 1024; // 2 MiB
  782. async function readBody(req) {
  783. const chunks = [];
  784. let size = 0;
  785. for await (const chunk of req) {
  786. size += chunk.length;
  787. if (size > MAX_BODY_BYTES) {
  788. req.destroy();
  789. throw new Error("request body too large");
  790. }
  791. chunks.push(chunk);
  792. }
  793. const raw = Buffer.concat(chunks).toString("utf-8");
  794. if (!raw) return {};
  795. try {
  796. return JSON.parse(raw);
  797. } catch (e) {
  798. throw new Error("invalid JSON body");
  799. }
  800. }
  801. function unauthorized(res) {
  802. res.statusCode = 401;
  803. res.setHeader("Content-Type", "application/json");
  804. res.end(JSON.stringify({ ok: false, error: "unauthorized" }));
  805. }
  806. function badRequest(res, msg) {
  807. res.statusCode = 400;
  808. res.setHeader("Content-Type", "application/json");
  809. res.end(JSON.stringify({ ok: false, error: msg }));
  810. }
  811. function classifySidecarError(err) {
  812. const message = String(err && err.message ? err.message : err || "");
  813. const lowered = message.toLowerCase();
  814. // Spectrum raises AuthenticationError("Target not allowed for this
  815. // project") from space.send when a shared/free-tier line tries to
  816. // initiate an outbound conversation with a new target. That is a plan
  817. // limitation, not a transient fault — surface a dedicated class so the
  818. // adapter can explain it instead of retrying (issues #50971/#51897).
  819. if (lowered.includes("target not allowed")) {
  820. return { errorClass: "target_not_allowed", retryable: false };
  821. }
  822. if (
  823. lowered.includes("unauthorized") ||
  824. lowered.includes("forbidden") ||
  825. lowered.includes("permission") ||
  826. lowered.includes("401") ||
  827. lowered.includes("403") ||
  828. lowered.includes("invalid token") ||
  829. lowered.includes("project secret") ||
  830. lowered.includes("unable to resolve space id")
  831. ) {
  832. return { errorClass: "auth_or_config", retryable: false };
  833. }
  834. if (
  835. lowered.includes("timeout") ||
  836. lowered.includes("timed out") ||
  837. lowered.includes("econnreset") ||
  838. lowered.includes("econnrefused") ||
  839. lowered.includes("socket hang up") ||
  840. lowered.includes("fetch failed") ||
  841. lowered.includes("unavailable") ||
  842. lowered.includes("upstream connect") ||
  843. lowered.includes("reset reason") ||
  844. lowered.includes("overflow") ||
  845. lowered.includes("temporarily") ||
  846. lowered.includes("429")
  847. ) {
  848. return { errorClass: "upstream_transient", retryable: true };
  849. }
  850. return { errorClass: "sidecar_internal", retryable: false };
  851. }
  852. function serverError(res, err) {
  853. res.statusCode = 500;
  854. res.setHeader("Content-Type", "application/json");
  855. const classified = classifySidecarError(err);
  856. // Don't leak stack traces or raw exception text to the caller — even
  857. // though we listen on loopback, the supervisor logs the real error. The
  858. // Python adapter only needs a safe class plus retryability.
  859. res.end(JSON.stringify({
  860. ok: false,
  861. error: "internal sidecar error",
  862. error_class: classified.errorClass,
  863. retryable: classified.retryable,
  864. }));
  865. }
  866. function ok(res, data) {
  867. res.statusCode = 200;
  868. res.setHeader("Content-Type", "application/json");
  869. res.end(JSON.stringify({ ok: true, ...data }));
  870. }
  871. function handleInbound(req, res) {
  872. res.statusCode = 200;
  873. res.setHeader("Content-Type", "application/x-ndjson");
  874. res.setHeader("Cache-Control", "no-store");
  875. res.setHeader("Connection", "keep-alive");
  876. // One consumer at a time — a fresh connection (e.g. after a reconnect)
  877. // supersedes the previous one.
  878. if (consumerRes && consumerRes !== res) {
  879. try {
  880. consumerRes.end();
  881. } catch {
  882. /* ignore */
  883. }
  884. }
  885. setConsumer(res);
  886. // Heartbeat keeps the socket warm through idle periods and lets the Python
  887. // side detect a dead pipe promptly.
  888. const heartbeat = setInterval(() => {
  889. try {
  890. res.write("\n");
  891. } catch {
  892. /* ignore */
  893. }
  894. }, 25000);
  895. const cleanup = () => {
  896. clearInterval(heartbeat);
  897. clearConsumer(res);
  898. };
  899. req.on("close", cleanup);
  900. req.on("aborted", cleanup);
  901. res.on("error", cleanup);
  902. }
  903. async function resolveSpace(spaceId) {
  904. const cached = knownSpaces.get(spaceId);
  905. if (cached) return cached;
  906. const im = imessage(app);
  907. const phoneTarget = phoneTargetFromSpaceId(spaceId);
  908. let space = null;
  909. // A bare E.164 phone number addresses a DM, so callers can pass just
  910. // "+1..." (e.g. PHOTON_HOME_CHANNEL for cron delivery) instead of an opaque
  911. // inbound space id. Photon also represents DM chat ids as `any;-;+1...`;
  912. // normalize those through the same path. `space.create` accepts the raw
  913. // phone string directly.
  914. if (phoneTarget) {
  915. try {
  916. space = await im.space.create(phoneTarget);
  917. } catch (e) {
  918. console.error(
  919. "photon-sidecar: phone->DM space.create failed: " +
  920. (e && e.stack ? e.stack : String(e))
  921. );
  922. }
  923. }
  924. // Anything else — typically an opaque group GUID — is rehydrated from the
  925. // persisted id via `space.get`, so group spaces stay reachable after a
  926. // sidecar restart even before any fresh inbound message in that group.
  927. if (!space) {
  928. try {
  929. space = await im.space.get(spaceId);
  930. } catch (e) {
  931. console.error(
  932. "photon-sidecar: space.get failed: " +
  933. (e && e.stack ? e.stack : String(e))
  934. );
  935. }
  936. }
  937. if (!space) throw new Error(`unable to resolve space id ${spaceId}`);
  938. rememberKnownSpace(spaceId, space);
  939. if (phoneTarget) rememberKnownSpace(phoneTarget, space);
  940. rememberKnownSpace(space?.id, space);
  941. return space;
  942. }
  943. // Constant-time token comparison — don't leak the token via `!==` timing.
  944. const _tokenBuf = Buffer.from(sharedToken);
  945. function tokenOk(header) {
  946. if (typeof header !== "string") return false;
  947. const h = Buffer.from(header);
  948. return h.length === _tokenBuf.length && crypto.timingSafeEqual(h, _tokenBuf);
  949. }
  950. function isHttpUrl(value) {
  951. if (typeof value !== "string" || !value.trim()) return false;
  952. try {
  953. const parsed = new URL(value.trim());
  954. return parsed.protocol === "http:" || parsed.protocol === "https:";
  955. } catch {
  956. return false;
  957. }
  958. }
  959. const server = http.createServer(async (req, res) => {
  960. if (!tokenOk(req.headers["x-hermes-sidecar-token"])) {
  961. return unauthorized(res);
  962. }
  963. // Long-lived inbound NDJSON stream.
  964. if (req.method === "GET" && req.url === "/inbound") {
  965. return handleInbound(req, res);
  966. }
  967. if (req.method !== "POST") {
  968. res.statusCode = 405;
  969. return res.end();
  970. }
  971. try {
  972. if (req.url === "/healthz") {
  973. return ok(res, { stream: streamHealthSnapshot() });
  974. }
  975. if (req.url === "/probe") {
  976. // Upstream liveness probe. Drives a cheap unary read over the SAME gRPC
  977. // channel the inbound stream uses. STRICT semantics: only a completed
  978. // round-trip (resolution, or a not-found rejection for our synthetic
  979. // id) counts as alive; any other rejection or a timeout is
  980. // INCONCLUSIVE — never reported as alive.
  981. const outcome = await probeUpstream();
  982. if (outcome.alive) {
  983. return ok(res, { alive: true, outcome: "alive" });
  984. }
  985. res.statusCode = 503;
  986. res.setHeader("Content-Type", "application/json");
  987. return res.end(
  988. JSON.stringify({
  989. ok: false,
  990. alive: false,
  991. outcome: outcome.hung ? "hung" : "inconclusive",
  992. reason: outcome.reason,
  993. })
  994. );
  995. }
  996. if (req.url === "/shutdown") {
  997. ok(res, {});
  998. setTimeout(() => process.kill(process.pid, "SIGTERM"), 50);
  999. return;
  1000. }
  1001. const body = await readBody(req);
  1002. if (req.url === "/send") {
  1003. const { spaceId, text, format = "text" } = body || {};
  1004. if (!spaceId || typeof text !== "string") {
  1005. return badRequest(res, "spaceId and text are required");
  1006. }
  1007. if (format !== "text" && format !== "markdown") {
  1008. return badRequest(res, "format must be text or markdown");
  1009. }
  1010. const space = await resolveSpace(spaceId);
  1011. // iMessage renders markdown natively; spectrum-ts degrades it to
  1012. // readable plain text on platforms that don't.
  1013. // spectrumMarkdown() enables enableDataDetection in the underlying
  1014. // iMessage API, which can 500 on messages containing raw URLs.
  1015. // Plain-text URLs are auto-linked by iMessage, so route markdown
  1016. // messages that contain URLs through spectrumText while preserving
  1017. // spectrumMarkdown for URL-free markdown. The decision lives in
  1018. // send-format.mjs so tests can exercise it directly.
  1019. const builder =
  1020. chooseSendFormat(format, text) === "markdown"
  1021. ? spectrumMarkdown(text)
  1022. : spectrumText(text);
  1023. const result = await space.send(builder);
  1024. return ok(res, { messageId: result?.id || null });
  1025. }
  1026. if (req.url === "/send-richlink") {
  1027. const { spaceId, url } = body || {};
  1028. if (!spaceId || !isHttpUrl(url)) {
  1029. return badRequest(res, "spaceId and http(s) url are required");
  1030. }
  1031. const space = await resolveSpace(spaceId);
  1032. const result = await space.send(spectrumRichlink(url.trim()));
  1033. return ok(res, { messageId: result?.id || null });
  1034. }
  1035. if (req.url === "/send-attachment") {
  1036. const { spaceId, path, name, mimeType, caption, kind } =
  1037. body || {};
  1038. if (!spaceId || typeof path !== "string" || !path) {
  1039. return badRequest(res, "spaceId and path are required");
  1040. }
  1041. const space = await resolveSpace(spaceId);
  1042. // spectrum-ts infers name + MIME from the file extension; pass
  1043. // overrides only when Hermes supplied them so a known-good
  1044. // inference isn't clobbered with an empty string.
  1045. const opts = {};
  1046. if (name) opts.name = name;
  1047. if (mimeType) opts.mimeType = mimeType;
  1048. const builder =
  1049. kind === "voice"
  1050. ? voice(path, Object.keys(opts).length ? opts : undefined)
  1051. : attachment(path, Object.keys(opts).length ? opts : undefined);
  1052. const result = await space.send(builder);
  1053. // iMessage delivers the caption as a separate bubble; send it
  1054. // after the media so the attachment renders first.
  1055. if (caption && typeof caption === "string") {
  1056. try {
  1057. await space.send(spectrumText(caption));
  1058. } catch (e) {
  1059. console.error(
  1060. "photon-sidecar: attachment sent but caption failed: " +
  1061. (e && e.stack ? e.stack : String(e))
  1062. );
  1063. }
  1064. }
  1065. return ok(res, { messageId: result?.id || null });
  1066. }
  1067. if (req.url === "/react") {
  1068. const { spaceId, messageId, emoji } = body || {};
  1069. if (!spaceId || !messageId || typeof emoji !== "string" || !emoji) {
  1070. return badRequest(res, "spaceId, messageId and emoji are required");
  1071. }
  1072. const space = await resolveSpace(spaceId);
  1073. const target =
  1074. knownMessages.get(messageId) ?? (await space.getMessage(messageId));
  1075. if (!target) {
  1076. return badRequest(res, "message not found");
  1077. }
  1078. const handle = await target.react(emoji);
  1079. if (!handle) {
  1080. return badRequest(res, "reactions not supported on this platform");
  1081. }
  1082. lruSet(
  1083. reactionHandles,
  1084. `${spaceId}\u0000${messageId}`,
  1085. { emoji, handle },
  1086. MAX_REACTION_HANDLES
  1087. );
  1088. return ok(res, { reactionId: handle.id ?? null });
  1089. }
  1090. if (req.url === "/unreact") {
  1091. const { spaceId, messageId, reactionId } = body || {};
  1092. if (!spaceId || !messageId) {
  1093. return badRequest(res, "spaceId and messageId are required");
  1094. }
  1095. const key = `${spaceId}\u0000${messageId}`;
  1096. const slot = reactionHandles.get(key);
  1097. if (slot) {
  1098. await slot.handle.unsend();
  1099. reactionHandles.delete(key);
  1100. return ok(res, {});
  1101. }
  1102. // Restart-recovery: the live handle is gone, so try rehydrating the
  1103. // reaction message by id and retracting it. Only outbound messages can
  1104. // be unsent — if the provider rehydrates it as inbound (or not at all)
  1105. // this throws, and that's an expected soft failure, not a sidecar bug:
  1106. // a stale tapback self-heals when the next /react replaces it.
  1107. if (reactionId) {
  1108. try {
  1109. const space = await resolveSpace(spaceId);
  1110. const msg = await space.getMessage(reactionId);
  1111. if (msg) {
  1112. await space.unsend(msg);
  1113. return ok(res, {});
  1114. }
  1115. } catch (e) {
  1116. console.error(
  1117. "photon-sidecar: best-effort unreact failed: " +
  1118. (e && e.message ? e.message : String(e))
  1119. );
  1120. }
  1121. return badRequest(res, "reaction not removable");
  1122. }
  1123. return badRequest(res, "no tracked reaction for message");
  1124. }
  1125. if (req.url === "/send-poll") {
  1126. const { spaceId, title, options } = body || {};
  1127. const choices = Array.isArray(options)
  1128. ? options.map((option) => String(option || "").trim()).filter(Boolean)
  1129. : [];
  1130. if (!spaceId || typeof title !== "string" || !title.trim()) {
  1131. return badRequest(res, "spaceId and title are required");
  1132. }
  1133. if (choices.length < 2) {
  1134. return badRequest(res, "options must contain at least two choices");
  1135. }
  1136. const space = await resolveSpace(spaceId);
  1137. const result = await space.send(spectrumPoll(title.trim(), choices));
  1138. return ok(res, { messageId: result?.id || null });
  1139. }
  1140. if (req.url === "/send-effect") {
  1141. const { spaceId, text, effect } = body || {};
  1142. const effectName = String(effect || "").trim();
  1143. const effectId = MESSAGE_EFFECTS[effectName];
  1144. if (!spaceId || typeof text !== "string" || !text.trim()) {
  1145. return badRequest(res, "spaceId and text are required");
  1146. }
  1147. if (!effectId) {
  1148. return badRequest(res, "unsupported effect");
  1149. }
  1150. const space = await resolveSpace(spaceId);
  1151. const result = await space.send(
  1152. imessageEffect(spectrumText(text.trim()), effectId)
  1153. );
  1154. return ok(res, { messageId: result?.id || null });
  1155. }
  1156. if (req.url === "/typing") {
  1157. const { spaceId, state = "start" } = body || {};
  1158. if (!spaceId) return badRequest(res, "spaceId is required");
  1159. if (state !== "start" && state !== "stop") {
  1160. return badRequest(res, "state must be start or stop");
  1161. }
  1162. const space = await resolveSpace(spaceId);
  1163. await space.send(spectrumTyping(state));
  1164. return ok(res, {});
  1165. }
  1166. res.statusCode = 404;
  1167. res.setHeader("Content-Type", "application/json");
  1168. return res.end(JSON.stringify({ ok: false, error: "not found" }));
  1169. } catch (e) {
  1170. console.error(
  1171. "photon-sidecar: handler error: " +
  1172. (e && e.stack ? e.stack : String(e))
  1173. );
  1174. // serverError() intentionally returns a generic message — see its
  1175. // body for the rationale.
  1176. return serverError(res, e);
  1177. }
  1178. });
  1179. server.listen(port, bind, () => {
  1180. console.error(`photon-sidecar: listening on ${bind}:${port}`);
  1181. });
  1182. let stopping = false;
  1183. async function shutdown(signal) {
  1184. // Re-entry guard: stdin EOF, a signal and /shutdown can all fire together
  1185. // during one teardown.
  1186. if (stopping) return;
  1187. stopping = true;
  1188. console.error(`photon-sidecar: received ${signal}, stopping...`);
  1189. try {
  1190. await Promise.race([
  1191. app.stop(),
  1192. new Promise((resolve) => setTimeout(resolve, 3000)),
  1193. ]);
  1194. } catch (e) {
  1195. console.error("photon-sidecar: app.stop() failed: " + String(e));
  1196. }
  1197. server.close(() => process.exit(0));
  1198. setTimeout(() => process.exit(1), 500).unref();
  1199. }
  1200. process.on("SIGINT", () => shutdown("SIGINT"));
  1201. process.on("SIGTERM", () => shutdown("SIGTERM"));
  1202. // Lifetime binding to the parent. The adapter spawns us with stdin as a pipe
  1203. // it holds open; EOF means the gateway process is gone — including hard
  1204. // deaths (crash, SIGKILL) where no signal and no /shutdown ever reaches us.
  1205. // Without this, an orphaned sidecar squats the port and keeps consuming the
  1206. // inbound gRPC stream, and every replacement spawn dies on EADDRINUSE.
  1207. // Opt-in via env so manual `node index.mjs` runs aren't affected.
  1208. if (process.env.PHOTON_SIDECAR_WATCH_STDIN === "1") {
  1209. process.stdin.resume();
  1210. process.stdin.on("end", () => shutdown("stdin EOF (parent exited)"));
  1211. process.stdin.on("error", () => shutdown("stdin error (parent exited)"));
  1212. }
  1213. // Don't let a stray promise rejection take the process down silently — handlers
  1214. // catch their own errors, so log and keep serving (Python supervises restart on
  1215. // a real fatal exit).
  1216. process.on("unhandledRejection", (reason) => {
  1217. console.error(
  1218. "photon-sidecar: unhandledRejection: " +
  1219. (reason && reason.stack ? reason.stack : String(reason))
  1220. );
  1221. });