@shadowob/connector 1.1.6 → 1.1.8

package/hermes-shadowob-plugin/adapter.py

@@ -55,9 +55,9 @@ except Exception:  # pragma: no cover - lets local static checks import this fil
         return None
 
 try:
-    from .shadow_sdk import ShadowAsyncClient, ShadowSocketClient, parse_bool, split_csv
+    from .shadow_sdk import ShadowApiError, ShadowAsyncClient, ShadowSocketClient, parse_bool, split_csv
 except Exception:  # pragma: no cover - Hermes may load adapter.py as a loose module.
-    from shadow_sdk import ShadowAsyncClient, ShadowSocketClient, parse_bool, split_csv  # type: ignore
+    from shadow_sdk import ShadowApiError, ShadowAsyncClient, ShadowSocketClient, parse_bool, split_csv  # type: ignore
 
 logger = logging.getLogger(__name__)
 
@@ -68,6 +68,11 @@ _AUDIO_CT_PREFIXES = ("audio/",)
 _VIDEO_CT_PREFIXES = ("video/",)
 _DOCUMENT_CT_PREFIXES = ("application/", "text/")
 _SLASH_COMMAND_RE = re.compile(r"^/([a-zA-Z][a-zA-Z0-9._-]{0,63})(?:\s+([\s\S]*))?$")
+_TERMINAL_TASK_STATUSES = {"completed", "failed", "canceled", "transferred"}
+
+
+def _visible_text(text: str) -> str:
+    return text.replace("\u200b", "").strip()
 
 
 def _extra(config: Any) -> dict[str, Any]:
@@ -218,6 +223,36 @@ def _parse_json_list(value: Any) -> list[dict[str, Any]]:
     return []
 
 
+def _parse_int(value: Any) -> int | None:
+    if value in (None, ""):
+        return None
+    try:
+        parsed = int(float(str(value)))
+        return parsed if parsed >= 0 else None
+    except Exception:
+        return None
+
+
+def _parse_waveform_peaks(value: Any) -> list[int] | None:
+    if value in (None, ""):
+        return None
+    raw = value
+    if isinstance(value, str):
+        try:
+            raw = json.loads(value)
+        except Exception:
+            return None
+    if not isinstance(raw, list):
+        return None
+    peaks: list[int] = []
+    for item in raw:
+        parsed = _parse_int(item)
+        if parsed is None or parsed < 0 or parsed > 100:
+            return None
+        peaks.append(parsed)
+    return peaks if 32 <= len(peaks) <= 96 else None
+
+
 def _normalize_slash_command_name(value: Any) -> str | None:
     if not isinstance(value, str):
         return None
@@ -388,6 +423,119 @@ def _message_reply_to_id(message: dict[str, Any]) -> str | None:
     return str(value) if value else None
 
 
+def _message_cards(message: dict[str, Any]) -> list[dict[str, Any]]:
+    metadata = message.get("metadata")
+    if not isinstance(metadata, dict):
+        return []
+    cards = metadata.get("cards")
+    if not isinstance(cards, list):
+        return []
+    return [card for card in cards if isinstance(card, dict)]
+
+
+def _card_id(card: dict[str, Any]) -> str | None:
+    value = card.get("id") or card.get("cardId") or card.get("card_id")
+    return str(value) if value else None
+
+
+def _task_card_by_id(message: dict[str, Any], card_id: str | None) -> dict[str, Any] | None:
+    if not card_id:
+        return None
+    for card in _message_cards(message):
+        if str(card.get("id") or "") == card_id:
+            return card
+    return None
+
+
+def _task_card_claim_expired(card: dict[str, Any]) -> bool:
+    claim = card.get("claim")
+    expires_at = claim.get("expiresAt") if isinstance(claim, dict) else None
+    if not expires_at:
+        return True
+    try:
+        expires = datetime.fromisoformat(str(expires_at).replace("Z", "+00:00"))
+        if expires.tzinfo is None:
+            expires = expires.replace(tzinfo=timezone.utc)
+        return expires <= datetime.now(timezone.utc)
+    except Exception:
+        return True
+
+
+def _task_card_matches_self(card: dict[str, Any], *, bot_user_id: str | None, agent_id: str | None) -> bool:
+    if card.get("kind") != "task":
+        return False
+    status = str(card.get("status") or "").lower()
+    if status in _TERMINAL_TASK_STATUSES:
+        return False
+    assignee = card.get("assignee")
+    if not isinstance(assignee, dict):
+        return True
+    assigned_user = assignee.get("userId") or assignee.get("user_id")
+    assigned_agent = assignee.get("agentId") or assignee.get("agent_id")
+    if bot_user_id and assigned_user and str(assigned_user) == bot_user_id:
+        return True
+    if agent_id and assigned_agent and str(assigned_agent) == agent_id:
+        return True
+    return not assigned_user and not assigned_agent
+
+
+def _message_task_card_for_self(
+    message: dict[str, Any],
+    *,
+    bot_user_id: str | None,
+    agent_id: str | None,
+) -> dict[str, Any] | None:
+    for card in _message_cards(message):
+        if _task_card_matches_self(card, bot_user_id=bot_user_id, agent_id=agent_id):
+            return card
+    return None
+
+
+def _format_task_card_prompt(
+    text: str,
+    card: dict[str, Any],
+    *,
+    message_id: str | None = None,
+) -> str:
+    title = str(card.get("title") or "Inbox task").strip()
+    body = str(card.get("body") or "").strip()
+    priority = str(card.get("priority") or "").strip()
+    source = card.get("source") if isinstance(card.get("source"), dict) else {}
+    source_label = str(source.get("label") or source.get("command") or "").strip()
+    card_id = str(card.get("id") or "").strip()
+    claim = card.get("claim") if isinstance(card.get("claim"), dict) else {}
+    claim_id = str(claim.get("id") or "").strip()
+    data = card.get("data") if isinstance(card.get("data"), dict) else {}
+    task_data = data.get("task") if isinstance(data.get("task"), dict) else {}
+    workspace_id = str(task_data.get("workspaceId") or "").strip()
+    lines = ["[Shadow Inbox task]", f"Title: {title}"]
+    if message_id:
+        lines.append(f"Task message id: {message_id}")
+    if card_id:
+        lines.append(f"Task card id: {card_id}")
+    if claim_id:
+        lines.append(f"Task claim id: {claim_id}")
+    if workspace_id:
+        lines.append(f"Task workspace id: {workspace_id}")
+    if priority:
+        lines.append(f"Priority: {priority}")
+    if source_label:
+        lines.append(f"Source: {source_label}")
+    if message_id and card_id and claim_id:
+        lines.extend(
+            [
+                "",
+                "Bind Shadow Server App command calls for this task with:",
+                f"--task-message-id {message_id} --task-card-id {card_id} --task-claim-id {claim_id}",
+            ]
+        )
+    if body:
+        lines.extend(["", body])
+    if text and text.strip() and text.strip() not in {title, body}:
+        lines.extend(["", "Original message:", text.strip()])
+    return "\n".join(lines)
+
+
 def _text_without_self_mention(text: str, username: str | None) -> str:
     if not username:
         return text
@@ -735,7 +883,19 @@ class ShadowOBAdapter(BasePlatformAdapter):
         metadata: Optional[dict[str, Any]] = None,
         **kwargs,
     ) -> SendResult:
-        return await self._send_file(chat_id, audio_path, caption=caption, reply_to=reply_to, metadata=metadata)
+        return await self._send_file(
+            chat_id,
+            audio_path,
+            caption=caption,
+            reply_to=reply_to,
+            metadata=metadata,
+            attachment_kind="voice",
+            duration_ms=_parse_int(kwargs.get("duration_ms") or kwargs.get("durationMs")),
+            waveform_peaks=_parse_waveform_peaks(kwargs.get("waveform_peaks") or kwargs.get("waveformPeaks")),
+            transcript_text=kwargs.get("transcript") or kwargs.get("transcript_text"),
+            transcript_language=kwargs.get("transcript_language") or kwargs.get("transcriptLanguage"),
+            transcript_source="runtime",
+        )
 
     async def send_image(
         self,
@@ -823,6 +983,12 @@ class ShadowOBAdapter(BasePlatformAdapter):
         caption: str | None = None,
         reply_to: str | None = None,
         metadata: dict[str, Any] | None = None,
+        attachment_kind: str | None = None,
+        duration_ms: int | None = None,
+        waveform_peaks: list[int] | None = None,
+        transcript_text: str | None = None,
+        transcript_language: str | None = None,
+        transcript_source: str | None = None,
     ) -> SendResult:
         if self.client is None:
             return SendResult(success=False, error="Shadow client is not initialized", retryable=True)
@@ -835,7 +1001,16 @@ class ShadowOBAdapter(BasePlatformAdapter):
                 reply_to_id=_metadata_reply_to(metadata, reply_to),
                 metadata=_metadata_payload(metadata),
             )
-            await self.client.upload_media_from_path(path, message_id=str(msg.get("id")))
+            await self.client.upload_media_from_path(
+                path,
+                message_id=str(msg.get("id")),
+                kind=attachment_kind,
+                duration_ms=duration_ms,
+                waveform_peaks=waveform_peaks,
+                transcript_text=str(transcript_text) if transcript_text else None,
+                transcript_language=str(transcript_language) if transcript_language else None,
+                transcript_source=transcript_source,
+            )
             return SendResult(success=True, message_id=str(msg.get("id") or ""), raw_response=msg)
         except Exception as exc:
             return SendResult(success=False, error=str(exc), retryable=self._is_retryable(exc))
@@ -1305,6 +1480,71 @@ class ShadowOBAdapter(BasePlatformAdapter):
         except Exception as exc:
             logger.warning("[Shadow] Failed to refresh remote config after policy change: %s", exc)
 
+    async def _activate_task_card(
+        self,
+        message: dict[str, Any],
+        card: dict[str, Any] | None,
+    ) -> dict[str, Any] | None:
+        if self.client is None or not card:
+            return card
+        message_id = _message_id(message)
+        card_id = _card_id(card)
+        if not message_id or not card_id:
+            return None
+
+        status = str(card.get("status") or "").lower()
+        try:
+            if status == "queued" or (status in {"claimed", "running"} and _task_card_claim_expired(card)):
+                updated = await self.client.claim_task_card(
+                    message_id,
+                    card_id,
+                    ttl_seconds=3600,
+                    note="Hermes accepted the Inbox task.",
+                )
+                message = updated if isinstance(updated, dict) else message
+                card = _task_card_by_id(message, card_id) or card
+                status = str(card.get("status") or status).lower()
+
+            if status in {"queued", "claimed"}:
+                updated = await self.client.update_task_card(
+                    message_id,
+                    card_id,
+                    status="running",
+                    note="Hermes started working on the task.",
+                )
+                message = updated if isinstance(updated, dict) else message
+                card = _task_card_by_id(message, card_id) or card
+            return card
+        except ShadowApiError as exc:
+            if exc.status_code == 409:
+                logger.info("[Shadow] Inbox task card %s is already claimed; skipping message %s", card_id, message_id)
+                return None
+            logger.warning("[Shadow] Failed to activate Inbox task card %s/%s: %s", message_id, card_id, exc)
+            return None
+        except Exception as exc:
+            logger.warning("[Shadow] Failed to activate Inbox task card %s/%s: %s", message_id, card_id, exc)
+            return None
+
+    async def _complete_task_card(
+        self,
+        message_id: str | None,
+        card_id: str | None,
+        *,
+        failed: bool = False,
+        note: str | None = None,
+    ) -> None:
+        if self.client is None or not message_id or not card_id:
+            return
+        try:
+            await self.client.update_task_card(
+                message_id,
+                card_id,
+                status="failed" if failed else "completed",
+                note=(note or ("Hermes failed while processing this task." if failed else "Hermes finished processing this task."))[:4000],
+            )
+        except Exception as exc:
+            logger.debug("[Shadow] Failed to update Inbox task card %s/%s completion: %s", message_id, card_id, exc)
+
     async def _handle_shadow_message(self, message: dict[str, Any], *, source: str) -> None:
         message_id = _message_id(message)
         if not message_id:
@@ -1336,10 +1576,15 @@ class ShadowOBAdapter(BasePlatformAdapter):
         if policy and not _policy_bool(policy, "reply", True):
             logger.debug("[Shadow] policy reply=false skipped message %s", message_id)
             return
+        task_card = _message_task_card_for_self(
+            message,
+            bot_user_id=self._bot_user_id,
+            agent_id=self._agent_id,
+        )
         trigger_user_ids = policy_config.get("allowedTriggerUserIds") or policy_config.get("triggerUserIds")
         if isinstance(trigger_user_ids, list):
             allowed = {str(item) for item in trigger_user_ids if item}
-            if allowed and (not author_id or author_id not in allowed):
+            if allowed and not task_card and (not author_id or author_id not in allowed):
                 logger.debug("[Shadow] policy trigger users skipped message %s", message_id)
                 return
 
@@ -1353,7 +1598,7 @@ class ShadowOBAdapter(BasePlatformAdapter):
 
         text = _interactive_response_text(str(message.get("content") or ""), message, source_message)
         mention_only = self._mention_only or _policy_bool(policy, "mentionOnly", False)
-        if mention_only and not self._message_mentions_self(message):
+        if mention_only and not self._message_mentions_self(message) and not task_card:
             # DMs are allowed even in mention-only mode.
             channel = self._channel_cache.get(channel_id, {})
             kind = str(channel.get("kind") or channel.get("type") or "").lower()
@@ -1380,7 +1625,21 @@ class ShadowOBAdapter(BasePlatformAdapter):
         elif text.strip().startswith("/"):
             logger.info("[Shadow] Unknown slash command in message %s; treating as text", message_id)
 
-        media_paths, media_types, message_type = await self._resolve_inbound_media(message)
+        if task_card:
+            task_card = await self._activate_task_card(message, task_card)
+            if not task_card:
+                return
+            text = _format_task_card_prompt(text, task_card, message_id=message_id)
+
+        media_paths, media_types, message_type, media_metadata = await self._resolve_inbound_media(message)
+        voice_metadata = media_metadata.get("voice") if isinstance(media_metadata, dict) else None
+        voice_transcript = (
+            voice_metadata.get("transcript")
+            if isinstance(voice_metadata, dict) and voice_metadata.get("transcript_status") == "ready"
+            else None
+        )
+        if voice_transcript and not _visible_text(text):
+            text = str(voice_transcript)
         reply_to_id = _message_reply_to_id(message)
         reply_to_text = await self._fetch_reply_text(reply_to_id) if reply_to_id else None
 
@@ -1408,7 +1667,7 @@ class ShadowOBAdapter(BasePlatformAdapter):
             text=text or ("[Media attached]" if media_paths else ""),
             message_type=message_type,
             source=source_obj,
-            raw_message={"shadow": message, "source": source},
+            raw_message={"shadow": message, "source": source, "media": media_metadata},
             message_id=message_id,
             media_urls=media_paths,
             media_types=media_types,
@@ -1417,7 +1676,14 @@ class ShadowOBAdapter(BasePlatformAdapter):
             auto_skill=resolve_channel_skills(config_extra, thread_id or channel_id, parent_for_bindings),
             channel_prompt=resolve_channel_prompt(config_extra, thread_id or channel_id, parent_for_bindings),
         )
-        await self.handle_message(event)
+        task_card_id = _card_id(task_card) if task_card else None
+        try:
+            await self.handle_message(event)
+        except Exception as exc:
+            await self._complete_task_card(message_id, task_card_id, failed=True, note=str(exc))
+            raise
+        if task_card_id:
+            await self._complete_task_card(message_id, task_card_id)
 
     def _remember_processed(self, message_id: str) -> None:
         if len(self._processed_ids) == self._processed_ids.maxlen:
@@ -1458,15 +1724,40 @@ class ShadowOBAdapter(BasePlatformAdapter):
         except Exception:
             return None
 
-    async def _resolve_inbound_media(self, message: dict[str, Any]) -> tuple[list[str], list[str], Any]:
+    def _voice_attachment_metadata(self, attachment: dict[str, Any], path: str | None = None) -> dict[str, Any]:
+        transcript = attachment.get("transcript")
+        return {
+            "voice": True,
+            "attachment_id": attachment.get("id") or attachment.get("attachmentId") or attachment.get("attachment_id"),
+            "path": path,
+            "duration_ms": attachment.get("durationMs") or attachment.get("duration_ms"),
+            "waveform_peaks": attachment.get("waveformPeaks") or attachment.get("waveform_peaks"),
+            "transcript": transcript.get("text") if isinstance(transcript, dict) else None,
+            "transcript_status": transcript.get("status") if isinstance(transcript, dict) else None,
+        }
+
+    async def _resolve_inbound_media(self, message: dict[str, Any]) -> tuple[list[str], list[str], Any, dict[str, Any]]:
         attachments = message.get("attachments") or []
         if not isinstance(attachments, list) or not attachments:
-            return [], [], MessageType.TEXT
+            return [], [], MessageType.TEXT, {}
         if not self._download_media or self.client is None:
-            return [str(a.get("url")) for a in attachments if isinstance(a, dict) and a.get("url")], [str(a.get("contentType") or a.get("content_type") or "application/octet-stream") for a in attachments if isinstance(a, dict)], MessageType.DOCUMENT
+            urls = [str(a.get("url")) for a in attachments if isinstance(a, dict) and a.get("url")]
+            types = [str(a.get("contentType") or a.get("content_type") or "application/octet-stream") for a in attachments if isinstance(a, dict)]
+            voice_attachment = next(
+                (
+                    a
+                    for a in attachments
+                    if isinstance(a, dict)
+                    and (a.get("kind") == "voice" or str(a.get("contentType") or a.get("content_type") or "").startswith("audio/"))
+                ),
+                None,
+            )
+            metadata = {"voice": self._voice_attachment_metadata(voice_attachment)} if voice_attachment else {}
+            return urls, types, MessageType.DOCUMENT, metadata
 
         paths: list[str] = []
         types: list[str] = []
+        voice_metadata: dict[str, Any] | None = None
         dominant = MessageType.DOCUMENT
         for attachment in attachments:
             if not isinstance(attachment, dict):
@@ -1489,11 +1780,15 @@ class ShadowOBAdapter(BasePlatformAdapter):
                 paths.append(local_path)
                 types.append(content_type)
                 dominant = self._message_type_for_content_type(content_type, filename)
+                if attachment.get("kind") == "voice" or content_type.startswith(_AUDIO_CT_PREFIXES):
+                    voice_metadata = self._voice_attachment_metadata(attachment, local_path)
             except Exception as exc:
                 logger.warning("[Shadow] failed to cache inbound attachment %s: %s", url, exc)
                 paths.append(str(url))
                 types.append(content_type)
-        return paths, types, dominant
+                if attachment.get("kind") == "voice" or content_type.startswith(_AUDIO_CT_PREFIXES):
+                    voice_metadata = self._voice_attachment_metadata(attachment, str(url))
+        return paths, types, dominant, {"voice": voice_metadata} if voice_metadata else {}
 
     def _cache_downloaded_media(self, data: bytes, filename: str, content_type: str) -> str:
         suffix = Path(filename).suffix or self._extension_for_content_type(content_type)

package/hermes-shadowob-plugin/shadow_sdk.py

@@ -278,6 +278,42 @@ class ShadowAsyncClient:
     async def get_message(self, message_id: str) -> JsonDict:
         return await self.request("GET", f"/api/messages/{quote(str(message_id), safe='')}")
 
+    async def claim_task_card(
+        self,
+        message_id: str,
+        card_id: str,
+        *,
+        ttl_seconds: int | None = None,
+        note: str | None = None,
+    ) -> JsonDict:
+        body: JsonDict = {}
+        if ttl_seconds is not None:
+            body["ttlSeconds"] = int(ttl_seconds)
+        if note:
+            body["note"] = note
+        return await self.request(
+            "POST",
+            f"/api/messages/{quote(str(message_id), safe='')}/cards/{quote(str(card_id), safe='')}/claim",
+            json_body=body,
+        )
+
+    async def update_task_card(
+        self,
+        message_id: str,
+        card_id: str,
+        *,
+        status: str,
+        note: str | None = None,
+    ) -> JsonDict:
+        body: JsonDict = {"status": status}
+        if note:
+            body["note"] = note
+        return await self.request(
+            "PATCH",
+            f"/api/messages/{quote(str(message_id), safe='')}/cards/{quote(str(card_id), safe='')}",
+            json_body=body,
+        )
+
     async def resolve_attachment_media_url(
         self,
         attachment_id: str,
@@ -374,6 +410,12 @@ class ShadowAsyncClient:
         content_type: str | None = None,
         *,
         message_id: str | None = None,
+        kind: str | None = None,
+        duration_ms: int | None = None,
+        waveform_peaks: list[int] | None = None,
+        transcript_text: str | None = None,
+        transcript_language: str | None = None,
+        transcript_source: str | None = None,
     ) -> JsonDict:
         await self.open()
         content_type = content_type or infer_content_type(filename)
@@ -381,6 +423,18 @@ class ShadowAsyncClient:
         form_data: dict[str, str] = {}
         if message_id:
             form_data["messageId"] = message_id
+        if kind:
+            form_data["kind"] = kind
+        if duration_ms is not None:
+            form_data["durationMs"] = str(int(duration_ms))
+        if waveform_peaks is not None:
+            form_data["waveformPeaks"] = json.dumps(waveform_peaks)
+        if transcript_text:
+            form_data["transcriptText"] = transcript_text
+        if transcript_language:
+            form_data["transcriptLanguage"] = transcript_language
+        if transcript_source:
+            form_data["transcriptSource"] = transcript_source
         response = await self.client.post(
             self._url("/api/media/upload"),
             headers=self._headers(json_content=False),
@@ -391,7 +445,18 @@ class ShadowAsyncClient:
             raise ShadowApiError("POST", "/api/media/upload", response.status_code, response.text)
         return response.json()
 
-    async def upload_media_from_path(self, path: str | os.PathLike[str], *, message_id: str | None = None) -> JsonDict:
+    async def upload_media_from_path(
+        self,
+        path: str | os.PathLike[str],
+        *,
+        message_id: str | None = None,
+        kind: str | None = None,
+        duration_ms: int | None = None,
+        waveform_peaks: list[int] | None = None,
+        transcript_text: str | None = None,
+        transcript_language: str | None = None,
+        transcript_source: str | None = None,
+    ) -> JsonDict:
         p = Path(path).expanduser()
         data = p.read_bytes()
         return await self.upload_media(
@@ -399,22 +464,54 @@ class ShadowAsyncClient:
             p.name,
             infer_content_type(p.name),
             message_id=message_id,
+            kind=kind,
+            duration_ms=duration_ms,
+            waveform_peaks=waveform_peaks,
+            transcript_text=transcript_text,
+            transcript_language=transcript_language,
+            transcript_source=transcript_source,
         )
 
-    async def upload_media_from_url(self, url_or_path: str, *, message_id: str | None = None) -> JsonDict:
+    async def upload_media_from_url(
+        self,
+        url_or_path: str,
+        *,
+        message_id: str | None = None,
+        kind: str | None = None,
+        duration_ms: int | None = None,
+        waveform_peaks: list[int] | None = None,
+        transcript_text: str | None = None,
+        transcript_language: str | None = None,
+        transcript_source: str | None = None,
+    ) -> JsonDict:
         value = str(url_or_path).strip()
         if value.upper().startswith("MEDIA:"):
             value = value.split(":", 1)[1].strip()
         if value.startswith("file://"):
             value = value[7:]
         if value.startswith("~") or value.startswith("/") or not urlparse(value).scheme:
-            return await self.upload_media_from_path(value, message_id=message_id)
+            return await self.upload_media_from_path(
+                value,
+                message_id=message_id,
+                kind=kind,
+                duration_ms=duration_ms,
+                waveform_peaks=waveform_peaks,
+                transcript_text=transcript_text,
+                transcript_language=transcript_language,
+                transcript_source=transcript_source,
+            )
         downloaded = await self.download_file(value)
         return await self.upload_media(
             downloaded.data,
             downloaded.filename,
             downloaded.content_type,
             message_id=message_id,
+            kind=kind,
+            duration_ms=duration_ms,
+            waveform_peaks=waveform_peaks,
+            transcript_text=transcript_text,
+            transcript_language=transcript_language,
+            transcript_source=transcript_source,
         )
 
     async def download_file(self, file_url: str) -> DownloadedFile:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shadowob/connector",
-  "version": "1.1.6",
+  "version": "1.1.8",
   "description": "Shadow connector helpers for OpenClaw, Hermes Agent, and cc-connect",
   "type": "module",
   "main": "./dist/index.js",
@@ -22,6 +22,7 @@
   "files": [
     "dist",
     "hermes-shadowob-plugin",
+    "skills",
     "README.md"
   ],
   "keywords": [