| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195 |
- """``PluginContext.post_message``: one message in the current conversation, editable in place.
- The conversation is the session bound in the calling context (a tool or hook running in its turn,
- its slash command, a hook fired for it): the plugin never names a chat, so it cannot reach another
- one. Outside any session (a timer, a plugin thread, cron, a process with no live gateway) the call
- is refused with a result, never an exception. Routing and the edit fallback live in
- ``gateway/plugin_messages.py``; this side only hands work to the gateway loop and back.
- """
- from __future__ import annotations
- import asyncio
- import concurrent.futures
- import logging
- from typing import Any, Optional
- logger = logging.getLogger("hermes_cli.plugins")
- _TIMEOUT_S = 30.0
- def _err(code: str, detail: str = "") -> dict[str, Any]:
- return {"ok": False, "error": code, **({"detail": detail} if detail else {})}
- class PluginMessage:
- """Handle for one posted message. ``ok`` / ``message_id`` / ``error`` describe the last
- operation; ``edit(text)`` replaces the text in place (or posts anew where the surface cannot
- edit, and the handle then follows the new message). A refused post returns a handle whose
- edits are refused the same way. Operations stay ordered: one the gateway has not finished
- (``error == "timeout"``, ``pending`` set) is waited for before the next runs, and its outcome
- still lands on the handle, so a slow post never leaves an orphan message behind a dead handle."""
- def __init__(self, plugin_id: str, target: Any, result: dict[str, Any]):
- self._plugin_id, self._target = plugin_id, target
- self.result = result
- self.message_id: Optional[str] = result.get("message_id")
- self._pending: Optional[concurrent.futures.Future] = None
- @property
- def ok(self) -> bool:
- return bool(self.result.get("ok"))
- @property
- def error(self) -> Optional[str]:
- return self.result.get("error")
- @property
- def pending(self) -> bool:
- return self._pending is not None and not self._pending.done()
- def __repr__(self) -> str:
- return f"<PluginMessage ok={self.ok} message_id={self.message_id!r} error={self.error!r}>"
- def _adopt(self, other: PluginMessage) -> None:
- self._target, self.result, self.message_id = other._target, other.result, other.message_id
- def _refused(self) -> Optional[dict[str, Any]]:
- if self._target is None:
- return _err(self.error or "no_conversation", self.result.get("detail", ""))
- return None
- def _settle(self, result: dict[str, Any]) -> dict[str, Any]:
- self.result = result
- if result.get("ok") and result.get("message_id"):
- self.message_id = result["message_id"]
- return result
- async def _edit(self, text: str) -> dict[str, Any]:
- refused = self._refused()
- if refused is not None:
- return refused
- from gateway import plugin_messages
- return self._settle(await plugin_messages.edit(self._target, self.message_id, str(text),
- plugin_id=self._plugin_id))
- async def aedit(self, text: str) -> dict[str, Any]:
- """``edit`` for code already running on the gateway's event loop (async hooks/commands)."""
- if self.pending:
- await asyncio.wrap_future(self._pending)
- return await self._edit(text)
- def edit(self, text: str) -> dict[str, Any]:
- """Replace the message text: ``{"ok", "message_id", "edited", ["fallback"]}``. Thread-safe."""
- if _on_gateway_loop(): # never block the loop the pending operation needs
- return _err("on_event_loop", "called from the gateway event loop: use await handle.aedit(...)")
- if self.pending:
- try:
- self._pending.result(_TIMEOUT_S)
- except concurrent.futures.TimeoutError:
- return _err("timeout", "the previous operation on this message has not finished")
- except Exception: # its own outcome is already on the handle
- logger.debug("plugin_message: previous operation failed", exc_info=True)
- refused = self._refused()
- if refused is not None:
- return refused
- return _run_on_gateway_loop(self._edit(text), self)
- def _gateway_loop():
- try:
- from gateway.run import _gateway_runner_ref
- runner = _gateway_runner_ref()
- except ImportError:
- runner = None
- loop = getattr(runner, "_gateway_loop", None)
- if runner is None or not getattr(runner, "_running", False) or loop is None or loop.is_closed():
- return None, None
- return runner, loop
- def _on_gateway_loop() -> bool:
- _runner, loop = _gateway_loop()
- try:
- return loop is not None and asyncio.get_running_loop() is loop
- except RuntimeError:
- return False
- def _run_on_gateway_loop(coro, handle: PluginMessage) -> dict[str, Any]:
- """Run *coro* on the gateway loop and wait up to ``_TIMEOUT_S``; past that it keeps running as
- the handle's pending operation (its result still lands on the handle)."""
- _runner, loop = _gateway_loop()
- if loop is None:
- coro.close()
- return _err("gateway_unavailable", "no live gateway is running in this process")
- if _on_gateway_loop():
- coro.close()
- return _err("on_event_loop", "called from the gateway event loop: use the async form (await ...)")
- future = asyncio.run_coroutine_threadsafe(coro, loop)
- handle._pending = future
- try:
- return future.result(_TIMEOUT_S)
- except concurrent.futures.TimeoutError:
- result = _err("timeout", f"the gateway did not answer within {_TIMEOUT_S:.0f}s; the operation "
- "is still running and its result will land on this handle")
- handle.result = result
- return result
- except Exception as exc: # the plugin gets a result, never the raise
- logger.warning("plugin_message: gateway hand-off failed", exc_info=True)
- return _err("send_failed", str(exc)[:512])
- _NO_SESSION = ("no session is bound in the calling context (a tool call, slash command or hook "
- "fired for a session)")
- async def _post_for(ctx: Any, text: str, session_key: str, route: Any) -> PluginMessage:
- plugin_id = ctx.plugin_id
- runner, _loop = _gateway_loop()
- result: dict[str, Any]
- if not session_key:
- result = _err("no_conversation", _NO_SESSION)
- elif runner is None:
- result = _err("gateway_unavailable", "no live gateway is running in this process")
- else:
- from gateway import plugin_messages
- # The session store read is disk-bound: keep it off the gateway loop.
- target, refusal = await asyncio.to_thread(plugin_messages.resolve, runner, session_key=session_key,
- route=route, plugin_home=ctx._manager.home_path, plugin_id=plugin_id)
- if target is None:
- result = refusal or _err("no_conversation")
- else:
- result = await plugin_messages.post(target, str(text), plugin_id=plugin_id)
- if result.get("ok"):
- return PluginMessage(plugin_id, target, result)
- logger.info("plugin_message plugin=%s op=post refused: %s", plugin_id, result.get("error"))
- return PluginMessage(plugin_id, None, result)
- async def apost(ctx: Any, text: str) -> PluginMessage:
- """``post`` for code already running on the gateway's event loop (async hooks/commands)."""
- from gateway.plugin_messages import bound_route
- from gateway.session_context import bound_session_key
- return await _post_for(ctx, text, bound_session_key(), bound_route())
- def post(ctx: Any, text: str) -> PluginMessage:
- """Post *text* to the calling session from a tool handler or hook on a worker thread. The session
- is read here, on the caller's own context, then the send runs on the gateway loop."""
- from gateway.session_context import bound_session_key
- session_key = bound_session_key()
- if not session_key:
- return PluginMessage(ctx.plugin_id, None, _err("no_conversation", _NO_SESSION))
- from gateway.plugin_messages import bound_route
- route = bound_route()
- handle = PluginMessage(ctx.plugin_id, None, _err("timeout"))
- async def _post() -> dict[str, Any]:
- handle._adopt(await _post_for(ctx, text, session_key, route))
- return handle.result
- result = _run_on_gateway_loop(_post(), handle)
- if handle._target is None and not handle.pending:
- handle.result = result
- return handle
|