mirrors/hermes-agent
1
0
Fork 0
mirror of https://github.com/NousResearch/hermes-agent.git synced 2026-05-24 05:41:40 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 6

feat(session): make /handoff actually transfer the session live

Browse source 
Builds on @kshitijk4poor's CLI handoff stub. The original PR's flow
deferred everything to whenever a real user happened to message the
target platform; this rewrites it so the gateway picks up handoffs
immediately and the destination chat just starts working.

State machine on sessions table replaces the boolean flag:
  None -> 'pending' -> 'running' -> ('completed' | 'failed')
plus handoff_error for failure reasons. CLI request_handoff /
get_handoff_state / list_pending_handoffs / claim_handoff /
complete_handoff / fail_handoff helpers wrap the transitions.

CLI side (cli.py): /handoff <platform> validates the platform's home
channel via load_gateway_config, refuses if the agent is mid-turn,
flips the row to 'pending', and poll-blocks (60s) on terminal state.
On 'completed' it prints the /resume hint and exits the CLI like
/quit. On 'failed' or timeout it surfaces the reason and the CLI
session stays intact.

Gateway side (gateway/run.py): new _handoff_watcher background task
scans state.db every 2s, atomically claims pending rows, and runs
_process_handoff for each. _process_handoff:

  1. Resolves the platform's home channel.
  2. Asks the adapter for a fresh thread via the new
     create_handoff_thread(parent_chat_id, name) capability so the
     handed-off conversation gets its own scrollback. Adapters that
     don't support threads (or fail) return None and the watcher
     falls back to the home channel directly.
  3. Constructs a SessionSource keyed as 'thread' when a thread was
     created, 'dm' otherwise, then session_store.switch_session
     re-binds the destination key to the CLI session_id. The full
     role-aware transcript replays via load_transcript on the next
     turn (no flat-text injection into context_prompt).
  4. Forges a synthetic MessageEvent(internal=True) with the handoff
     notice and dispatches through _handle_message; the agent runs
     against the loaded transcript and adapter.send delivers the
     reply.
  5. Marks the row 'completed' on success, 'failed' (+error) on any
     exception.

Adapter capability (gateway/platforms/base.py): create_handoff_thread
default returns None. Three overrides:

  - Telegram (gateway/platforms/telegram.py): wraps _create_dm_topic
    so DM topics (Bot API 9.4+) and forum supergroups both work.
  - Discord (gateway/platforms/discord.py): parent.create_thread on
    text channels with a seed-message + message.create_thread
    fallback for permission edge cases. Skips DMs and other
    non-thread-capable parents.
  - Slack (gateway/platforms/slack.py): posts a seed message and
    returns its ts as the thread anchor — Slack threads are
    message-anchored.

In thread mode, build_session_key keys the destination without
user_id (thread_sessions_per_user defaults to False) so the synthetic
turn and any later real-user message in the thread share the same
session_key — seamless takeover without race.

CommandDef stays cli_only=True (handoff is initiated from the CLI;
gateway exposes /resume for the reverse direction).

Removed the original PR's _handle_message_with_agent handoff hook
(transcript-as-text injection into context_prompt) and the
send_message_tool notification — both replaced by the watcher path.

Tests rewritten around the new state machine: 13/13 pass.
E2E-validated thread + no-thread paths and the failure path against
real worktree imports with mocked adapters.
This commit is contained in:
teknium1 2026-05-10 12:56:31 -07:00 • committed by Teknium
parent 878611a79d
commit 00ce5f04d9
8 changed files with 737 additions and 189 deletions
Download patch file Download diff file Expand all files Collapse all files

27
gateway/platforms/base.py
View file

@ -1511,6 +1511,33 @@ class BasePlatformAdapter(ABC):
# property) so the stream consumer knows not to short-circuit.
REQUIRES_EDIT_FINALIZE: bool = False
async def create_handoff_thread(
self,
parent_chat_id: str,
name: str,
) -> Optional[str]:
"""Create a fresh thread under ``parent_chat_id`` for a session handoff.
Used by the gateway's handoff watcher when transferring a CLI
session to a thread-capable platform — the new thread isolates the
handed-off conversation from any pre-existing chat in the home
channel and gives users a clean per-handoff scrollback.
Returns the new thread/topic id (as a string) on success, or
``None`` if the platform doesn't support threading or the
attempt failed (permissions, topics-mode off, etc.). When ``None``
is returned the watcher falls back to using ``parent_chat_id``
directly.
Default implementation returns ``None`` — adapters that support
threads override this. See:
- Telegram: forum topics in groups, DM topics with bot API 9.4+
- Discord: text-channel threads (1440-min auto-archive)
- Slack: seed-message thread anchoring
"""
return None
async def edit_message(
self,
chat_id: str,

78
gateway/platforms/discord.py
View file

@ -3689,6 +3689,84 @@ class DiscordAdapter(BasePlatformAdapter):
)
return None
async def create_handoff_thread(
self,
parent_chat_id: str,
name: str,
) -> Optional[str]:
"""Create a Discord thread under a text channel for a handoff.
Falls back to a seed-message + ``message.create_thread`` path if
``parent.create_thread`` is rejected (some channel types or
permission setups). Returns the new thread id as a string, or
``None`` on failure or when the parent isn't a text channel
(DMs, voice channels, threads themselves can't host threads).
"""
if not self._client or not DISCORD_AVAILABLE:
return None
try:
parent_id = int(parent_chat_id)
except (TypeError, ValueError):
return None
try:
parent = self._client.get_channel(parent_id)
if parent is None:
parent = await self._client.fetch_channel(parent_id)
except Exception as exc:
logger.warning(
"[%s] Handoff thread: cannot resolve parent %s: %s",
self.name, parent_chat_id, exc,
)
return None
# DMs, voice channels, and existing threads can't host child threads.
if isinstance(parent, getattr(discord, "DMChannel", tuple())):
logger.info(
"[%s] Handoff thread: parent %s is a DM; threads not supported here",
self.name, parent_chat_id,
)
return None
thread_name = (name or "handoff").strip()[:80] or "handoff"
reason = "Hermes session handoff"
# First try: create a thread directly on the channel.
try:
create = getattr(parent, "create_thread", None)
if create is not None:
thread = await create(
name=thread_name,
auto_archive_duration=1440,
reason=reason,
)
return str(thread.id)
except Exception as direct_error:
logger.debug(
"[%s] Handoff thread: direct create failed (%s); trying seed-message fallback",
self.name, direct_error,
)
# Fallback: post a seed message and create the thread from it.
try:
send = getattr(parent, "send", None)
if send is None:
return None
seed_msg = await send(f"\U0001f9f5 Hermes handoff: **{thread_name}**")
thread = await seed_msg.create_thread(
name=thread_name,
auto_archive_duration=1440,
reason=reason,
)
return str(thread.id)
except Exception as fallback_error:
logger.warning(
"[%s] Handoff thread: both create paths failed for parent %s: %s",
self.name, parent_chat_id, fallback_error,
)
return None
async def send_exec_approval(
self, chat_id: str, command: str, session_key: str,
description: str = "dangerous command",

35
gateway/platforms/slack.py
View file

@ -679,6 +679,41 @@ class SlackAdapter(BasePlatformAdapter):
if lock_acquired and not self._running:
self._release_platform_lock()
async def create_handoff_thread(
self,
parent_chat_id: str,
name: str,
) -> Optional[str]:
"""Create a Slack thread anchor for a session handoff.
Slack threads are anchored to a parent message (``thread_ts``), not
a channel-level construct. So we post a seed message into the home
channel and return its ``ts`` — the watcher uses that as the
``thread_id`` for subsequent sends.
Returns the seed message ts as a string, or ``None`` on failure.
"""
if not self._app:
return None
try:
client = self._get_client(parent_chat_id)
if client is None:
return None
seed_text = f":thread: Hermes handoff — *{(name or 'session').strip()[:80]}*"
result = await client.chat_postMessage(
channel=parent_chat_id,
text=seed_text,
)
ts = result.get("ts") if isinstance(result, dict) else getattr(result, "get", lambda _k, _d=None: None)("ts")
if ts:
return str(ts)
except Exception as exc:
logger.warning(
"[%s] Handoff thread: seed-post failed for channel %s: %s",
self.name, parent_chat_id, exc,
)
return None
async def disconnect(self) -> None:
"""Disconnect from Slack."""
if self._handler:

18
gateway/platforms/telegram.py
View file

@ -865,6 +865,24 @@ class TelegramAdapter(BasePlatformAdapter):
)
return None
async def create_handoff_thread(
self,
parent_chat_id: str,
name: str,
) -> Optional[str]:
"""Create a forum topic for a session handoff.
Works for DM topics (Bot API 9.4+, requires user to enable Topics
in their chat with the bot) and forum supergroups. Returns the
``message_thread_id`` as a string, or ``None`` on failure.
"""
try:
chat_id_int = int(parent_chat_id)
except (TypeError, ValueError):
return None
thread_id = await self._create_dm_topic(chat_id_int, name=name)
return str(thread_id) if thread_id else None
async def rename_dm_topic(
self,
chat_id: int,

264
gateway/run.py
View file

@ -3681,10 +3681,234 @@ class GatewayRunner:
)
asyncio.create_task(self._platform_reconnect_watcher())
# Start background handoff watcher — picks up CLI sessions marked
# handoff_state='pending' in state.db and re-binds them to the
# destination platform's home channel, then forges a synthetic user
# turn so the agent kicks off the new chat.
asyncio.create_task(self._handoff_watcher())
logger.info("Press Ctrl+C to stop")
return True
async def _handoff_watcher(self, interval: float = 2.0) -> None:
"""Background task that processes pending CLI→gateway session handoffs.
Polls ``state.db`` for sessions in ``handoff_state='pending'`` and,
for each one:
1. Atomically claims it (pending → running).
2. Resolves the destination platform's configured home channel.
3. Re-binds the gateway's session_key for that home channel to the
CLI's existing session_id via ``session_store.switch_session`` so
the full role-aware transcript replays on the next agent turn.
4. Forges a synthetic ``MessageEvent`` (``internal=True``) with a
handoff-notice text and dispatches through the normal gateway
message pipeline so the agent runs and replies on the platform.
5. Marks the row ``completed`` (or ``failed`` with ``handoff_error``).
The CLI process is poll-blocked on the row's terminal state and
prints the result to the user.
"""
# Initial delay so the gateway is fully connected to its platforms
# before we try to dispatch handoffs through them.
await asyncio.sleep(5)
while self._running:
try:
if self._session_db is None:
await asyncio.sleep(interval)
continue
pending = self._session_db.list_pending_handoffs()
for row in pending:
session_id = row.get("id")
if not session_id:
continue
if not self._session_db.claim_handoff(session_id):
# Another tick or another gateway already claimed it.
continue
try:
await self._process_handoff(row)
self._session_db.complete_handoff(session_id)
except Exception as exc:
logger.warning(
"Handoff for session %s failed: %s",
session_id, exc, exc_info=True,
)
self._session_db.fail_handoff(session_id, str(exc))
except asyncio.CancelledError:
raise
except Exception as exc:
logger.debug("Handoff watcher tick error: %s", exc, exc_info=True)
await asyncio.sleep(interval)
async def _process_handoff(self, row: Dict[str, Any]) -> None:
"""Execute one handoff row. Raises on failure (caller marks failed)."""
from gateway.config import Platform
from gateway.session import SessionSource, build_session_key
from gateway.platforms.base import MessageEvent
cli_session_id = row["id"]
platform_name = (row.get("handoff_platform") or "").strip().lower()
if not platform_name:
raise RuntimeError("handoff_platform is empty")
# Resolve platform enum
try:
platform = Platform(platform_name)
except (ValueError, KeyError):
raise RuntimeError(f"unknown platform '{platform_name}'")
# Adapter must be live
adapter = self.adapters.get(platform)
if not adapter:
raise RuntimeError(
f"platform '{platform_name}' is not active in this gateway"
)
# Home channel must be configured
home = self.config.get_home_channel(platform)
if not home or not home.chat_id:
raise RuntimeError(
f"no home channel configured for {platform_name}; "
f"run /sethome on the desired chat first"
)
cli_title = row.get("title") or cli_session_id[:8]
# Try to create a fresh thread on the destination so the handoff
# has its own scrollback. Adapter returns None if threading isn't
# supported (Matrix/WhatsApp/Signal/SMS) or if creation failed
# (no permission, topics-mode off, parent is a DM, etc.). When
# None we fall through to using the home channel directly — the
# synthetic turn still lands; just without thread isolation.
thread_name = f"Hermes — {cli_title}"
try:
new_thread_id = await adapter.create_handoff_thread(
str(home.chat_id), thread_name,
)
except Exception as exc:
logger.debug(
"Handoff: create_handoff_thread raised on %s: %s",
platform_name, exc, exc_info=True,
)
new_thread_id = None
# Use the new thread if the adapter created one; otherwise fall
# back to whatever thread (if any) the home channel was configured
# with.
effective_thread_id = new_thread_id or (
str(home.thread_id) if home.thread_id else None
)
# Determine chat_type for the destination source. If we created a
# thread, key the session_key as a thread (build_session_key sets
# thread sessions to user-shared by default, which is what we
# want — the synthetic turn and any later real-user message both
# land on the same key without needing a user_id).
if new_thread_id:
dest_chat_type = "thread"
else:
# No thread — assume DM-style for the home channel. For
# group/channel home channels without thread support
# (Matrix/WhatsApp/Signal), the platform's own keying makes
# the synthetic turn shared anyway (single-DM platforms).
dest_chat_type = "dm"
dest_source = SessionSource(
platform=platform,
chat_id=str(home.chat_id),
chat_name=home.name,
chat_type=dest_chat_type,
user_id="system:handoff",
user_name="Handoff",
thread_id=effective_thread_id,
)
# Compute the gateway's session_key for that destination using the
# same rules its adapters use, so switch_session targets the right
# entry. For thread destinations build_session_key keys without
# user_id (thread_sessions_per_user defaults to False) — so the
# next real user message in the thread shares this same session.
platform_cfg = self.config.platforms.get(platform)
extra = platform_cfg.extra if platform_cfg else {}
session_key = build_session_key(
dest_source,
group_sessions_per_user=extra.get("group_sessions_per_user", True),
thread_sessions_per_user=extra.get("thread_sessions_per_user", False),
)
# Make sure there's an entry in the session_store for this key. If
# the home channel has never been used, get_or_create_session
# creates one; switch_session then re-points it.
self.session_store.get_or_create_session(dest_source)
# Re-bind the destination key to the CLI session_id. switch_session
# ends the prior session in SQLite and reopens the CLI session under
# the new key. The CLI's transcript becomes the active one for the
# gateway from this moment on.
switched = self.session_store.switch_session(session_key, cli_session_id)
if switched is None:
raise RuntimeError(
f"could not switch session key {session_key} → {cli_session_id}"
)
# Evict any cached AIAgent for this session_key so the next dispatch
# rebuilds it against the CLI session_id (mirrors /resume / /branch).
self._evict_cached_agent(session_key)
# Cancel any in-flight running-agent state for the destination key
# so the synthetic turn isn't queued behind a stale running flag.
self._release_running_agent_state(session_key)
synthetic_text = (
f"[Session was just handed off from CLI (\"{cli_title}\") to this "
f"channel. The full prior conversation history is loaded above. "
f"Briefly confirm you're working here and summarize what we were "
f"working on, so the user can continue from this device.]"
)
synthetic_event = MessageEvent(
text=synthetic_text,
source=dest_source,
internal=True,
)
logger.info(
"Handoff: dispatching synthetic turn for CLI session %s → %s "
"(home=%s, thread=%s, session_key=%s)",
cli_session_id, platform_name, home.chat_id, effective_thread_id,
session_key,
)
# Dispatch through the runner directly. Going through
# adapter.handle_message would spawn a background task and we'd
# lose synchronous error visibility; calling _handle_message inline
# keeps the success/failure path observable for the watcher.
response_text = await self._handle_message(synthetic_event)
if not response_text:
# Streaming may have already delivered the response inline.
# Either way, agent ran without raising — count as success.
return
# Send the agent's reply to the destination. Route to the new
# thread if we created one; otherwise the configured home channel
# (which may itself carry a thread_id).
send_metadata: Dict[str, Any] = {}
if effective_thread_id:
send_metadata["thread_id"] = effective_thread_id
try:
result = await adapter.send(
chat_id=str(home.chat_id),
content=response_text,
metadata=send_metadata or None,
)
except Exception as exc:
raise RuntimeError(f"adapter.send failed: {exc}") from exc
if not getattr(result, "success", True):
err = getattr(result, "error", "send returned success=False")
raise RuntimeError(f"adapter.send failed: {err}")
async def _session_expiry_watcher(self, interval: int = 300):
"""Background task that finalizes expired sessions.
@ -6648,46 +6872,6 @@ class GatewayRunner:
# Build the context prompt to inject
context_prompt = build_session_context_prompt(context, redact_pii=_redact_pii)
# Check for pending CLI handoff
if _is_new_session and self._session_db:
try:
platform_key = source.platform.value if source.platform else ""
handoff = self._session_db.find_pending_handoff(platform_key)
if handoff:
cli_session_id = handoff["id"]
cli_messages = self._session_db.get_messages(cli_session_id)
if cli_messages:
# Cap to last 200 messages to avoid context blowup
cli_messages = cli_messages[-200:]
transcript = []
for msg in cli_messages:
role = msg.get("role", "unknown")
content = str(msg.get("content") or "")
if content.strip():
label = {"user": "User", "assistant": "Assistant",
"system": "System", "tool": "Tool"}.get(role, role.title())
transcript.append(f"{label}: {content}")
if transcript:
handoff_title = handoff.get("title") or "untitled"
handoff_context = (
f"[Handoff from CLI session '{handoff_title}'. "
f"Continue the conversation below where it left off.]"
)
context_prompt = (
handoff_context
+ "\n\n--- Previous conversation ---\n"
+ "\n\n".join(transcript)
+ "\n--- End of previous conversation ---\n\n"
+ context_prompt
)
self._session_db.clear_handoff_pending(cli_session_id)
logger.info(
"Handoff: CLI session %s handed off to %s chat %s",
cli_session_id, platform_key, source.chat_id,
)
except Exception:
logger.debug("Handoff check failed", exc_info=True)
# If the previous session expired and was auto-reset, prepend a notice
# so the agent knows this is a fresh conversation (not an intentional /reset).