@inline-chat/hermes-agent-adapter 0.0.7 → 0.0.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inline-chat/hermes-agent-adapter",
-  "version": "0.0.7",
+  "version": "0.0.8",
   "description": "Hermes Agent platform adapter for Inline, with a native Python plugin and bundled Inline realtime sidecar.",
   "license": "Apache-2.0",
   "type": "module",
@@ -60,7 +60,7 @@
     "check": "bun run typecheck && bun run lint && bun run test"
   },
   "dependencies": {
-    "@inline-chat/realtime-sdk": "0.0.14",
+    "@inline-chat/realtime-sdk": "0.0.15",
     "yaml": "2.9.0"
   },
   "devDependencies": {
@@ -75,9 +75,12 @@
   "inlineHermes": {
     "pluginId": "inline",
     "pluginPath": "plugin/inline",
+    "install": {
+      "npmSpec": "@inline-chat/hermes-agent-adapter"
+    },
     "machineSetupProtocol": 1,
     "minHermesVersion": "0.17.0",
-    "testedHermesVersion": "0.19.1",
-    "testedHermesCommit": "cc4cab2"
+    "testedHermesVersion": "0.20.0",
+    "testedHermesCommit": "3c27eb6"
   }
 }

package/plugin/inline/adapter.py

@@ -69,6 +69,8 @@ _DEFAULT_OBSERVED_CONTEXT_LIMIT = 20
 _MAX_OBSERVED_CONTEXT_LIMIT = 100
 _MAX_CONTEXT_HISTORY_LIMIT = 20
 _MAX_CONTEXT_REQUEST_LIMIT = 100
+_JOIN_MENTION_LOOKBACK_SECONDS = 60
+_JOIN_HISTORY_PAGE_LIMIT = 100
 _CONTEXT_MESSAGE_TEXT_LIMIT = 360
 _OBSERVED_CONTEXT_CACHE_MAX_SIZE = 512
 _STATE_DIR = Path.home() / ".hermes" / "inline"
@@ -855,6 +857,7 @@ class InlineAdapter(BasePlatformAdapter):
         self._me_id: Optional[str] = None
         self._me_username: Optional[str] = None
         self._seen_messages: Dict[str, float] = {}
+        self._seen_message_instances: Dict[str, float] = {}
         self._clarify_choices: "OrderedDict[str, List[str]]" = OrderedDict()
         self._clarify_sessions: "OrderedDict[str, str]" = OrderedDict()
         self._approval_sessions: "OrderedDict[str, str]" = OrderedDict()
@@ -2048,7 +2051,12 @@ class InlineAdapter(BasePlatformAdapter):
             if self._system_events:
                 await self._dispatch_message(event, edit=True)
             return
-        if kind in {"message.delete", "message.history.clear", "chat.participant.add", "chat.participant.delete"}:
+        if kind == "chat.participant.add":
+            if await self._recover_self_join_mentions(event):
+                return
+            await self._dispatch_system_event(event)
+            return
+        if kind in {"message.delete", "message.history.clear", "chat.participant.delete"}:
             await self._dispatch_system_event(event)
             return
         if kind != "message.new":
@@ -2068,6 +2076,28 @@ class InlineAdapter(BasePlatformAdapter):
                 del self._seen_messages[stale]
         return False
 
+    def _is_duplicate_message_instance(self, chat_id: str, msg: Dict[str, Any], event: Dict[str, Any]) -> bool:
+        message_date = str(msg.get("date") or event.get("date") or "").strip()
+        content = json.dumps({
+            "fromId": msg.get("fromId"),
+            "message": msg.get("message"),
+            "entities": msg.get("entities"),
+            "media": msg.get("media"),
+        }, sort_keys=True, default=str, separators=(",", ":"))
+        fingerprint = hashlib.sha256(content.encode("utf-8")).hexdigest()[:16]
+        key = f"{chat_id}:{str(msg.get('id') or '')}:{message_date}:{fingerprint}"
+        now = time.time()
+        old = self._seen_message_instances.get(key)
+        if old is not None and now - old < _DEDUP_WINDOW_SECONDS:
+            return True
+        if key in self._seen_message_instances:
+            del self._seen_message_instances[key]
+        self._seen_message_instances[key] = now
+        if len(self._seen_message_instances) > _DEDUP_MAX_SIZE:
+            for stale in list(self._seen_message_instances.keys())[: len(self._seen_message_instances) - _DEDUP_MAX_SIZE]:
+                del self._seen_message_instances[stale]
+        return False
+
     async def _dispatch_message(self, event: Dict[str, Any], *, edit: bool = False) -> None:
         msg = event.get("message") or {}
         msg_id = str(msg.get("id") or "")
@@ -2089,6 +2119,8 @@ class InlineAdapter(BasePlatformAdapter):
                 dedup_key = f"new:{chat_id}:msg:{msg_id}"
         if self._is_duplicate(dedup_key):
             return
+        if not edit and self._is_duplicate_message_instance(chat_id, msg, event):
+            return
         from_id = str(msg.get("fromId") or "")
         if msg.get("out") or (self._me_id and from_id == self._me_id):
             return
@@ -2209,6 +2241,21 @@ class InlineAdapter(BasePlatformAdapter):
                 parent_message_id = msg_id
 
         channel_prompt, auto_skill = self._resolve_thread_bindings(chat_id, thread_id, parent_chat_id)
+        mentioned_agent_id = self._mentioned_agent_id(msg)
+        if mentioned_agent_id:
+            try:
+                resolved_agent = await self._sidecar_call("/get-agent", {"agentId": mentioned_agent_id})
+                agent = resolved_agent.get("agent") if isinstance(resolved_agent.get("agent"), dict) else {}
+                agent_name = str(agent.get("name") or "").strip()
+                agent_instructions = str(agent.get("instructions") or "").strip()
+                agent_skill = str(agent.get("skillKey") or agent.get("skill_key") or "").strip()
+                if agent_name:
+                    specialization = agent_instructions or f'You are a specialized agent named "{agent_name}".'
+                    channel_prompt = self._merge_channel_prompt(channel_prompt, specialization)
+                if agent_skill:
+                    auto_skill = [agent_skill]
+            except Exception as exc:
+                logger.warning("[inline] failed to resolve mentioned Agent %s: %s", mentioned_agent_id, exc)
         entity_text = self._inline_entity_text(msg, str(msg.get("message") or ""))
         parent_chat_info: Dict[str, Any] = {}
         if parent_chat_id:
@@ -2298,6 +2345,92 @@ class InlineAdapter(BasePlatformAdapter):
             timestamp=self._timestamp(event.get("date") or msg.get("date")),
         ))
 
+    def _message_explicitly_mentions_me(self, msg: Dict[str, Any]) -> bool:
+        if not self._me_id:
+            return False
+        if bool(msg.get("mentioned")):
+            return True
+        for entity in self._message_entities(msg):
+            if self._entity_kind(entity) != "mention":
+                continue
+            payload = self._entity_payload(entity, "mention")
+            if self._entity_id(payload, "userId") == self._me_id:
+                return True
+        username = str(self._me_username or "").strip().lstrip("@")
+        text = str(msg.get("message") or "")
+        if not username or not text:
+            return False
+        return bool(re.search(rf"(^|\s)@{re.escape(username)}(?=$|[\s,.:;!?])", text, re.IGNORECASE))
+
+    async def _recover_self_join_mentions(self, event: Dict[str, Any]) -> bool:
+        participant = event.get("participant") if isinstance(event.get("participant"), dict) else {}
+        if not self._me_id or str(participant.get("userId") or "").strip() != self._me_id:
+            return False
+
+        chat_id = str(event.get("chatId") or "").strip()
+        joined_at = _to_int(participant.get("date") or event.get("date"))
+        if not chat_id or joined_at is None or joined_at <= 0:
+            logger.warning("[inline] cannot recover join mentions without chat and participant date")
+            return True
+
+        cutoff = joined_at - _JOIN_MENTION_LOOKBACK_SECONDS
+        messages: Dict[str, Dict[str, Any]] = {}
+        anchor_id: Optional[str] = None
+        while True:
+            body: Dict[str, Any] = {
+                "target": _target_from_chat_id(chat_id),
+                "limit": _JOIN_HISTORY_PAGE_LIMIT,
+            }
+            if anchor_id:
+                body["anchorId"] = anchor_id
+            try:
+                data = await self._sidecar_call("/history", body)
+            except Exception as exc:
+                logger.warning("[inline] join mention history unavailable for chat %s: %s", chat_id, exc)
+                return True
+            page = (data.get("result") or {}).get("messages") or []
+            page = [message for message in page if isinstance(message, dict)]
+            if not page:
+                break
+
+            oldest: Optional[Dict[str, Any]] = None
+            added = 0
+            for message in page:
+                message_id = str(message.get("id") or "").strip()
+                message_date = _to_int(message.get("date"))
+                if not message_id or message_date is None:
+                    continue
+                key = f"{message_id}:{message_date}"
+                if key not in messages:
+                    messages[key] = message
+                    added += 1
+                if oldest is None or message_date < int(oldest["date"]):
+                    oldest = {**message, "date": message_date}
+            if oldest is None or int(oldest["date"]) < cutoff or len(page) < _JOIN_HISTORY_PAGE_LIMIT or added == 0:
+                break
+            anchor_id = str(oldest.get("id") or "").strip() or None
+            if not anchor_id:
+                break
+
+        candidates = []
+        for message in messages.values():
+            message_date = _to_int(message.get("date"))
+            if message_date is None or message_date < cutoff or message_date > joined_at:
+                continue
+            if str(message.get("fromId") or "") == self._me_id:
+                continue
+            if self._message_explicitly_mentions_me(message):
+                candidates.append(message)
+        candidates.sort(key=lambda message: (_to_int(message.get("date")) or 0, str(message.get("id") or "")))
+
+        for message in candidates:
+            await self._dispatch_message({
+                "kind": "message.new",
+                "chatId": chat_id,
+                "message": {**message, "mentioned": True},
+            })
+        return True
+
     async def _dispatch_reaction(self, event: Dict[str, Any], *, added: bool) -> None:
         reaction = event.get("reaction") if isinstance(event.get("reaction"), dict) else {}
         chat_id = str(event.get("chatId") or reaction.get("chatId") or "")
@@ -2770,6 +2903,19 @@ class InlineAdapter(BasePlatformAdapter):
             parts.append(f"+{len(entities) - _INLINE_ENTITY_LIMIT} more")
         return " | ".join(parts) if parts else None
 
+    def _mentioned_agent_id(self, msg: Dict[str, Any]) -> Optional[str]:
+        for entity in self._message_entities(msg):
+            if self._entity_kind(entity) != "mention":
+                continue
+            payload = self._entity_payload(entity, "mention")
+            user_id = self._entity_id(payload, "userId")
+            if self._me_id and user_id != self._me_id:
+                continue
+            agent_id = self._entity_id(payload, "agentId")
+            if agent_id:
+                return agent_id
+        return None
+
     @staticmethod
     def _merge_channel_prompt(*parts: Optional[str]) -> Optional[str]:
         merged = [str(part).strip() for part in parts if str(part or "").strip()]

package/plugin/inline/cli.py

@@ -335,16 +335,16 @@ def _run_inline_json(inline_bin: str, args: list[str]) -> tuple[dict | None, str
 
 def register_cli(parser: argparse.ArgumentParser) -> None:
     subs = parser.add_subparsers(dest="inline_command", required=False)
-    setup = subs.add_parser("setup", help="Configure Inline")
-    setup.add_argument("--non-interactive", action="store_true")
-    setup.add_argument("--token-stdin", action="store_true")
-    setup.add_argument("--owner-user-id")
-    setup.add_argument("--access", choices=["owner", "allowlist", "open", "disabled"], default="owner")
-    setup.add_argument("--allow-user", action="append", default=[], type=_positive_user_id)
-    setup.add_argument("--json", action="store_true")
-    status = subs.add_parser("status", help="Show Inline adapter status")
-    status.add_argument("--json", action="store_true")
-    status.add_argument("--probe", action="store_true")
+    setup = subs.add_parser("setup", help="Configure Inline", description="Configure the Inline platform and its access policy.")
+    setup.add_argument("--non-interactive", action="store_true", help="Run prompt-free machine setup; requires the token on stdin.")
+    setup.add_argument("--token-stdin", action="store_true", help="Read one bounded Inline token from stdin instead of argv.")
+    setup.add_argument("--owner-user-id", help="Positive Inline user ID that owns the configured bot.")
+    setup.add_argument("--access", choices=["owner", "allowlist", "open", "disabled"], default="owner", help="Who may invoke Hermes through Inline (default: owner).")
+    setup.add_argument("--allow-user", action="append", default=[], type=_positive_user_id, help="Additional positive Inline user ID to allow; repeatable.")
+    setup.add_argument("--json", action="store_true", help="Print compact machine-readable setup output.")
+    status = subs.add_parser("status", help="Show Inline adapter status", description="Check Inline configuration, sidecar, Node runtime, and optional credential identity.")
+    status.add_argument("--json", action="store_true", help="Print compact machine-readable status output.")
+    status.add_argument("--probe", action="store_true", help="Verify the configured Inline credential and bot identity.")
     parser.set_defaults(func=dispatch)
 
 
@@ -418,15 +418,27 @@ def _status(args) -> int:
     configured = bool(token)
     probe_requested = bool(getattr(args, "probe", False))
     probe = _probe_inline_token(token) if configured and probe_requested else None
-    ready = configured and (not probe_requested or bool(probe and probe.get("ok")))
+    node = _node_status()
+    sidecar = _sidecar_status(node)
+    sidecar_bundled = bool(
+        sidecar["exists"]
+        and sidecar["regularFile"]
+        and sidecar["readable"]
+        and sidecar["size"] > 0
+    )
+    runtime_usable = bool(sidecar["ok"] and node["ok"])
+    ready = runtime_usable and configured and (not probe_requested or bool(probe and probe.get("ok")))
     result = {
         "ok": ready,
+        "ready": ready,
         "action": "inline.status",
         "setupProtocolVersion": _MACHINE_SETUP_PROTOCOL_VERSION,
         "pluginVersion": _plugin_version(),
         "configured": configured,
-        "sidecarBundled": _SIDECAR_ENTRY.exists(),
-        "node": _node_status(),
+        "runtimeUsable": runtime_usable,
+        "sidecarBundled": sidecar_bundled,
+        "sidecar": sidecar,
+        "node": node,
         "probeRequested": probe_requested,
         **({"probe": probe} if probe is not None else {}),
     }
@@ -434,14 +446,15 @@ def _status(args) -> int:
         print(json.dumps(result, separators=(",", ":")))
     else:
         print(f"Inline configured: {'yes' if configured else 'no'}")
-        print(f"Inline sidecar bundled: {'yes' if _SIDECAR_ENTRY.exists() else 'no'}")
-        print(f"Node available: {_node_status()}")
+        print(f"Inline sidecar usable: {'yes' if sidecar['ok'] else 'no'}")
+        print(f"Node available: {_node_status_text(node)}")
+        print(f"Inline runtime ready: {'yes' if ready else 'no'}")
         if not configured:
             print("Next: run `hermes inline setup` for guided bot setup.")
         elif probe_requested:
             print(f"Inline credential probe: {'ready' if ready else 'failed'}")
         print("Advanced diagnostics: inline-hermes doctor --json")
-    return 0 if not probe_requested or ready else 1
+    return 0 if runtime_usable and (not probe_requested or ready) else 1
 
 
 def _plugin_version() -> str:
@@ -514,10 +527,17 @@ def _find_node_bin() -> str | None:
     return shutil.which("node")
 
 
-def _node_status() -> str:
+def _node_status() -> dict:
     node_bin = _find_node_bin()
     if not node_bin:
-        return "no"
+        return {
+            "ok": False,
+            "path": None,
+            "version": None,
+            "major": None,
+            "minimumMajor": _MIN_NODE_MAJOR,
+            "error": "Node.js was not found.",
+        }
     try:
         result = subprocess.run(
             [node_bin, "--version"],
@@ -528,12 +548,88 @@ def _node_status() -> str:
             check=False,
         )
     except Exception as exc:
-        return f"no ({exc})"
+        return {
+            "ok": False,
+            "path": node_bin,
+            "version": None,
+            "major": None,
+            "minimumMajor": _MIN_NODE_MAJOR,
+            "error": f"Node.js could not run: {exc}",
+        }
     version = (result.stdout or result.stderr or "").strip()
     if result.returncode != 0:
-        return f"no ({version or f'exited with status {result.returncode}'})"
+        return {
+            "ok": False,
+            "path": node_bin,
+            "version": version or None,
+            "major": None,
+            "minimumMajor": _MIN_NODE_MAJOR,
+            "error": f"Node.js exited with status {result.returncode}.",
+        }
     match = re.search(r"\bv?(\d+)(?:\.\d+){0,2}\b", version)
-    major = int(match.group(1)) if match else 0
-    if major < _MIN_NODE_MAJOR:
-        return f"no ({version or 'unknown version'}, requires >=20)"
-    return f"yes ({version})"
+    major = int(match.group(1)) if match else None
+    ok = major is not None and major >= _MIN_NODE_MAJOR
+    return {
+        "ok": ok,
+        "path": node_bin,
+        "version": version or None,
+        "major": major,
+        "minimumMajor": _MIN_NODE_MAJOR,
+        "error": None if ok else f"Node.js {version or 'version'} is incompatible; requires >= {_MIN_NODE_MAJOR}.",
+    }
+
+
+def _sidecar_status(node: dict) -> dict:
+    try:
+        info = _SIDECAR_ENTRY.stat()
+        exists = True
+        regular_file = _SIDECAR_ENTRY.is_file()
+        readable = os.access(_SIDECAR_ENTRY, os.R_OK)
+        size = info.st_size
+    except OSError:
+        exists = False
+        regular_file = False
+        readable = False
+        size = 0
+
+    syntax_checked = False
+    syntax_ok = False
+    error = None
+    if not exists:
+        error = "The packaged Inline sidecar is missing."
+    elif not regular_file or not readable or size <= 0:
+        error = "The packaged Inline sidecar is not a readable non-empty file."
+    elif node.get("ok"):
+        syntax_checked = True
+        try:
+            checked = subprocess.run(
+                [str(node["path"]), "--check", str(_SIDECAR_ENTRY)],
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                timeout=10,
+                check=False,
+            )
+            syntax_ok = checked.returncode == 0
+            if not syntax_ok:
+                error = "The packaged Inline sidecar failed Node.js syntax validation."
+        except (OSError, subprocess.TimeoutExpired):
+            error = "The packaged Inline sidecar could not be validated by Node.js."
+    else:
+        error = "The packaged Inline sidecar cannot run without compatible Node.js."
+
+    return {
+        "ok": bool(exists and regular_file and readable and size > 0 and syntax_checked and syntax_ok),
+        "exists": exists,
+        "regularFile": regular_file,
+        "readable": readable,
+        "size": size,
+        "syntaxChecked": syntax_checked,
+        "syntaxOk": syntax_ok,
+        "error": error,
+    }
+
+
+def _node_status_text(node: dict) -> str:
+    if node.get("ok"):
+        return f"yes ({node.get('version') or 'unknown version'})"
+    return f"no ({node.get('error') or 'unknown error'})"

package/plugin/inline/plugin.yaml

@@ -1,7 +1,7 @@
 name: inline-platform
 label: Inline
 kind: platform
-version: 0.0.7
+version: 0.0.8
 description: >
   Inline platform adapter for Hermes Agent. The adapter runs as a native
   Hermes Python platform plugin and supervises a local Node sidecar that uses