@clawpump/claw-agent 0.1.5 → 0.1.7

package/agent/plugins/platforms/mattermost/adapter.py

@@ -96,6 +96,9 @@ class MattermostAdapter(BasePlatformAdapter):
             or os.getenv("MATTERMOST_REPLY_MODE", "off")
         ).lower()
 
+        self._last_post_status: Optional[int] = None
+        self._last_post_error: str = ""
+
         # Dedup cache (prevent reprocessing)
         self._dedup = MessageDeduplicator()
 
@@ -130,20 +133,79 @@ class MattermostAdapter(BasePlatformAdapter):
         """POST /api/v4/{path} with JSON body."""
         import aiohttp
         url = f"{self._base_url}/api/v4/{path.lstrip('/')}"
+        self._last_post_status = None
+        self._last_post_error = ""
         try:
             async with self._session.post(
                 url, headers=self._headers(), json=payload,
                 timeout=aiohttp.ClientTimeout(total=30)
             ) as resp:
+                self._last_post_status = resp.status
                 if resp.status >= 400:
                     body = await resp.text()
+                    self._last_post_error = body or ""
                     logger.error("MM API POST %s → %s: %s", path, resp.status, body[:200])
                     return {}
                 return await resp.json()
         except aiohttp.ClientError as exc:
+            self._last_post_error = str(exc)
             logger.error("MM API POST %s network error: %s", path, exc)
             return {}
 
+    async def _thread_root_for_send(
+        self,
+        reply_to: Optional[str],
+        metadata: Optional[Dict[str, Any]],
+    ) -> Optional[str]:
+        """Resolve the Mattermost root_id from reply_to or metadata."""
+        if self._reply_mode != "thread":
+            return None
+        candidate = reply_to
+        if not candidate and isinstance(metadata, dict):
+            candidate = metadata.get("thread_id") or metadata.get("root_id")
+        if not candidate:
+            return None
+        return await self._resolve_root_id(str(candidate))
+
+    def _last_post_failure_is_broken_thread_root(self) -> bool:
+        """Return True only for clear invalid/missing Mattermost thread roots."""
+        if self._last_post_status not in {400, 404}:
+            return False
+        body = (self._last_post_error or "").lower()
+        if not body:
+            return False
+        rootish = any(marker in body for marker in ("root_id", "rootid", "root id", "thread", "post"))
+        broken = any(marker in body for marker in ("invalid", "not found", "does not exist", "missing"))
+        return rootish and broken
+
+    async def _post_preserving_thread(
+        self,
+        chat_id: str,
+        payload: Dict[str, Any],
+        metadata: Optional[Dict[str, Any]],
+    ) -> Dict[str, Any]:
+        """Post once, optionally falling back flat for final notify content."""
+        data = await self._api_post("posts", payload)
+        if data or "root_id" not in payload:
+            return data
+        if not (isinstance(metadata, dict) and metadata.get("notify")):
+            return data
+        if not self._last_post_failure_is_broken_thread_root():
+            return data
+
+        flat_payload = dict(payload)
+        flat_payload.pop("root_id", None)
+        original = str(flat_payload.get("message") or "")
+        flat_payload["message"] = (
+            "⚠️ Mattermost thread delivery failed; posting final reply in channel.\n\n"
+            + original
+        ).strip()
+        logger.warning(
+            "Mattermost: falling back to flat channel delivery for notify-worthy post in %s",
+            chat_id,
+        )
+        return await self._api_post("posts", flat_payload)
+
     async def _api_put(
         self, path: str, payload: Dict[str, Any]
     ) -> Dict[str, Any]:
@@ -286,14 +348,12 @@ class MattermostAdapter(BasePlatformAdapter):
                 "channel_id": chat_id,
                 "message": chunk,
             }
-            # Thread support: reply_to is the root post ID.
-            if reply_to and self._reply_mode == "thread":
-                # Ensure root_id points to the thread root, not a reply.
-                # Mattermost rejects non-root post IDs as root_id.
-                resolved_root = await self._resolve_root_id(reply_to)
+            # Thread support: reply_to or metadata["thread_id"] is the root post ID.
+            resolved_root = await self._thread_root_for_send(reply_to, metadata)
+            if resolved_root:
                 payload["root_id"] = resolved_root
 
-            data = await self._api_post("posts", payload)
+            data = await self._post_preserving_thread(chat_id, payload, metadata)
             if not data or "id" not in data:
                 return SendResult(success=False, error="Failed to create post")
             last_id = data["id"]
@@ -346,7 +406,7 @@ class MattermostAdapter(BasePlatformAdapter):
     ) -> SendResult:
         """Download an image and upload it as a file attachment."""
         return await self._send_url_as_file(
-            chat_id, image_url, caption, reply_to, "image"
+            chat_id, image_url, caption, reply_to, "image", metadata
         )
 
     async def send_image_file(
@@ -359,7 +419,7 @@ class MattermostAdapter(BasePlatformAdapter):
     ) -> SendResult:
         """Upload a local image file."""
         return await self._send_local_file(
-            chat_id, image_path, caption, reply_to
+            chat_id, image_path, caption, reply_to, metadata=metadata
         )
 
     async def send_document(
@@ -373,7 +433,7 @@ class MattermostAdapter(BasePlatformAdapter):
     ) -> SendResult:
         """Upload a local file as a document."""
         return await self._send_local_file(
-            chat_id, file_path, caption, reply_to, file_name
+            chat_id, file_path, caption, reply_to, file_name, metadata
         )
 
     async def send_voice(
@@ -386,7 +446,7 @@ class MattermostAdapter(BasePlatformAdapter):
     ) -> SendResult:
         """Upload an audio file."""
         return await self._send_local_file(
-            chat_id, audio_path, caption, reply_to
+            chat_id, audio_path, caption, reply_to, metadata=metadata
         )
 
     async def send_video(
@@ -399,7 +459,7 @@ class MattermostAdapter(BasePlatformAdapter):
     ) -> SendResult:
         """Upload a video file."""
         return await self._send_local_file(
-            chat_id, video_path, caption, reply_to
+            chat_id, video_path, caption, reply_to, metadata=metadata
         )
 
     def format_message(self, content: str) -> str:
@@ -423,12 +483,13 @@ class MattermostAdapter(BasePlatformAdapter):
         caption: Optional[str],
         reply_to: Optional[str],
         kind: str = "file",
+        metadata: Optional[Dict[str, Any]] = None,
     ) -> SendResult:
         """Download a URL and upload it as a file attachment."""
         from tools.url_safety import is_safe_url
         if not is_safe_url(url):
             logger.warning("Mattermost: blocked unsafe URL (SSRF protection)")
-            return await self.send(chat_id, f"{caption or ''}\n{url}".strip(), reply_to)
+            return await self.send(chat_id, f"{caption or ''}\n{url}".strip(), reply_to, metadata=metadata)
 
         import aiohttp
 
@@ -446,7 +507,7 @@ class MattermostAdapter(BasePlatformAdapter):
                             await asyncio.sleep(1.5 * (attempt + 1))
                             continue
                     if resp.status >= 400:
-                        return await self.send(chat_id, f"{caption or ''}\n{url}".strip(), reply_to)
+                        return await self.send(chat_id, f"{caption or ''}\n{url}".strip(), reply_to, metadata=metadata)
                     file_data = await resp.read()
                     ct = resp.content_type or "application/octet-stream"
                     break
@@ -455,25 +516,26 @@ class MattermostAdapter(BasePlatformAdapter):
                     await asyncio.sleep(1.5 * (attempt + 1))
                     continue
                 logger.warning("Mattermost: failed to download %s after %d attempts: %s", url, attempt + 1, exc)
-                return await self.send(chat_id, f"{caption or ''}\n{url}".strip(), reply_to)
+                return await self.send(chat_id, f"{caption or ''}\n{url}".strip(), reply_to, metadata=metadata)
 
         if file_data is None:
             logger.warning("Mattermost: download returned no data for %s", url)
-            return await self.send(chat_id, f"{caption or ''}\n{url}".strip(), reply_to)
+            return await self.send(chat_id, f"{caption or ''}\n{url}".strip(), reply_to, metadata=metadata)
 
         file_id = await self._upload_file(chat_id, file_data, fname, ct)
         if not file_id:
-            return await self.send(chat_id, f"{caption or ''}\n{url}".strip(), reply_to)
+            return await self.send(chat_id, f"{caption or ''}\n{url}".strip(), reply_to, metadata=metadata)
 
         payload: Dict[str, Any] = {
             "channel_id": chat_id,
             "message": caption or "",
             "file_ids": [file_id],
         }
-        if reply_to and self._reply_mode == "thread":
-            payload["root_id"] = await self._resolve_root_id(reply_to)
+        resolved_root = await self._thread_root_for_send(reply_to, metadata)
+        if resolved_root:
+            payload["root_id"] = resolved_root
 
-        data = await self._api_post("posts", payload)
+        data = await self._post_preserving_thread(chat_id, payload, metadata)
         if not data or "id" not in data:
             return SendResult(success=False, error="Failed to post with file")
         return SendResult(success=True, message_id=data["id"])
@@ -485,6 +547,7 @@ class MattermostAdapter(BasePlatformAdapter):
         caption: Optional[str],
         reply_to: Optional[str],
         file_name: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
     ) -> SendResult:
         """Upload a local file and attach it to a post."""
         import mimetypes
@@ -509,10 +572,11 @@ class MattermostAdapter(BasePlatformAdapter):
             "message": caption or "",
             "file_ids": [file_id],
         }
-        if reply_to and self._reply_mode == "thread":
-            payload["root_id"] = await self._resolve_root_id(reply_to)
+        resolved_root = await self._thread_root_for_send(reply_to, metadata)
+        if resolved_root:
+            payload["root_id"] = resolved_root
 
-        data = await self._api_post("posts", payload)
+        data = await self._post_preserving_thread(chat_id, payload, metadata)
         if not data or "id" not in data:
             return SendResult(success=False, error="Failed to post with file")
         return SendResult(success=True, message_id=data["id"])
@@ -596,11 +660,14 @@ class MattermostAdapter(BasePlatformAdapter):
                     "message": "\n".join(caption_parts),
                     "file_ids": file_ids,
                 }
+                resolved_root = await self._thread_root_for_send(None, metadata)
+                if resolved_root:
+                    payload["root_id"] = resolved_root
                 logger.info(
                     "Mattermost: sending %d image(s) as single post (chunk %d/%d)",
                     len(file_ids), chunk_idx + 1, len(chunks),
                 )
-                data = await self._api_post("posts", payload)
+                data = await self._post_preserving_thread(chat_id, payload, metadata)
                 if not data or "id" not in data:
                     logger.warning("Mattermost: multi-image post failed, falling back")
                     await super().send_multiple_images(chat_id, chunk, metadata, human_delay=human_delay)
@@ -786,8 +853,16 @@ class MattermostAdapter(BasePlatformAdapter):
         sender_id = post.get("user_id", "")
         sender_name = data.get("sender_name", "").lstrip("@") or sender_id
 
-        # Thread support: if the post is in a thread, use root_id.
+        # Thread support: if the post is in a thread, use root_id. In
+        # thread mode, top-level channel posts are valid roots for progress.
         thread_id = post.get("root_id") or None
+        if (
+            not thread_id
+            and self._reply_mode == "thread"
+            and channel_type_raw != "D"
+            and post_id
+        ):
+            thread_id = post_id
 
         # Determine message type.
         file_ids = post.get("file_ids") or []
@@ -849,6 +924,7 @@ class MattermostAdapter(BasePlatformAdapter):
             user_id=sender_id,
             user_name=sender_name,
             thread_id=thread_id,
+            message_id=post_id,
         )
 
         # Per-channel ephemeral prompt

package/agent/plugins/platforms/photon/README.md

@@ -0,0 +1,179 @@
+# Photon iMessage platform plugin
+
+This plugin connects Hermes Agent to iMessage (and other Spectrum
+interfaces) through [Photon][photon] — a managed service that handles
+iMessage line allocation, delivery, and abuse-prevention so users don't
+have to run their own Mac relay.
+
+The free tier uses Photon's shared iMessage line pool and is the path we
+recommend for everyone who doesn't already pay for a dedicated number.
+
+## Architecture
+
+Like Discord and Slack, Photon is a **persistent-connection** channel — no
+public URL, no webhook, no signing secret. The `spectrum-ts` SDK holds a
+long-lived **gRPC stream** to Photon for both directions. Because the SDK is
+TypeScript-only, Hermes runs it inside a small supervised Node sidecar and
+talks to it over loopback.
+
+```
+                         gRPC (spectrum-ts)
+┌─────────────────────────┐ ◄───────────────► ┌──────────────────────┐
+│  Photon Spectrum cloud  │   app.messages    │  Node sidecar        │
+│  (iMessage line owner)  │   space.send()    │  (plugins/…/sidecar) │
+└─────────────────────────┘                   └──────────┬───────────┘
+                                       GET /inbound (NDJSON) │  ▲ POST /send
+                                       inbound events        ▼  │ /typing
+                                              ┌──────────────────────┐
+                                              │  PhotonAdapter        │
+                                              │  (Python, in gateway) │
+                                              └──────────────────────┘
+```
+
+- **Inbound**: the sidecar consumes the SDK's `app.messages` gRPC stream,
+  normalizes each message, and streams it to the adapter over a loopback
+  `GET /inbound` (NDJSON). The adapter dedupes on `messageId` and dispatches
+  a `MessageEvent` to the gateway. It reconnects automatically if the stream
+  drops; the sidecar owns the gRPC reconnect to Photon.
+- **Outbound**: `send` / `send_typing` / reaction tapbacks are loopback POSTs
+  to the sidecar (`/send`, `/send-attachment`, `/typing`, `/react`,
+  `/unreact`), authenticated with a shared `X-Hermes-Sidecar-Token`.
+
+## First-time setup
+
+```bash
+# One-shot setup: device login (opens browser) + project + user + sidecar deps
+hermes photon setup --phone +15551234567
+
+# Start the gateway
+hermes gateway start
+```
+
+`hermes photon setup` does, in order:
+
+1. **Device login** (RFC 8628, `client_id=photon-cli`) — opens
+   `https://app.photon.codes/` for approval and stores the bearer token.
+2. **Find or create** the `Hermes Agent` project on the Photon dashboard.
+3. **Provision the project secret** — mint a fresh project secret (the
+   dashboard reveals it only once) and persist it to `~/.hermes/.env` so the
+   sidecar can authenticate `spectrum-ts`. Spectrum is always on, so there's no
+   separate enable step.
+4. **Register your phone number** as a Spectrum user (idempotent — skipped if
+   a user with that number already exists).
+5. **Print the assigned iMessage line** — the number you text to reach your
+   agent.
+6. **Install the sidecar deps** (`npm ci` — installs the committed lockfile
+   verbatim, so every setup runs the exact `spectrum-ts` version this plugin
+   was written against).
+
+There is no separate `login` command; like every other Hermes channel,
+onboarding goes through one setup surface. Re-running `setup` reuses an
+existing token/project, so it's safe to run again to finish a partial setup.
+Run `hermes photon status` to see what's configured.
+
+## Credentials
+
+Runtime SDK credentials live in `~/.hermes/.env` (the same place every other
+channel keeps its token), and the adapter reads them from the environment:
+
+```bash
+PHOTON_PROJECT_ID=<projectId>   # the SDK's projectId (same as the dashboard project id)
+PHOTON_PROJECT_SECRET=<projectSecret>
+```
+
+Management metadata lives in `~/.hermes/auth.json` under `credential_pool`:
+
+```jsonc
+{
+  "credential_pool": {
+    "photon": [
+      { "access_token": "<device-bearer>", "issued_at": ... }
+    ],
+    "photon_project": [
+      {
+        "dashboard_project_id": "<project id>",
+        "spectrum_project_id": "<project id>",
+        "project_secret": "<projectSecret>",
+        "name": "Hermes Agent"
+      }
+    ]
+  }
+}
+```
+
+> **Note on ids.** A Photon project's dashboard id and its Spectrum project id
+> are the same value, exposed as `PHOTON_PROJECT_ID`. The `dashboard_project_id`
+> and `spectrum_project_id` keys in `auth.json` both hold that id.
+
+## Configuration knobs
+
+All env vars are documented in `plugin.yaml`. The most important:
+
+| Env var                   | Default                    | Meaning                              |
+|---------------------------|----------------------------|--------------------------------------|
+| `PHOTON_PROJECT_ID`       | from .env / auth.json      | Spectrum project id (SDK `projectId`)|
+| `PHOTON_PROJECT_SECRET`   | from .env / auth.json      | Project secret                       |
+| `PHOTON_SIDECAR_PORT`     | 8789                       | Loopback port for the sidecar        |
+| `PHOTON_SIDECAR_AUTOSTART`| true                       | Spawn the sidecar on connect         |
+| `PHOTON_DASHBOARD_HOST`   | https://app.photon.codes   | Dashboard API host                   |
+| `PHOTON_SPECTRUM_HOST`    | https://spectrum.photon.codes | Spectrum API host                 |
+| `PHOTON_HOME_CHANNEL`     | your number (set by setup) | Default space for cron delivery — a space id, or a bare E.164 number (resolved to a DM) |
+| `PHOTON_ALLOWED_USERS`    | your number (set by setup) | Comma-separated E.164 allowlist      |
+| `PHOTON_REQUIRE_MENTION`  | false                      | Gate group chats on a wake word      |
+| `PHOTON_MAX_INLINE_ATTACHMENT_BYTES` | 20 MB           | Max inbound attachment size the sidecar reads & inlines |
+| `PHOTON_TELEMETRY`        | false                      | Spectrum SDK telemetry — toggle with `hermes photon telemetry on\|off` (restart the gateway to apply) |
+| `PHOTON_MARKDOWN`         | true                       | Send agent replies as markdown (iMessage renders natively). `false` strips formatting to plain text |
+| `PHOTON_REACTIONS`        | false                      | Tapback 👀/👍/👎 as processing status; tapbacks on bot messages reach the agent as `reaction:added:<emoji>` |
+
+## Attachments & limitations
+
+- **Inbound attachments and voice notes are downloaded.** The sidecar reads
+  the bytes (`content.read()`) and base64-inlines them on the NDJSON event; the
+  adapter caches them to the shared media cache and populates `media_urls` /
+  `media_types`, so the agent sees the real image/file or can transcribe the
+  voice note — parity with the BlueBubbles iMessage channel. Mixed iMessage
+  bubbles that contain both text and attachments are normalized as a grouped
+  payload so the user's typed text is preserved alongside the cached media.
+  Media larger than `PHOTON_MAX_INLINE_ATTACHMENT_BYTES` (default 20 MB), or
+  any byte read that fails, falls back to a text marker (`[Photon attachment
+  received: …]` or `[Photon voice received: …]`) so the agent still knows
+  something arrived.
+- **Outbound attachments are supported.** Images, voice notes, video, and
+  documents are sent via `space.send(attachment(...))` /
+  `space.send(voice(...))` through the sidecar's `/send-attachment`
+  endpoint; a caption is delivered as a separate text bubble after the media.
+- **Markdown is rendered.** Replies go out via spectrum-ts' `markdown()`
+  builder; iMessage renders bold/italics/lists/code natively and other
+  Spectrum platforms degrade to readable plain text. `PHOTON_MARKDOWN=false`
+  reverts to stripped plain text.
+- **Reactions (tapbacks) are supported** behind `PHOTON_REACTIONS` (default
+  off): the adapter tapbacks 👀 while processing and swaps it for 👍/👎 on
+  completion, and a user tapback on a bot-sent message is routed to the agent
+  as a synthetic `reaction:added:<emoji>` event. Removal after a sidecar
+  restart is best-effort — the live reaction handle is lost, so a stale
+  tapback heals when the next reaction replaces it. Group spaces stay
+  reachable across restarts via spectrum-ts v3's `space.get(id)`.
+- **Message effects, polls** — supported by `spectrum-ts` but not yet
+  exposed; the sidecar is the natural place to add them.
+
+## Upgrading spectrum-ts
+
+`spectrum-ts` is pinned to an **exact version** in `sidecar/package.json`
+(no `^` range) and installed with `npm ci`, because the SDK ships breaking
+majors (v2 removed `defineFusorPlatform`; v3 reworked space construction).
+A floating range or `npm install spectrum-ts@latest` would let a breaking
+release take down fresh setups silently. Upgrades are deliberate:
+
+1. Read the [SDK release notes](https://github.com/photon-hq/spectrum-ts/releases)
+   for every version between the current pin and the target.
+2. Bump the exact pin in `sidecar/package.json`, then run `npm install`
+   inside `sidecar/` to regenerate `package-lock.json`. Commit both.
+3. Migrate `sidecar/index.mjs` against the new typings
+   (`sidecar/node_modules/spectrum-ts/dist/*.d.ts` is the source of truth —
+   the hosted docs can lag).
+4. Run `pytest tests/plugins/platforms/photon/`.
+5. Verify end-to-end: `hermes photon status`, a DM and a group roundtrip,
+   and an agent reply into a group right after a gateway restart (exercises
+   `space.get` rehydration).
+
+[photon]: https://photon.codes/

package/agent/plugins/platforms/photon/__init__.py

@@ -0,0 +1,4 @@
+"""Photon Spectrum (iMessage) platform plugin entry point."""
+from .adapter import register
+
+__all__ = ["register"]