@inline-chat/hermes-agent-adapter 0.0.6 → 0.0.8-alpha.0

package/README.md

@@ -81,7 +81,7 @@ Set up the Inline Hermes Agent adapter on this machine.
 Constraints:
 - Do not read, print, or edit .env files.
 - Do not print Inline tokens or other secrets.
-- Use an Inline token from INLINE_TOKEN or INLINE_BOT_TOKEN; if neither is present, stop and point me to https://inline.chat/docs/creating-a-bot.
+- Use an Inline token from INLINE_TOKEN or INLINE_BOT_TOKEN when already available; otherwise use Hermes's guided setup without exposing the token.
 
 Tasks:
 1. Verify Node.js is version 20 or newer and Hermes Agent is installed.
@@ -110,6 +110,23 @@ hermes inline status
 inline-hermes --version
 ```
 
+The Inline CLI can drive Hermes setup without putting the bot token in argv:
+
+```sh
+inline agents setup --target hermes --non-interactive --json
+```
+
+For other orchestrators, the plugin also exposes a token-free machine contract.
+The token is accepted only on stdin and is saved through Hermes's credential
+helper:
+
+```sh
+printf '%s\n' "$INLINE_BOT_TOKEN" | hermes inline setup \
+  --non-interactive --token-stdin --owner-user-id 123 \
+  --access owner --json
+hermes inline status --json --probe
+```
+
 `doctor` verifies required plugin files, the Node executable used for the
 sidecar, the installed sidecar bundle hash, and whether Hermes config enables
 the external plugin with `plugins.enabled: [inline-platform]`. It detects
@@ -129,7 +146,7 @@ uv run ./hermes plugins list --plain --no-bundled
 Expected local output includes:
 
 ```text
-enabled      user     0.0.6    inline-platform
+enabled      user     0.0.8-alpha.0    inline-platform
 ```
 
 ## Update Or Reinstall
@@ -152,7 +169,7 @@ 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.19.1` from source commit `cc4cab2`.
+  against Hermes Agent `0.20.0` from source commit `3c27eb6`.
 - 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.14` and is
@@ -174,10 +191,10 @@ Before publishing, run:
 bun run release:preflight
 ```
 
-This runs `npm publish --dry-run --access public`. npm invokes
-`prepublishOnly`, so the dry-run must pass `bun run check`, rebuild the packed
-runtime files, verify the shipped `inline-hermes` binary, and print the final
-tarball contents without publishing.
+This creates an isolated registry-dependency stage, runs the full package
+check, packs one read-only tarball, and runs `npm publish --dry-run` against
+those exact bytes. It prints the artifact path, SHA-256, and file list so the
+trusted-publishing workflow can hash-check and publish the same artifact.
 
 Maintainers should also run the manual live-test and publish checklist in
 [`hermes-agent/RELEASE.md`](https://github.com/inline-chat/inline/blob/main/hermes-agent/RELEASE.md).

package/dist/install.js

@@ -7047,7 +7047,7 @@ var minNodeMajor = 20;
 async function main(argv = process.argv.slice(2)) {
   const opts = parseArgs(argv);
   if (opts.command === "help") {
-    printHelp();
+    printHelp(opts.helpTopic);
     return 0;
   }
   const pkg = await readPackageInfo();
@@ -7064,7 +7064,7 @@ async function main(argv = process.argv.slice(2)) {
     } else {
       printStatus(status);
     }
-    return status.ok ? 0 : opts.command === "doctor" ? 1 : 0;
+    return status.ok ? 0 : 1;
   }
   if (opts.command === "test-send") {
     const result2 = await testSend({ source, opts, pkg });
@@ -7087,8 +7087,15 @@ async function installPlugin(params) {
   const before = await inspectInstall(params);
   if (!before.sourceValid)
     return { ...before, action: "install", installed: false };
-  if (params.opts.dryRun)
-    return { ...before, action: "install", installed: false };
+  if (params.opts.dryRun) {
+    return {
+      ...before,
+      ok: before.sourceReady,
+      action: "install",
+      installed: false,
+      issues: before.sourceReady ? [] : before.issues
+    };
+  }
   await mkdir(path.dirname(params.target), { recursive: true });
   if (before.targetExists) {
     if (!params.opts.force) {
@@ -7119,7 +7126,7 @@ async function installPlugin(params) {
   return {
     ...after,
     action: "install",
-    installed: after.targetValid
+    installed: after.installedReady
   };
 }
 function shouldCopyPluginFile(src) {
@@ -7143,13 +7150,16 @@ async function inspectInstall(params) {
   const activation = await inspectActivation(params.opts.hermesHome, params.target);
   const issues = [];
   const warnings = [];
+  const sidecarMatches = Boolean(targetSidecar?.exists && sourceSidecar.sha256 && targetSidecar.sha256 && sourceSidecar.sha256 === targetSidecar.sha256);
+  const sourceReady = sourceValid && sourceSidecar.exists && node.ok;
+  const installedReady = targetExists && targetValid && sidecarMatches && node.ok;
   if (!sourceValid) {
     issues.push(`plugin source is incomplete: ${params.source}`);
   }
   if (targetExists && !targetValid) {
     issues.push(`installed plugin is incomplete: ${params.target}`);
   }
-  if (params.opts.command === "doctor" && !targetExists) {
+  if ((params.opts.command === "status" || params.opts.command === "doctor") && !targetExists) {
     issues.push(`plugin is not installed: ${params.target}`);
   }
   if (targetSidecar?.exists && sourceSidecar.sha256 && targetSidecar.sha256 && sourceSidecar.sha256 !== targetSidecar.sha256) {
@@ -7171,7 +7181,7 @@ async function inspectInstall(params) {
     warnings.push("Installed plugin ownership differs from the Hermes home owner; internal /inline_update may fail until inline-hermes install --force repairs it");
   }
   return {
-    ok: sourceValid && (!targetExists || targetValid) && node.ok && issues.length === 0,
+    ok: installedReady && issues.length === 0,
     action: "status",
     packageName: params.pkg.name,
     packageVersion: params.pkg.version,
@@ -7180,14 +7190,17 @@ async function inspectInstall(params) {
     source: params.source,
     sourceReal,
     sourceValid,
+    sourceReady,
     target: params.target,
     targetReal,
     targetExists,
     targetValid,
+    installedReady,
     targetLinked,
     sidecar: {
       source: sourceSidecar,
-      target: targetSidecar
+      target: targetSidecar,
+      matchesPackage: sidecarMatches
     },
     node,
     activation,
@@ -7298,21 +7311,40 @@ async function testSend(params) {
   }
 }
 function parseArgs(argv) {
-  const command = parseCommand(argv[0]);
-  const opts = {
-    command,
-    hermesHome: process.env.HERMES_HOME || path.join(os.homedir(), ".hermes"),
-    pluginId: defaultPluginId,
-    link: false,
-    dryRun: false,
-    force: false,
-    json: false,
-    text: "Inline Hermes test",
-    timeoutMs: 30000
-  };
+  if (argv[0] === "help") {
+    const helpTopic = argv[1] == null ? undefined : parseRuntimeCommand(argv[1]);
+    if (argv.length > (helpTopic ? 2 : 1))
+      throw new Error(`unknown argument: ${argv[helpTopic ? 2 : 1]}`);
+    return defaultOptions("help", helpTopic);
+  }
+  if (argv[0] === "version") {
+    if (argv.length !== 1)
+      throw new Error(`unknown argument: ${argv[1]}`);
+    return defaultOptions("version");
+  }
   const firstArgIsFlag = argv[0]?.startsWith("-") ?? false;
-  for (let i = argv[0] == null || firstArgIsFlag ? 0 : 1;i < argv.length; i += 1) {
+  const selectedCommand = firstArgIsFlag || argv[0] == null ? "install" : parseRuntimeCommand(argv[0]);
+  const opts = defaultOptions(selectedCommand);
+  const startIndex = argv[0] == null || firstArgIsFlag ? 0 : 1;
+  if (argv[startIndex] === "-v" || argv[startIndex] === "--version") {
+    if (startIndex !== 0 || argv.length !== 1)
+      throw new Error("--version is only valid as a top-level flag");
+    opts.command = "version";
+    return opts;
+  }
+  for (let i = startIndex;i < argv.length; i += 1) {
     const arg = argv[i];
+    if (arg == null)
+      throw new Error("missing argument");
+    if (arg === "-h" || arg === "--help") {
+      if (argv.length !== i + 1)
+        throw new Error(`${arg} must be the final argument`);
+      opts.command = "help";
+      if (startIndex !== 0)
+        opts.helpTopic = selectedCommand;
+      return opts;
+    }
+    assertOptionAllowed(selectedCommand, arg);
     switch (arg) {
       case "--hermes-home":
         opts.hermesHome = requireValue(argv, ++i, arg);
@@ -7347,14 +7379,6 @@ function parseArgs(argv) {
       case "--timeout-ms":
         opts.timeoutMs = parsePositiveInt(requireValue(argv, ++i, arg), arg);
         break;
-      case "-h":
-      case "--help":
-        opts.command = "help";
-        break;
-      case "-v":
-      case "--version":
-        opts.command = "version";
-        break;
       default:
         throw new Error(`unknown argument: ${arg}`);
     }
@@ -7363,17 +7387,39 @@ function parseArgs(argv) {
   validatePluginId(opts.pluginId);
   return opts;
 }
-function parseCommand(raw) {
-  if (raw == null || raw === "install")
-    return "install";
-  if (raw === "status" || raw === "doctor" || raw === "test-send" || raw === "help" || raw === "version")
+function defaultOptions(command, helpTopic) {
+  const opts = {
+    command,
+    hermesHome: process.env.HERMES_HOME || path.join(os.homedir(), ".hermes"),
+    pluginId: defaultPluginId,
+    link: false,
+    dryRun: false,
+    force: false,
+    json: false,
+    text: "Inline Hermes test",
+    timeoutMs: 30000,
+    ...helpTopic ? { helpTopic } : {}
+  };
+  return opts;
+}
+function parseRuntimeCommand(raw) {
+  if (raw === "install" || raw === "status" || raw === "doctor" || raw === "test-send")
     return raw;
-  if (raw === "-h" || raw === "--help")
-    return "help";
-  if (raw === "-v" || raw === "--version")
-    return "version";
   throw new Error(`unknown command: ${raw}`);
 }
+var commandOptions = {
+  install: new Set(["--hermes-home", "--plugin-id", "--link", "--dry-run", "--force", "--json"]),
+  status: new Set(["--hermes-home", "--plugin-id", "--json"]),
+  doctor: new Set(["--hermes-home", "--plugin-id", "--json"]),
+  "test-send": new Set(["--hermes-home", "--dry-run", "--json", "--to", "--text", "--base-url", "--state-path", "--timeout-ms"])
+};
+function assertOptionAllowed(command, option) {
+  if (!option.startsWith("-"))
+    throw new Error(`unexpected positional argument for ${command}: ${option}`);
+  if (!commandOptions[command].has(option)) {
+    throw new Error(`${option} is not valid for inline-hermes ${command}`);
+  }
+}
 function requireValue(argv, index, flag) {
   const value = argv[index];
   if (value == null || value.startsWith("--")) {
@@ -7525,20 +7571,20 @@ async function inspectInstallOwnership(hermesHome, target) {
   try {
     const homeInfo = await stat(hermesHome);
     const pluginsInfo = await stat(path.dirname(target));
-    return pluginsInfo.uid === homeInfo.uid && pluginsInfo.gid === homeInfo.gid && await treeOwnershipMatches(target, homeInfo.uid, homeInfo.gid);
+    return pluginsInfo.uid === homeInfo.uid && await treeOwnershipMatches(target, homeInfo.uid);
   } catch {
     return false;
   }
 }
-async function treeOwnershipMatches(target, uid, gid) {
+async function treeOwnershipMatches(target, uid) {
   const info = await lstat(target);
-  if (info.uid !== uid || info.gid !== gid)
+  if (info.uid !== uid)
     return false;
   if (!info.isDirectory())
     return true;
   const entries = await readdir(target);
   for (const entry of entries) {
-    if (!await treeOwnershipMatches(path.join(target, entry), uid, gid))
+    if (!await treeOwnershipMatches(path.join(target, entry), uid))
       return false;
   }
   return true;
@@ -8001,28 +8047,68 @@ function formatSidecarInfo(info) {
   const digest = info.sha256 ? info.sha256.slice(0, 12) : "unknown";
   return `${info.path} (${info.size ?? 0} bytes, sha256 ${digest})`;
 }
-function printHelp() {
+function printHelp(topic) {
+  if (topic === "install") {
+    console.log(`Usage: inline-hermes install [options]
+
+Install the packaged Inline plugin into a Hermes home.
+
+Options:
+  --hermes-home <path>  Hermes home directory. Defaults to HERMES_HOME or ~/.hermes.
+  --plugin-id <id>      Installed plugin directory name. Defaults to inline.
+  --link                Symlink the packaged plugin for local development.
+  --force               Replace an existing target plugin directory.
+  --dry-run             Validate packaged source and Node without writing files.
+  --json                Print machine-readable output.
+  -h, --help            Show this command help.
+`);
+    return;
+  }
+  if (topic === "status" || topic === "doctor") {
+    console.log(`Usage: inline-hermes ${topic} [options]
+
+${topic === "doctor" ? "Diagnose" : "Inspect"} the installed Inline plugin, sidecar integrity, and Node runtime.
+
+Options:
+  --hermes-home <path>  Hermes home directory. Defaults to HERMES_HOME or ~/.hermes.
+  --plugin-id <id>      Installed plugin directory name. Defaults to inline.
+  --json                Print machine-readable output.
+  -h, --help            Show this command help.
+`);
+    return;
+  }
+  if (topic === "test-send") {
+    console.log(`Usage: inline-hermes test-send --to chat:<id>|user:<id> [options]
+
+Probe the packaged sidecar with a bounded Inline send, or validate it with --dry-run.
+
+Options:
+  --hermes-home <path>  Hermes home used for token/config resolution.
+  --to <target>         Inline destination, for example chat:123 or user:42.
+  --text <message>      Message text. Defaults to "Inline Hermes test".
+  --base-url <url>      Inline API base URL. Defaults to https://api.inline.chat.
+  --state-path <path>   Inline SDK state file used by the probe sidecar.
+  --timeout-ms <ms>     Sidecar readiness timeout. Defaults to 30000.
+  --dry-run             Validate inputs without starting the sidecar or sending.
+  --json                Print machine-readable output.
+  -h, --help            Show this command help.
+`);
+    return;
+  }
   console.log(`inline-hermes
 
 Usage:
-  inline-hermes install [--hermes-home <path>] [--link] [--force] [--dry-run]
+  inline-hermes install [options]
   inline-hermes status [--hermes-home <path>] [--json]
   inline-hermes doctor [--hermes-home <path>] [--json]
-  inline-hermes test-send --to chat:<id>|user:<id> [--text <message>] [--json]
+  inline-hermes test-send --to chat:<id>|user:<id> [options]
+  inline-hermes help [install|status|doctor|test-send]
   inline-hermes version
 
-Options:
-  --hermes-home <path>  Hermes home directory. Defaults to HERMES_HOME or ~/.hermes.
-  --link                Symlink plugin source instead of copying it.
-  --force               Replace an existing target plugin directory.
-  --dry-run             Print what would happen without writing files.
-  --json                Print machine-readable output.
-  --to <target>          Inline target for test-send, for example chat:123.
-  --text <message>       Message for test-send. Defaults to "Inline Hermes test".
-  --base-url <url>       Inline API base URL for test-send.
-  --state-path <path>    Inline SDK state file for test-send.
-  --timeout-ms <ms>      test-send sidecar readiness timeout. Defaults to 30000.
-  -v, --version          Print package version.
+Run \`inline-hermes <command> --help\` for command-scoped options.
+Top-level options:
+  -h, --help     Show this help.
+  -v, --version  Print package version.
 
 After install, enable the external Hermes plugin with:
   hermes plugins enable ${pluginEnableKey}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inline-chat/hermes-agent-adapter",
-  "version": "0.0.6",
+  "version": "0.0.8-alpha.0",
   "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-alpha.0",
     "yaml": "2.9.0"
   },
   "devDependencies": {
@@ -75,8 +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()]