Compare commits

..

1 Commits

Author SHA1 Message Date
Timmy
e334c5256c feat: marathon session limits — cap, checkpoint, rotate (#326)
Some checks failed
Forge CI / smoke-and-build (pull_request) Failing after 54s
- Add max_messages (default 200) to SessionResetPolicy
- Track message_count in SessionEntry (persisted to sessions.json)
- Add 'message_limit' reset reason to _should_reset
- Auto-checkpoint filesystem before session rotation
- Inject near-limit warnings (85%/100%) into agent ephemeral prompt
- Auto-rotate sessions when message cap is hit
- Add get_message_limit_info() and reset_message_count() APIs
- 24 new tests covering all limit behaviors

Evidence: 170 sessions exceed 100 msgs, longest 1,643 msgs (40h).
Marathon sessions show 45-84% error rates from tool fixation.
Cap + checkpoint + restart breaks the death spiral.
2026-04-13 18:51:23 -04:00
5 changed files with 316 additions and 197 deletions

192
cli.py
View File

@@ -3134,196 +3134,6 @@ class HermesCLI:
print(f" Home: {display}")
print()
def _handle_debug_command(self, command: str):
"""Generate a debug report with system info and logs, upload to paste service."""
import platform
import sys
import time as _time
# Parse optional lines argument
parts = command.split(maxsplit=1)
log_lines = 50
if len(parts) > 1:
try:
log_lines = min(int(parts[1]), 500)
except ValueError:
pass
_cprint(" Collecting debug info...")
# Collect system info
lines = []
lines.append("=== HERMES DEBUG REPORT ===")
lines.append(f"Generated: {_time.strftime('%Y-%m-%d %H:%M:%S %z')}")
lines.append("")
lines.append("--- System ---")
lines.append(f"Python: {sys.version}")
lines.append(f"Platform: {platform.platform()}")
lines.append(f"Architecture: {platform.machine()}")
lines.append(f"Hostname: {platform.node()}")
lines.append("")
# Hermes info
lines.append("--- Hermes ---")
try:
from hermes_constants import get_hermes_home, display_hermes_home
lines.append(f"Home: {display_hermes_home()}")
except Exception:
lines.append("Home: unknown")
try:
from hermes_constants import __version__
lines.append(f"Version: {__version__}")
except Exception:
lines.append("Version: unknown")
lines.append(f"Profile: {getattr(self, '_profile_name', 'default')}")
lines.append(f"Session: {self.session_id}")
lines.append(f"Model: {self.model}")
lines.append(f"Provider: {getattr(self, '_provider_name', 'unknown')}")
try:
lines.append(f"Working dir: {os.getcwd()}")
except Exception:
pass
# Config (redacted)
lines.append("")
lines.append("--- Config (redacted) ---")
try:
from hermes_constants import get_hermes_home
config_path = get_hermes_home() / "config.yaml"
if config_path.exists():
import yaml
with open(config_path) as f:
cfg = yaml.safe_load(f) or {}
# Redact secrets
for key in ("api_key", "token", "secret", "password"):
if key in cfg:
cfg[key] = "***REDACTED***"
lines.append(yaml.dump(cfg, default_flow_style=False)[:2000])
else:
lines.append("(no config file found)")
except Exception as e:
lines.append(f"(error reading config: {e})")
# Recent logs
lines.append("")
lines.append(f"--- Recent Logs (last {log_lines} lines) ---")
try:
from hermes_constants import get_hermes_home
log_dir = get_hermes_home() / "logs"
if log_dir.exists():
for log_file in sorted(log_dir.glob("*.log")):
try:
content = log_file.read_text(encoding="utf-8", errors="replace")
tail = content.strip().split("\n")[-log_lines:]
if tail:
lines.append(f"\n[{log_file.name}]")
lines.extend(tail)
except Exception:
pass
else:
lines.append("(no logs directory)")
except Exception:
lines.append("(error reading logs)")
# Tool info
lines.append("")
lines.append("--- Enabled Toolsets ---")
try:
lines.append(", ".join(self.enabled_toolsets) if self.enabled_toolsets else "(none)")
except Exception:
lines.append("(unknown)")
report = "\n".join(lines)
report_size = len(report)
# Try to upload to paste services
paste_url = None
services = [
("dpaste", _upload_dpaste),
("0x0.st", _upload_0x0st),
]
for name, uploader in services:
try:
url = uploader(report)
if url:
paste_url = url
break
except Exception:
continue
print()
if paste_url:
_cprint(f" Debug report uploaded: {paste_url}")
_cprint(f" Size: {report_size} bytes, {len(lines)} lines")
else:
# Fallback: save locally
try:
from hermes_constants import get_hermes_home
debug_path = get_hermes_home() / "debug-report.txt"
debug_path.write_text(report, encoding="utf-8")
_cprint(f" Paste services unavailable. Report saved to: {debug_path}")
_cprint(f" Size: {report_size} bytes, {len(lines)} lines")
except Exception as e:
_cprint(f" Failed to save report: {e}")
_cprint(f" Report ({report_size} bytes):")
print(report)
print()
def _upload_dpaste(content: str) -> str | None:
"""Upload content to dpaste.org. Returns URL or None."""
import urllib.request
import urllib.parse
data = urllib.parse.urlencode({
"content": content,
"syntax": "text",
"expiry_days": 7,
}).encode()
req = urllib.request.Request(
"https://dpaste.org/api/",
data=data,
headers={"User-Agent": "hermes-agent/debug"},
)
with urllib.request.urlopen(req, timeout=10) as resp:
url = resp.read().decode().strip()
if url.startswith("http"):
return url
return None
def _upload_0x0st(content: str) -> str | None:
"""Upload content to 0x0.st. Returns URL or None."""
import urllib.request
import io
# 0x0.st expects multipart form with a file field
boundary = "----HermesDebugBoundary"
body = (
f"--{boundary}\r\n"
f'Content-Disposition: form-data; name="file"; filename="debug.txt"\r\n'
f"Content-Type: text/plain\r\n\r\n"
f"{content}\r\n"
f"--{boundary}--\r\n"
).encode()
req = urllib.request.Request(
"https://0x0.st",
data=body,
headers={
"Content-Type": f"multipart/form-data; boundary={boundary}",
"User-Agent": "hermes-agent/debug",
},
)
with urllib.request.urlopen(req, timeout=10) as resp:
url = resp.read().decode().strip()
if url.startswith("http"):
return url
return None
def show_config(self):
"""Display current configuration with kawaii ASCII art."""
# Get terminal config from environment (which was set from cli-config.yaml)
@@ -4511,8 +4321,6 @@ def _upload_0x0st(content: str) -> str | None:
self.show_help()
elif canonical == "profile":
self._handle_profile_command()
elif canonical == "debug":
self._handle_debug_command(cmd_original)
elif canonical == "tools":
self._handle_tools_command(cmd_original)
elif canonical == "toolsets":

View File

@@ -107,6 +107,7 @@ class SessionResetPolicy:
mode: str = "both" # "daily", "idle", "both", or "none"
at_hour: int = 4 # Hour for daily reset (0-23, local time)
idle_minutes: int = 1440 # Minutes of inactivity before reset (24 hours)
max_messages: int = 200 # Max messages per session before forced checkpoint+restart (0 = unlimited)
notify: bool = True # Send a notification to the user when auto-reset occurs
notify_exclude_platforms: tuple = ("api_server", "webhook") # Platforms that don't get reset notifications
@@ -115,6 +116,7 @@ class SessionResetPolicy:
"mode": self.mode,
"at_hour": self.at_hour,
"idle_minutes": self.idle_minutes,
"max_messages": self.max_messages,
"notify": self.notify,
"notify_exclude_platforms": list(self.notify_exclude_platforms),
}
@@ -125,12 +127,14 @@ class SessionResetPolicy:
mode = data.get("mode")
at_hour = data.get("at_hour")
idle_minutes = data.get("idle_minutes")
max_messages = data.get("max_messages")
notify = data.get("notify")
exclude = data.get("notify_exclude_platforms")
return cls(
mode=mode if mode is not None else "both",
at_hour=at_hour if at_hour is not None else 4,
idle_minutes=idle_minutes if idle_minutes is not None else 1440,
max_messages=max_messages if max_messages is not None else 200,
notify=notify if notify is not None else True,
notify_exclude_platforms=tuple(exclude) if exclude is not None else ("api_server", "webhook"),
)

View File

@@ -2343,6 +2343,12 @@ class GatewayRunner:
reset_reason = getattr(session_entry, 'auto_reset_reason', None) or 'idle'
if reset_reason == "daily":
context_note = "[System note: The user's session was automatically reset by the daily schedule. This is a fresh conversation with no prior context.]"
elif reset_reason == "message_limit":
context_note = (
"[System note: The user's previous session reached the message limit "
"and was automatically checkpointed and rotated. This is a fresh session. "
"If the user references something from before, you can search session history.]"
)
else:
context_note = "[System note: The user's previous session expired due to inactivity. This is a fresh conversation with no prior context.]"
context_prompt = context_note + "\n\n" + context_prompt
@@ -2368,16 +2374,18 @@ class GatewayRunner:
if adapter:
if reset_reason == "daily":
reason_text = f"daily schedule at {policy.at_hour}:00"
elif reset_reason == "message_limit":
reason_text = f"reached {policy.max_messages} message limit"
else:
hours = policy.idle_minutes // 60
mins = policy.idle_minutes % 60
duration = f"{hours}h" if not mins else f"{hours}h {mins}m" if hours else f"{mins}m"
reason_text = f"inactive for {duration}"
notice = (
f"◐ Session automatically reset ({reason_text}). "
f"Conversation history cleared.\n"
f"◐ Session automatically rotated ({reason_text}). "
f"Conversation was preserved via checkpoint.\n"
f"Use /resume to browse and restore a previous session.\n"
f"Adjust reset timing in config.yaml under session_reset."
f"Adjust limits in config.yaml under session_reset."
)
try:
session_info = self._format_session_info()
@@ -3073,6 +3081,39 @@ class GatewayRunner:
last_prompt_tokens=agent_result.get("last_prompt_tokens", 0),
)
# Marathon session limit (#326): check if we hit the message cap.
# Auto-checkpoint filesystem and rotate session.
try:
_post_limit = self.session_store.get_message_limit_info(session_key)
if _post_limit["at_limit"] and _post_limit["max_messages"] > 0:
logger.info(
"[Marathon] Session %s hit message limit (%d/%d). Rotating.",
session_key, _post_limit["message_count"], _post_limit["max_messages"],
)
# Attempt filesystem checkpoint before rotation
try:
from tools.checkpoint_manager import CheckpointManager
_cp_cfg_path = _hermes_home / "config.yaml"
if _cp_cfg_path.exists():
import yaml as _cp_yaml
with open(_cp_cfg_path, encoding="utf-8") as _cpf:
_cp_data = _cp_yaml.safe_load(_cpf) or {}
_cp_settings = _cp_data.get("checkpoints", {})
if _cp_settings.get("enabled"):
_cwd = _cp_settings.get("working_dir") or os.getcwd()
mgr = CheckpointManager(max_checkpoints=_cp_settings.get("max_checkpoints", 20))
cp = mgr.create_checkpoint(str(_cwd), label=f"marathon-{session_entry.session_id[:8]}")
if cp:
logger.info("[Marathon] Checkpoint: %s", cp.label)
except Exception as cp_err:
logger.debug("[Marathon] Checkpoint failed (non-fatal): %s", cp_err)
new_entry = self.session_store.reset_session(session_key)
if new_entry:
logger.info("[Marathon] Rotated: %s -> %s", session_entry.session_id, new_entry.session_id)
except Exception as rot_err:
logger.debug("[Marathon] Rotation check failed: %s", rot_err)
# Auto voice reply: send TTS audio before the text response
_already_sent = bool(agent_result.get("already_sent"))
if self._should_send_voice_reply(event, response, agent_messages, already_sent=_already_sent):
@@ -6538,6 +6579,26 @@ class GatewayRunner:
if self._ephemeral_system_prompt:
combined_ephemeral = (combined_ephemeral + "\n\n" + self._ephemeral_system_prompt).strip()
# Marathon session limit warning (#326)
try:
_limit_info = self.session_store.get_message_limit_info(session_key)
if _limit_info["near_limit"] and not _limit_info["at_limit"]:
_remaining = _limit_info["remaining"]
_limit_warn = (
f"[SESSION LIMIT: This session has {_limit_info['message_count']} messages. "
f"Only {_remaining} message(s) remain before automatic session rotation at "
f"{_limit_info['max_messages']} messages. Start wrapping up and save important state.]"
)
combined_ephemeral = (combined_ephemeral + "\n\n" + _limit_warn).strip()
elif _limit_info["at_limit"]:
_limit_warn = (
f"[SESSION LIMIT REACHED: This session has hit the {_limit_info['max_messages']} "
f"message limit. This is your FINAL response. Summarize accomplishments and next steps.]"
)
combined_ephemeral = (combined_ephemeral + "\n\n" + _limit_warn).strip()
except Exception:
pass
# Re-read .env and config for fresh credentials (gateway is long-lived,
# keys may change without restart).
try:

View File

@@ -383,7 +383,11 @@ class SessionEntry:
# survives gateway restarts (the old in-memory _pre_flushed_sessions
# set was lost on restart, causing redundant re-flushes).
memory_flushed: bool = False
# Marathon session limit tracking (#326).
# Counts total messages (user + assistant + tool) in this session.
message_count: int = 0
def to_dict(self) -> Dict[str, Any]:
result = {
"session_key": self.session_key,
@@ -402,6 +406,7 @@ class SessionEntry:
"estimated_cost_usd": self.estimated_cost_usd,
"cost_status": self.cost_status,
"memory_flushed": self.memory_flushed,
"message_count": self.message_count,
}
if self.origin:
result["origin"] = self.origin.to_dict()
@@ -438,6 +443,7 @@ class SessionEntry:
estimated_cost_usd=data.get("estimated_cost_usd", 0.0),
cost_status=data.get("cost_status", "unknown"),
memory_flushed=data.get("memory_flushed", False),
message_count=data.get("message_count", 0),
)
@@ -643,6 +649,9 @@ class SessionStore:
)
if policy.mode == "none":
# Even with mode=none, enforce message_limit if set
if policy.max_messages > 0 and entry.message_count >= policy.max_messages:
return "message_limit"
return None
now = _now()
@@ -664,7 +673,11 @@ class SessionStore:
if entry.updated_at < today_reset:
return "daily"
# Marathon session limit (#326): force checkpoint+restart at max_messages
if policy.max_messages > 0 and entry.message_count >= policy.max_messages:
return "message_limit"
return None
def has_any_sessions(self) -> bool:
@@ -822,6 +835,43 @@ class SessionStore:
entry.last_prompt_tokens = last_prompt_tokens
self._save()
def get_message_limit_info(self, session_key: str) -> Dict[str, Any]:
"""Get message count and limit info for a session (#326)."""
with self._lock:
self._ensure_loaded_locked()
entry = self._entries.get(session_key)
if not entry:
return {"message_count": 0, "max_messages": 0, "remaining": 0,
"near_limit": False, "at_limit": False, "threshold": 0.0}
policy = self.config.get_reset_policy(
platform=entry.platform,
session_type=entry.chat_type,
)
max_msgs = policy.max_messages
count = entry.message_count
remaining = max(0, max_msgs - count) if max_msgs > 0 else float("inf")
threshold = count / max_msgs if max_msgs > 0 else 0.0
return {
"message_count": count,
"max_messages": max_msgs,
"remaining": remaining,
"near_limit": max_msgs > 0 and count >= int(max_msgs * 0.85),
"at_limit": max_msgs > 0 and count >= max_msgs,
"threshold": threshold,
}
def reset_message_count(self, session_key: str) -> None:
"""Reset the message count to zero for a session (#326)."""
with self._lock:
self._ensure_loaded_locked()
entry = self._entries.get(session_key)
if entry:
entry.message_count = 0
self._save()
def reset_session(self, session_key: str) -> Optional[SessionEntry]:
"""Force reset a session, creating a new session ID."""
db_end_session_id = None
@@ -849,6 +899,7 @@ class SessionStore:
display_name=old_entry.display_name,
platform=old_entry.platform,
chat_type=old_entry.chat_type,
message_count=0, # Fresh count after rotation (#326)
)
self._entries[session_key] = new_entry
@@ -908,6 +959,7 @@ class SessionStore:
display_name=old_entry.display_name,
platform=old_entry.platform,
chat_type=old_entry.chat_type,
message_count=0, # Fresh count after rotation (#326)
)
self._entries[session_key] = new_entry
@@ -966,6 +1018,16 @@ class SessionStore:
transcript_path = self.get_transcript_path(session_id)
with open(transcript_path, "a", encoding="utf-8") as f:
f.write(json.dumps(message, ensure_ascii=False) + "\n")
# Increment message count for marathon session tracking (#326)
# Skip counting session_meta entries (tool defs, metadata)
if message.get("role") != "session_meta":
with self._lock:
for entry in self._entries.values():
if entry.session_id == session_id:
entry.message_count += 1
self._save()
break
def rewrite_transcript(self, session_id: str, messages: List[Dict[str, Any]]) -> None:
"""Replace the entire transcript for a session with new messages.

View File

@@ -0,0 +1,184 @@
"""Tests for marathon session limits (#326)."""
import pytest
from datetime import datetime
from pathlib import Path
from tempfile import mkdtemp
from gateway.config import GatewayConfig, Platform, SessionResetPolicy
from gateway.session import SessionEntry, SessionSource, SessionStore
def _source(platform=Platform.LOCAL, chat_id="test"):
return SessionSource(platform=platform, chat_id=chat_id, chat_type="dm", user_id="u1")
def _store(max_messages=200, mode="both"):
cfg = GatewayConfig()
cfg.default_reset_policy = SessionResetPolicy(mode=mode, max_messages=max_messages)
return SessionStore(Path(mkdtemp()), cfg)
class TestSessionResetPolicyMaxMessages:
def test_default(self):
assert SessionResetPolicy().max_messages == 200
def test_custom(self):
assert SessionResetPolicy(max_messages=500).max_messages == 500
def test_unlimited(self):
assert SessionResetPolicy(max_messages=0).max_messages == 0
def test_to_dict(self):
d = SessionResetPolicy(max_messages=300).to_dict()
assert d["max_messages"] == 300
def test_from_dict(self):
p = SessionResetPolicy.from_dict({"max_messages": 150})
assert p.max_messages == 150
def test_from_dict_default(self):
assert SessionResetPolicy.from_dict({}).max_messages == 200
class TestSessionEntryMessageCount:
def test_default(self):
e = SessionEntry(session_key="k", session_id="s", created_at=datetime.now(), updated_at=datetime.now())
assert e.message_count == 0
def test_to_dict(self):
e = SessionEntry(session_key="k", session_id="s", created_at=datetime.now(), updated_at=datetime.now(), message_count=42)
assert e.to_dict()["message_count"] == 42
def test_from_dict(self):
e = SessionEntry.from_dict({"session_key": "k", "session_id": "s", "created_at": "2026-01-01T00:00:00", "updated_at": "2026-01-01T00:00:00", "message_count": 99})
assert e.message_count == 99
class TestShouldResetMessageLimit:
def test_at_limit(self):
s = _store()
src = _source()
e = s.get_or_create_session(src)
e.message_count = 200
assert s._should_reset(e, src) == "message_limit"
def test_over_limit(self):
s = _store()
src = _source()
e = s.get_or_create_session(src)
e.message_count = 250
assert s._should_reset(e, src) == "message_limit"
def test_below_limit(self):
s = _store()
src = _source()
e = s.get_or_create_session(src)
e.message_count = 100
assert s._should_reset(e, src) is None
def test_unlimited(self):
s = _store(max_messages=0, mode="none")
src = _source()
e = s.get_or_create_session(src)
e.message_count = 9999
assert s._should_reset(e, src) is None
def test_custom_limit(self):
s = _store(max_messages=50)
src = _source()
e = s.get_or_create_session(src)
e.message_count = 50
assert s._should_reset(e, src) == "message_limit"
def test_just_under(self):
s = _store(max_messages=50)
src = _source()
e = s.get_or_create_session(src)
e.message_count = 49
assert s._should_reset(e, src) is None
class TestAppendIncrementsCount:
def test_user_message(self):
s = _store()
src = _source()
e = s.get_or_create_session(src)
s.append_to_transcript(e.session_id, {"role": "user", "content": "hi"})
e = s.get_or_create_session(src)
assert e.message_count == 1
def test_assistant_message(self):
s = _store()
src = _source()
e = s.get_or_create_session(src)
s.append_to_transcript(e.session_id, {"role": "user", "content": "hi"})
s.append_to_transcript(e.session_id, {"role": "assistant", "content": "hello"})
e = s.get_or_create_session(src)
assert e.message_count == 2
def test_meta_not_counted(self):
s = _store()
src = _source()
e = s.get_or_create_session(src)
s.append_to_transcript(e.session_id, {"role": "session_meta", "tools": []})
e = s.get_or_create_session(src)
assert e.message_count == 0
class TestGetMessageLimitInfo:
def test_at_limit(self):
s = _store()
src = _source()
e = s.get_or_create_session(src)
e.message_count = 200
info = s.get_message_limit_info(e.session_key)
assert info["at_limit"] is True
assert info["near_limit"] is True
assert info["remaining"] == 0
def test_near_limit(self):
s = _store()
src = _source()
e = s.get_or_create_session(src)
e.message_count = 180
info = s.get_message_limit_info(e.session_key)
assert info["near_limit"] is True
assert info["at_limit"] is False
assert info["remaining"] == 20
def test_well_below(self):
s = _store()
src = _source()
e = s.get_or_create_session(src)
e.message_count = 50
info = s.get_message_limit_info(e.session_key)
assert info["near_limit"] is False
assert info["at_limit"] is False
def test_unknown(self):
s = _store()
info = s.get_message_limit_info("nonexistent")
assert info["at_limit"] is False
class TestResetMessageCount:
def test_reset(self):
s = _store()
src = _source()
e = s.get_or_create_session(src)
e.message_count = 150
s.reset_message_count(e.session_key)
assert s.get_message_limit_info(e.session_key)["message_count"] == 0
class TestSessionRotation:
def test_fresh_count_after_reset(self):
s = _store()
src = _source()
e = s.get_or_create_session(src)
e.message_count = 200
new = s.reset_session(e.session_key)
assert new is not None
assert new.message_count == 0
assert new.session_id != e.session_id