feat(photon): render multiple-choice clarify as a native iMessage poll

[vaibhavjnf]

Summary

On Photon/iMessage, the clarify tool's multiple-choice prompts flattened to a numbered text list — even though iMessage has a native poll bubble and spectrum-ts already exposes it via the poll() content builder. This wires clarify choices to a native iMessage poll: the user taps a choice and the vote resolves the clarify.

Root cause

Two gaps, both directions:

Direction	Before
Outbound	Sidecar had only /send (text). No way to send a poll → base adapter's numbered-text fallback was used.
Inbound	normalizeContent() handled only text/attachment/voice. A poll vote arrived as poll_option and was dropped — surfaced as [Photon content type not handled: poll_option] — so the clarify never resolved.

Reproduced live: sending a poll() to a DM rendered the native bubble; tapping a choice produced exactly the poll_option "content type not handled" marker, and the pending clarify hung to timeout.

Fix (end to end, edge-only)

Sidecar (sidecar/index.mjs)

• import poll from spectrum-ts
• add POST /send-poll → space.send(poll(title, ...options))
• serialize inbound poll_option (vote: chosen title + selected bool) and poll content in normalizeContent()

Adapter (adapter.py)

• override send_clarify: for choices, send a native poll via _sidecar_send_poll and call mark_awaiting_text so the existing pending-clarify text-intercept resolves it; open-ended clarifies keep the plain-text path
• inbound poll_option selections dispatch as a plain-text MessageEvent carrying the chosen option (deselections / empty votes dropped)
• if the poll send fails (older sidecar without /send-poll, or a send error) → fall back to the numbered-text clarify, so nothing regresses on a half-upgraded restart

No new model tool, no new env var, no core change — capability lives at the platform edge, and the vote reuses the existing clarify text-intercept resolution path (no new gateway resolution mechanism).

Test plan

• tests/plugins/platforms/photon/test_poll_clarify.py (6 tests): inbound vote → choice text; deselection dropped; empty-title vote dropped; send_clarify with choices sends a poll + enables text-capture; open-ended stays text; poll-failure falls back to the text list
• Full photon suite green (pytest tests/plugins/platforms/photon/)
• node --check sidecar, py_compile adapter — clean tree, no dependency on local mods
• Live: native poll bubble renders on real iMessage; tap streams back the poll_option event the new code consumes

Compatibility

Additive (+379/-1). /send-poll is a new route; the adapter degrades to the text-list clarify if the sidecar predates it, and open-ended clarify is unchanged.

Contributed by Vaibhav Sharma (X @vabbyshabby).

[alt-glitch]

Related: #43665 (feat(photon): add native poll sending). That PR adds the generic outbound poll primitive (/send-poll sidecar route + send_poll() adapter method) via spectrum-ts poll(). This PR adds the same outbound route plus the layer #43665 lacks: it wires multiple-choice clarify prompts to a native poll AND consumes the inbound poll_option vote to resolve the pending clarify (with a text-list fallback). Complementary rather than duplicate — reviewers may want to reconcile the two /send-poll implementations.

[tonydwb]

Code Review Summary

Verdict: Approved

Renders multiple-choice clarify questions as native iMessage polls via spectrum-ts. Selection streams back as a poll_option event resolved as plain text. Graceful fallback to numbered text if native poll fails.

Looks Good

• Clean feature implementation with proper error handling
• Well-documented code with clear architectural comments
• Fallback path is well-thought-out
• No debug or diagnostic artifacts
• Appropriate logging for production

---

Reviewed by Hermes Agent

[vaibhavjnf]

Cant wait to become a hermes contributor 😭

[teknium1]

Thanks for the focused edge-platform implementation. The current main premise is valid: Photon still inherits the numbered clarify fallback in gateway/platforms/base.py:3149-3166, and its inbound dispatcher has no poll_option handling (plugins/platforms/photon/adapter.py:700-789).

Problems

• tests/plugins/platforms/photon/test_poll_clarify.py:25-33 replaces handle_message, so the tests do not cover the actual pending-clarify interception path in gateway/run.py:9076-9107. This feature changes that message-resolution chain; add an integration-style test that registers a pending clarify and verifies a poll vote resolves it through the normal gateway path.
• The branch predates current Photon sidecar changes. Main now pins spectrum-ts 8.0.0 at plugins/platforms/photon/sidecar/package.json:13 (commit 4345b3e76), so validate the poll export and poll_option payload against that SDK during salvage.
• The new sidecar poll normalization still falls into the adapter's unsupported-content fallback at plugins/platforms/photon/adapter.py:787-789; either define its adapter behavior or omit that serialization.

Suggested changes

• Reconcile the duplicate /send-poll primitive with related open PR feat(photon): add native poll sending #43665, then retain this PR's clarify-specific routing and fallback.

Automated hermes-sweeper review.

[teknium1]

Merged via #73614 — cherry-picked with authorship preserved; a maintainer follow-up deduplicated the /send-poll route in favor of #43665's primitive (earliest submission) and tightened option validation to the sidecar contract. The clarify→poll→vote-resolution loop is a genuinely great UX idea.