@inline-chat/hermes-agent-adapter 0.0.12 → 0.0.14

package/README.md

@@ -147,7 +147,7 @@ uv run ./hermes plugins list --plain --no-bundled
 Expected local output includes:
 
 ```text
-enabled      user     0.0.12   inline-platform
+enabled      user     0.0.14   inline-platform
 ```
 
 ## Update Or Reinstall
@@ -170,10 +170,11 @@ mismatch, rerun the same command after rebuilding or upgrading the package.
 
 - Hermes Agent: requires the external user plugin registry and native platform
   plugin loader available in Hermes Agent `0.17.x`. This package was validated
-  against Hermes Agent `0.20.6` from source commit `31e41eed`.
+  against Hermes Agent `0.21.0` from source commit `29112bef` (tag
+  `v2026.8.31`).
 - Node.js: `>=20` is required for the bundled sidecar. Hermes-managed Node 22,
   system Node, or an explicit `INLINE_NODE_BIN` path all work.
-- Inline transport: the sidecar uses `@inline-chat/realtime-sdk@0.0.16` and is
+- Inline transport: the sidecar uses `@inline-chat/realtime-sdk@0.0.17` and is
   bundled into the npm package, so Hermes startup does not run `npm install`.
 - Live sends require a valid Inline user or bot token in `INLINE_TOKEN`,
   `INLINE_BOT_TOKEN`, `platforms.inline.token`, or `inline.token`.
@@ -313,6 +314,8 @@ Access control follows Hermes' native platform model:
 | `INLINE_CONNECT_RETRY_MAX_MS` | Maximum sidecar retry delay after repeated realtime startup failures. Defaults to `15000`. |
 | `INLINE_SIDECAR_PORT` | Fixed loopback port for the sidecar. Must be `1` through `65535`. Defaults to `8794`; `test-send` uses a random free port. |
 | `INLINE_SIDECAR_BIND` | Sidecar bind host. Must be loopback: `127.0.0.1`, `localhost`, or `::1`. Defaults to `127.0.0.1`. |
+| `INLINE_HERMES_SENTRY_DSN` | Explicitly enables adapter and sidecar error reporting to the configured collector. Reporting is disabled when unset. |
+| `INLINE_PLUGIN_TELEMETRY` | Set to `off`, `0`, or `false` to disable explicitly configured plugin error reporting. `DO_NOT_TRACK=1` is also honored. |
 | `platforms.inline.typing_indicator` | Hermes-native toggle for Inline typing/presence while a turn is running. Defaults to `true`; set to `false` to keep busy threads visually quiet. |
 | `platforms.inline.gateway_restart_notification` | Hermes-native toggle for gateway online/restarted notices. Defaults to `true`. |
 
@@ -399,6 +402,28 @@ the normal reply.
 The plugin id is `inline`, which is intentionally the same id an eventual
 bundled Hermes adapter should use.
 
+## Error Reporting And Privacy
+
+The Inline adapter and its supervised sidecar keep error reporting disabled
+unless the operator sets `INLINE_HERMES_SENTRY_DSN` to an explicit collector.
+When enabled, reports include the raw exception type and message, traceback
+paths, line/function locations, plugin release,
+operation name, runtime, OS, and architecture so maintainers can diagnose
+failures in subsequent releases.
+
+Reports do not attach Inline or Hermes message events, request bodies,
+user/chat/account identifiers, breadcrumbs, source context, or stack locals.
+Known token, password, authorization, sidecar credential, and secret-shaped
+values are redacted before upload. Inline's Sentry project also enables default
+server-side data scrubbing and IP-address scrubbing. Because dependency
+exception messages are preserved for diagnosis, they can still contain values
+the dependency itself chose to place in an error.
+
+Remove `INLINE_HERMES_SENTRY_DSN`, set `INLINE_PLUGIN_TELEMETRY=off`, or set
+`DO_NOT_TRACK=1` to disable both adapter and sidecar reporting. Reporting is
+best-effort, has a two-second network deadline, and never changes plugin success
+or failure behavior.
+
 ## Troubleshooting
 
 Run `inline-hermes doctor --json` first. It checks the installed plugin path,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inline-chat/hermes-agent-adapter",
-  "version": "0.0.12",
+  "version": "0.0.14",
   "description": "Hermes Agent platform adapter for Inline, with a native Python plugin and bundled Inline realtime sidecar.",
   "license": "Apache-2.0",
   "type": "module",
@@ -33,6 +33,7 @@
     "plugin/inline/cli.py",
     "plugin/inline/message_actions.py",
     "plugin/inline/plugin.yaml",
+    "plugin/inline/telemetry.py",
     "plugin/inline/tools.py",
     "plugin/inline/sidecar/index.mjs"
   ],
@@ -50,7 +51,7 @@
   },
   "scripts": {
     "build": "mkdir -p plugin/inline/sidecar && bun build ./src/install.ts --outdir dist --entry-naming '[name].js' --target=node --format=esm --packages=bundle && bun build ./src/sidecar/index.ts --outdir plugin/inline/sidecar --entry-naming 'index.mjs' --target=node --format=esm --packages=bundle && tsc -p tsconfig.json --emitDeclarationOnly",
-    "lint": "bunx oxlint --ignore-path ../.oxlintignore scripts/release-stage.mjs src/install.ts src/sidecar/contract.ts src/sidecar/index.ts src/sidecar/user-directory.ts src/sidecar/user-directory.test.ts tests/adapter-python.test.ts tests/install.test.ts tests/package-artifact.test.ts tests/sidecar-contract.test.ts tests/sidecar-runtime.test.ts vitest.config.ts",
+    "lint": "bunx oxlint --ignore-path ../.oxlintignore scripts/release-stage.mjs src/install.ts src/sidecar/contract.ts src/sidecar/index.ts src/sidecar/telemetry.ts src/sidecar/telemetry.test.ts src/sidecar/user-directory.ts src/sidecar/user-directory.test.ts tests/adapter-python.test.ts tests/install.test.ts tests/package-artifact.test.ts tests/sidecar-contract.test.ts tests/sidecar-runtime.test.ts tests/telemetry-python.test.ts vitest.config.ts",
     "pretest": "bun run build",
     "prepack": "bun run build",
     "prepublishOnly": "bun run check",
@@ -61,7 +62,7 @@
     "check": "bun run typecheck && bun run lint && bun run test"
   },
   "dependencies": {
-    "@inline-chat/realtime-sdk": "0.0.16",
+    "@inline-chat/realtime-sdk": "0.0.17",
     "yaml": "2.9.0"
   },
   "devDependencies": {
@@ -81,7 +82,7 @@
     },
     "machineSetupProtocol": 1,
     "minHermesVersion": "0.17.0",
-    "testedHermesVersion": "0.20.6",
-    "testedHermesCommit": "31e41eed"
+    "testedHermesVersion": "0.21.0",
+    "testedHermesCommit": "29112bef"
   }
 }

package/plugin/inline/adapter.py

@@ -55,6 +55,7 @@ from .message_actions import (
     parse_inline_agent_action_reply_target,
     resolve_inline_message_action_ownership,
 )
+from .telemetry import capture_plugin_error
 
 logger = logging.getLogger(__name__)
 
@@ -600,6 +601,36 @@ def _inline_menu_commands(max_commands: int = _INLINE_COMMAND_LIMIT) -> tuple[Li
     return commands, hidden_count + hidden_local + skipped
 
 
+def _inline_skill_catalog() -> List[Dict[str, Any]]:
+    """Return installed, enabled Hermes skills in the Bot API catalog shape."""
+    from tools.skills_tool import _find_all_skills, _sort_skills
+
+    published: List[Dict[str, Any]] = []
+    seen: set[str] = set()
+    for skill in _sort_skills(_find_all_skills(skip_disabled=False)):
+        if len(published) >= 250:
+            break
+        key = str(skill.get("name") or "").strip()
+        if not key or _utf16_length(key) > 256 or key in seen:
+            continue
+        # At most two UTF-16 code units per Python Unicode scalar keeps the
+        # 4,000-unit validation bound even for non-BMP descriptions.
+        description = str(skill.get("description") or "").strip()[:2000].rstrip()
+        seen.add(key)
+        published.append({
+            "key": key,
+            "name": key,
+            **({"description": description} if description else {}),
+            "sort_order": len(published),
+        })
+    return published
+
+
+def _utf16_length(value: str) -> int:
+    """Match JavaScript and Bot API string-length validation."""
+    return len(value.encode("utf-16-le", errors="surrogatepass")) // 2
+
+
 def _token_value(raw: Any) -> str:
     if raw is None:
         return ""
@@ -971,6 +1002,18 @@ class InlineAdapter(BasePlatformAdapter):
         self._context_backfill_seen: "OrderedDict[str, float]" = OrderedDict()
         self._reply_thread_overrides = self._load_reply_thread_overrides()
 
+    def _report_error(self, operation: str, error: BaseException, *, handled: bool = True) -> None:
+        try:
+            capture_plugin_error(
+                operation,
+                error,
+                handled=handled,
+                secrets=(self._token, self._sidecar_token),
+            )
+        except Exception:
+            # Observability must never alter adapter behavior.
+            pass
+
     @staticmethod
     def _parse_id_set(raw: Any) -> set[str]:
         if raw is None:
@@ -1014,6 +1057,7 @@ class InlineAdapter(BasePlatformAdapter):
         except FileNotFoundError:
             return {}
         except Exception as exc:
+            self._report_error("settings.load", exc)
             logger.warning("[inline] failed to load Inline adapter settings: %s", exc)
             return {}
         raw = data.get("reply_threads") if isinstance(data, dict) else None
@@ -1045,6 +1089,7 @@ class InlineAdapter(BasePlatformAdapter):
             tmp_path.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n", encoding="utf-8")
             tmp_path.replace(self._settings_path)
         except Exception as exc:
+            self._report_error("settings.save", exc)
             logger.warning("[inline] failed to save Inline adapter settings: %s", exc)
 
     def _reply_thread_mode_for_chat(self, chat_id: str, parent_chat_id: Optional[str] = None) -> str:
@@ -1393,6 +1438,7 @@ class InlineAdapter(BasePlatformAdapter):
         except asyncio.CancelledError:
             raise
         except Exception as exc:
+            self._report_error("settings.answer", exc)
             logger.warning("[inline] agent settings answer expired: %s", exc)
             return False
 
@@ -1416,6 +1462,7 @@ class InlineAdapter(BasePlatformAdapter):
                 context = await self._bot_settings_context(event)
                 response = {"result": {"oneofKind": "document", "document": self._bot_settings_document(context)}}
         except Exception as exc:
+            self._report_error("settings.load", exc)
             logger.warning("[inline] failed to load Hermes agent settings: %s", exc)
             response = self._bot_settings_problem(_INLINE_BOT_SETTINGS_FAILED, "Hermes could not load settings.")
         answered = await self._answer_bot_settings(request_id, response)
@@ -1530,6 +1577,7 @@ class InlineAdapter(BasePlatformAdapter):
         except ValueError as exc:
             response = self._bot_settings_problem(_INLINE_BOT_SETTINGS_INVALID_VALUE, str(exc).capitalize())
         except Exception as exc:
+            self._report_error("settings.update", exc)
             logger.warning("[inline] failed to update Hermes agent settings: %s", exc)
             response = self._bot_settings_problem(_INLINE_BOT_SETTINGS_FAILED, "Hermes could not update this setting.")
         answered = await self._answer_bot_settings(request_id, response)
@@ -1776,6 +1824,7 @@ class InlineAdapter(BasePlatformAdapter):
         try:
             await self._sidecar_call("/follow-mode", {"target": target, "mode": mode})
         except Exception as exc:
+            self._report_error("follow_mode.update", exc)
             logger.warning("[inline] /%s failed for chat %s: %s", command, chat_id, exc)
             await self.send(
                 chat_id,
@@ -1814,6 +1863,7 @@ class InlineAdapter(BasePlatformAdapter):
             try:
                 await self._start_sidecar()
             except Exception as exc:
+                self._report_error("sidecar.start", exc, handled=False)
                 self._set_fatal_error("SIDECAR_FAILED", f"failed to start Inline sidecar: {exc}", retryable=True)
                 await self._stop_sidecar()
                 await self._http_client.aclose()
@@ -1965,8 +2015,6 @@ class InlineAdapter(BasePlatformAdapter):
                 self._sidecar_supervisor_task = None
 
     def _schedule_bot_command_sync(self) -> None:
-        if not self._sync_commands:
-            return
         if self._command_sync_task is not None and not self._command_sync_task.done():
             return
         self._command_sync_task = asyncio.get_event_loop().create_task(self._run_bot_command_sync())
@@ -1974,9 +2022,11 @@ class InlineAdapter(BasePlatformAdapter):
     async def _run_bot_command_sync(self) -> None:
         try:
             await self._sync_bot_commands()
+            await self._sync_bot_skills()
         except asyncio.CancelledError:
             raise
         except Exception as exc:
+            self._report_error("commands_and_skills.sync", exc)
             logger.warning("[inline] bot command sync failed: %s", exc)
         finally:
             if asyncio.current_task() is self._command_sync_task:
@@ -1996,8 +2046,20 @@ class InlineAdapter(BasePlatformAdapter):
             hidden_suffix = f", {hidden_count} hidden" if hidden_count else ""
             logger.info("[inline] bot commands synced (%d command%s%s)", len(synced), "" if len(synced) == 1 else "s", hidden_suffix)
         except Exception as exc:
+            self._report_error("commands.sync", exc)
             logger.warning("[inline] bot command sync failed: %s", exc)
 
+    async def _sync_bot_skills(self) -> None:
+        if self._http_client is None:
+            return
+        try:
+            skills = _inline_skill_catalog()
+            await self._call_bot_api("setMySkills", {"skills": skills})
+            logger.info("[inline] bot skills synced (%d skill%s)", len(skills), "" if len(skills) == 1 else "s")
+        except Exception as exc:
+            self._report_error("skills.sync", exc)
+            logger.warning("[inline] bot skill sync failed: %s", exc)
+
     async def _set_bot_commands_with_retry(self, commands: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
         try:
             await self._call_bot_api("setMyCommands", {"commands": commands})
@@ -2087,6 +2149,7 @@ class InlineAdapter(BasePlatformAdapter):
             try:
                 completed.result()
             except Exception as exc:
+                self._report_error("settings.task", exc)
                 logger.warning("[inline] agent settings task failed: %s", exc)
 
         task.add_done_callback(finished)
@@ -2114,6 +2177,7 @@ class InlineAdapter(BasePlatformAdapter):
             except Exception as exc:
                 if not self._inbound_running:
                     break
+                self._report_error("inbound.stream", exc)
                 logger.warning("[inline] inbound stream dropped (%s); reconnecting in %.1fs", exc, backoff)
                 await asyncio.sleep(backoff)
                 backoff = min(backoff * 2, 30.0)
@@ -2367,8 +2431,13 @@ class InlineAdapter(BasePlatformAdapter):
                 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_instructions:
+                        channel_prompt = self._merge_channel_prompt(channel_prompt, agent_instructions)
+                    elif not agent_skill:
+                        channel_prompt = self._merge_channel_prompt(
+                            channel_prompt,
+                            f'You are a specialized agent named "{agent_name}". Proceed with the user\'s request.',
+                        )
                 if agent_skill:
                     auto_skill = list(dict.fromkeys([*(auto_skill or []), agent_skill]))
             except Exception as exc:
@@ -3749,7 +3818,8 @@ class InlineAdapter(BasePlatformAdapter):
                     return True
                 await self._finish_action(event, "Type your answer", "Type your answer:")
                 return True
-            except Exception:
+            except Exception as exc:
+                self._report_error("action.clarify_other", exc)
                 logger.exception("[inline] clarify other failed")
                 return True
         try:
@@ -3767,7 +3837,8 @@ class InlineAdapter(BasePlatformAdapter):
                 self._clarify_choices.pop(clarify_id, None)
                 await self._finish_action(event, "Prompt expired", "Clarification expired.")
             return True
-        except Exception:
+        except Exception as exc:
+            self._report_error("action.clarify", exc)
             logger.exception("[inline] clarify action failed")
             return True
 
@@ -3800,7 +3871,8 @@ class InlineAdapter(BasePlatformAdapter):
             toast, text = labels[choice]
             await self._finish_action(event, toast, text)
             return True
-        except Exception:
+        except Exception as exc:
+            self._report_error("action.approval", exc)
             logger.exception("[inline] approval action failed")
             return True
 
@@ -3823,7 +3895,8 @@ class InlineAdapter(BasePlatformAdapter):
             text = str(result or ("Cancelled." if choice == "cancel" else "Recorded."))
             await self._finish_action(event, "Recorded", text)
             return True
-        except Exception:
+        except Exception as exc:
+            self._report_error("action.slash_confirm", exc)
             logger.exception("[inline] slash confirm action failed")
             return True
 
@@ -3867,7 +3940,8 @@ class InlineAdapter(BasePlatformAdapter):
             self._thread_action_sessions.pop(session_id, None)
             await self._answer_action(interaction_id, f"Reply threads: {mode}")
             return True
-        except Exception:
+        except Exception as exc:
+            self._report_error("action.thread", exc)
             logger.exception("[inline] thread action failed")
             await self._answer_action(interaction_id, "Thread setting failed")
             return True
@@ -3957,6 +4031,7 @@ class InlineAdapter(BasePlatformAdapter):
                 result_text = await result_text
             result_text = str(result_text or "Selection applied.")
         except Exception as exc:
+            self._report_error("action.choice_picker", exc)
             logger.error("[inline] choice picker selection failed (%s)", type(exc).__name__)
             result_text = "Selection failed; try again."
             failed = True
@@ -3995,7 +4070,8 @@ class InlineAdapter(BasePlatformAdapter):
             tmp_path = response_path.with_suffix(".tmp")
             tmp_path.write_text(answer, encoding="utf-8")
             tmp_path.replace(response_path)
-        except Exception:
+        except Exception as exc:
+            self._report_error("action.update_prompt", exc)
             logger.exception("[inline] failed to write Hermes update response")
             await self._answer_action(interaction_id, "Response failed; try again")
             return True
@@ -4171,6 +4247,7 @@ class InlineAdapter(BasePlatformAdapter):
                 result_text = await result_text
             result_text = str(result_text or "Model switched.")
         except Exception as exc:
+            self._report_error("action.model_picker", exc)
             logger.error("[inline] model picker switch failed (%s)", type(exc).__name__)
             result_text = "Model switch failed; try again."
             failed = True
@@ -4600,6 +4677,7 @@ class InlineAdapter(BasePlatformAdapter):
             result = data.get("result") or {}
             return str(result.get("chatId") or "") or None
         except Exception as exc:
+            self._report_error("thread.create", exc)
             logger.debug("[inline] create handoff thread failed: %s", exc)
             return None
 
@@ -4779,7 +4857,7 @@ class InlineAdapter(BasePlatformAdapter):
             ]}]},
         })
         if not result.success:
-            # Hermes 0.20.6 treats any non-raising hook call as delivered and
+            # Hermes treats any non-raising hook call as delivered and
             # otherwise suppresses its plaintext /approve and /deny fallback.
             raise RuntimeError(result.error or "failed to send Inline update prompt")
         self._remember(self._update_prompt_sessions, prompt_id, {
@@ -5011,6 +5089,8 @@ class InlineAdapter(BasePlatformAdapter):
                 raw_response=result,
             )
         except InlineSidecarError as exc:
+            if exc.error_kind == "unknown":
+                self._report_error("sidecar.send", exc)
             return _send_result(
                 success=False,
                 error=str(exc),
@@ -5019,6 +5099,7 @@ class InlineAdapter(BasePlatformAdapter):
                 error_kind=exc.error_kind,
             )
         except Exception as exc:
+            self._report_error("sidecar.send", exc)
             return _send_result(success=False, error=str(exc), retryable=self._is_retryable_error(str(exc)))
 
     async def _sidecar_call(self, path: str, body: Dict[str, Any]) -> Dict[str, Any]:

package/plugin/inline/cli.py

@@ -7,6 +7,7 @@ the plugin has already been discovered by Hermes.
 from __future__ import annotations
 
 import argparse
+import hashlib
 import json
 import os
 import re
@@ -26,7 +27,7 @@ _CLI_INSTALL_URL = "https://inline.chat/cli/install.sh"
 _MAX_TOKEN_BYTES = 16 * 1024
 _MAX_PROBE_RESPONSE_BYTES = 64 * 1024
 _MACHINE_SETUP_PROTOCOL_VERSION = 1
-_PROBE_USER_AGENT = "inline-hermes-agent-adapter/0.0.12"
+_PROBE_USER_AGENT = "inline-hermes-agent-adapter/0.0.14"
 _ENV_REFERENCE_RE = re.compile(r"^\$\{([A-Za-z_][A-Za-z0-9_]*)\}$")
 
 
@@ -463,6 +464,7 @@ def _status(args) -> int:
         "sidecar": sidecar,
         "node": node,
         "probeRequested": probe_requested,
+        "gateway": _gateway_status(),
         **({"probe": probe} if probe is not None else {}),
     }
     if getattr(args, "json", False):
@@ -480,6 +482,51 @@ def _status(args) -> int:
     return 0 if runtime_usable and (not probe_requested or ready) else 1
 
 
+def _gateway_status() -> dict:
+    """Project local runtime facts without changing the credential-status contract."""
+    unavailable = {"supported": False, "ready": False, "reason": "runtime_status_unavailable"}
+    try:
+        from gateway.status import read_runtime_status, get_runtime_status_running_pid
+        from hermes_constants import get_hermes_home
+
+        runtime = read_runtime_status()
+        # Also validate this helper contract for an absent runtime: older hosts
+        # lack expected_home and must not claim support until after installation.
+        pid = get_runtime_status_running_pid(runtime if isinstance(runtime, dict) else {}, expected_home=get_hermes_home())
+        if not isinstance(runtime, dict):
+            return {"supported": True, "ready": False, "reason": "missing_status"}
+        # Return only an opaque generation, never process IDs or raw state.
+        start_time = runtime.get("start_time")
+        valid_identity = type(pid) is int and pid > 0 and type(start_time) is int and start_time >= 0
+        if pid and not valid_identity:
+            return {"supported": False, "ready": False, "reason": "runtime_identity_unavailable"}
+        generation = hashlib.sha256(f"inline-gateway:{pid}:{start_time}".encode()).hexdigest() if valid_identity else None
+        state = runtime.get("gateway_state")
+        platforms = runtime.get("platforms")
+        inline = platforms.get("inline") if isinstance(platforms, dict) else None
+        platform_state = inline.get("state") if isinstance(inline, dict) else None
+        state = state if state in ("starting", "running", "draining", "stopping", "stopped", "startup_failed") else "unknown"
+        platform_state = platform_state if platform_state in ("connected", "connecting", "retrying", "fatal", "disconnected") else "unknown"
+        if pid and isinstance(inline, dict) and ("writer_pid" not in inline or "writer_start_time" not in inline):
+            return {"supported": False, "ready": False, "reason": "runtime_writer_identity_unavailable"}
+        # Runtime status can retain platform entries from the prior process.
+        # Only the current process's own connected projection is readiness proof.
+        writer_matches = isinstance(inline, dict) and inline.get("writer_pid") == pid and inline.get("writer_start_time") == start_time
+        ready = generation is not None and writer_matches and state == "running" and platform_state == "connected"
+        return {
+            "supported": True,
+            "ready": ready,
+            **({"generation": generation} if generation is not None else {}),
+            "gatewayState": state,
+            "platformState": platform_state,
+            "reason": "ready" if ready else "stale_pid" if not pid else "gateway_not_running" if state != "running" else "platform_status_stale" if not writer_matches else "platform_not_connected",
+        }
+    except Exception:
+        # Older Hermes versions may not expose the helpers. Never return raw
+        # runtime files or exceptions: they can contain provider/credential data.
+        return unavailable
+
+
 def _plugin_version() -> str:
     """Read the separately installed plugin version without package-manager state."""
     try:

package/plugin/inline/plugin.yaml

@@ -1,7 +1,7 @@
 name: inline-platform
 label: Inline
 kind: platform
-version: 0.0.12
+version: 0.0.14
 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