Issue Station
Sign In
Tools hereToolbox

hermes - ✅(Solved) Fix [Bug]: [Gateway] CheckpointManager snapshots not created in Gateway mode — file operations lack rollback protection on messaging platforms [2 pull requests, 1 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
NousResearch/hermes-agent#11409•Fetched 2026-04-18 06:01:16
View on GitHub
Comments
0
Participants
1
Timeline
4
Reactions
0
Author
ham0ndham0nd
Participants
ham0ndham0nd
Timeline (top)
cross-referenced ×2labeled ×1referenced ×1

Error Message

Additional Logs / Traceback (optional)

Root Cause

Actual Behavior
No snapshots are created. Gateway has the config-reading code and the /rollback handler, but the core ensure_checkpoint() hook that exists in run_agent.py is completely absent from gateway/run.py.
Root Cause Analysis
In run_agent.py (CLI), checkpoint calls exist at two places in the tool-execution loop (lines ~7068 and ~7323):
if function_name in ("write_file", "patch") and self._checkpoint_mgr.enabled:

Fix Action

Fix / Workaround

CheckpointManager already exists and works in CLI mode (run_agent.py), but the Gateway (run.py) never calls ensure_checkpoint() when processing file-mutating tool calls (write_file, patch). As a result, even with checkpoints.enabled: true in config.yaml, no snapshots are created — the /rollback command finds no checkpoints to restore. The CheckpointManager is only used in the Gateway for the /rollback command itself (to list/restore snapshots), but the actual snapshot-taking during file operations is missing.

Restart hermes gateway Ask the agent to write_file or patch a file Run /rollback — response says "No checkpoints found" Inspect ~/.hermes/checkpoints/ — directory is empty

Every write_file and patch call should automatically create a git snapshot before execution, viewable via /rollback list and restorable via /rollback <n>.

PR fix notes

PR #11428: fix(gateway): pass checkpoint config to AIAgent so snapshots work in gateway mode

Description (problem / solution / changelog)

Fixes #11409

Problem: Gateway mode (run.py) never passed checkpoints_enabled or checkpoint_max_snapshots to AIAgent, so ensure_checkpoint() was never called before file-mutating tool calls (write_file, patch). The /rollback command then found no checkpoints.

Fix: Read checkpoints config from config.yaml in _run_agent() (handling both dict and bool shorthand forms) and pass the values to the AIAgent constructor — matching how run_agent.py already does it.

Tests: 6 new tests in tests/gateway/test_gateway_checkpoint_snapshots.py covering config parsing and AIAgent integration.

Changed files

  • gateway/run.py (modified, +11/-0)
  • tests/gateway/test_gateway_checkpoint_snapshots.py (added, +111/-0)

PR #11555: fix(gateway): snapshot checkpoints before write_file and patch

Description (problem / solution / changelog)

Summary

  • mirror the CLI checkpoint hook in gateway sessions for write_file and patch
  • reuse shared checkpoint config loading/building so /rollback and tool-triggered snapshots stay aligned
  • add focused gateway regression tests for the helper and _run_agent wiring

Problem

Gateway mode exposed /rollback, but never actually created snapshots before file-mutating tools. That left messaging platforms without the rollback protection already present in CLI mode.

Root cause

run_agent.py already calls ensure_checkpoint() before write_file / patch, but gateway/run.py only used CheckpointManager inside /rollback itself.

Fix

Attach a gateway tool_start_callback that snapshots the relevant working directory before write_file or patch begins, gated by the existing checkpoints.enabled config.

Fixes #11409

Testing

  • pytest -q -o addopts= tests/gateway/test_checkpoint_hooks.py
  • pytest -q -o addopts= tests/gateway/test_background_process_notifications.py -k 'watch_notification or build_process_event_source'
  • pytest -q -o addopts= tests/gateway/test_checkpoint_hooks.py tests/gateway/test_background_process_notifications.py -k 'watch_notification or build_process_event_source or checkpoint'

Changed files

  • gateway/run.py (modified, +61/-18)
  • tests/gateway/test_checkpoint_hooks.py (added, +173/-0)

Code Example

Actual Behavior
No snapshots are created. Gateway has the config-reading code and the /rollback handler, but the core ensure_checkpoint() hook that exists in run_agent.py is completely absent from gateway/run.py.
Root Cause Analysis
In run_agent.py (CLI), checkpoint calls exist at two places in the tool-execution loop (lines ~7068 and ~7323):
if function_name in ("write_file", "patch") and self._checkpoint_mgr.enabled:

    work_dir = self._checkpoint_mgr.get_working_dir_for_path(file_path)

    self._checkpoint_mgr.ensure_checkpoint(work_dir, f"before {function_name}")

These calls are completely absent from gateway/run.py. Gateway never imports or invokes ensure_checkpoint() in its message handling pipeline. It only uses CheckpointManager for the /rollback command (lines 5537–5559) to list/restore already-taken snapshots.
Proposed Fix
Add the same ensure_checkpoint() calls to gateway/run.py in the tool execution path, mirroring the logic already in run_agent.py. The config reading for checkpoints.enabled already exists in _handle_rollback_command() — reuse the same pattern to gate the checkpoint hooks.
Affected file: gateway/run.py
Similar reference implementation: run_agent.py lines 7068–7073 and 7323–7328

---
RAW_BUFFERClick to expand / collapse

Bug Description

CheckpointManager already exists and works in CLI mode (run_agent.py), but the Gateway (run.py) never calls ensure_checkpoint() when processing file-mutating tool calls (write_file, patch). As a result, even with checkpoints.enabled: true in config.yaml, no snapshots are created — the /rollback command finds no checkpoints to restore. The CheckpointManager is only used in the Gateway for the /rollback command itself (to list/restore snapshots), but the actual snapshot-taking during file operations is missing.

Steps to Reproduce

Add to checkpoints:

enabled: true

max_snapshots: 50

: checkpoints:

enabled: true

max_snapshots: 50

Restart hermes gateway Ask the agent to write_file or patch a file Run /rollback — response says "No checkpoints found" Inspect ~/.hermes/checkpoints/ — directory is empty

Expected Behavior

Every write_file and patch call should automatically create a git snapshot before execution, viewable via /rollback list and restorable via /rollback <n>.

Actual Behavior

No snapshots are created. Gateway has the config-reading code and the /rollback handler, but the core ensure_checkpoint() hook that exists in run_agent.py is completely absent from gateway/run.py.

Affected Component

Gateway (Telegram/Discord/Slack/WhatsApp)

Messaging Platform (if gateway-related)

No response

Debug Report

Actual Behavior
No snapshots are created. Gateway has the config-reading code and the /rollback handler, but the core ensure_checkpoint() hook that exists in run_agent.py is completely absent from gateway/run.py.
Root Cause Analysis
In run_agent.py (CLI), checkpoint calls exist at two places in the tool-execution loop (lines ~7068 and ~7323):
if function_name in ("write_file", "patch") and self._checkpoint_mgr.enabled:

    work_dir = self._checkpoint_mgr.get_working_dir_for_path(file_path)

    self._checkpoint_mgr.ensure_checkpoint(work_dir, f"before {function_name}")

These calls are completely absent from gateway/run.py. Gateway never imports or invokes ensure_checkpoint() in its message handling pipeline. It only uses CheckpointManager for the /rollback command (lines 5537–5559) to list/restore already-taken snapshots.
Proposed Fix
Add the same ensure_checkpoint() calls to gateway/run.py in the tool execution path, mirroring the logic already in run_agent.py. The config reading for checkpoints.enabled already exists in _handle_rollback_command() — reuse the same pattern to gate the checkpoint hooks.
Affected file: gateway/run.py
Similar reference implementation: run_agent.py lines 7068–7073 and 7323–7328

Operating System

docker

Python Version

No response

Hermes Version

No response

Additional Logs / Traceback (optional)

Root Cause Analysis (optional)

No response

Proposed Fix (optional)

No response

Are you willing to submit a PR for this?

  • I'd like to fix this myself and submit a PR

extent analysis

TL;DR

Add the ensure_checkpoint() calls to gateway/run.py in the tool execution path to create snapshots before file-mutating operations.

Guidance

  • Identify the tool execution path in gateway/run.py where write_file and patch operations are handled.
  • Add a conditional check for checkpoints.enabled in the config, similar to the one in run_agent.py.
  • Call ensure_checkpoint() before executing write_file and patch operations, passing the working directory and a descriptive message.
  • Verify that the CheckpointManager is properly initialized and configured in gateway/run.py.

Example

if function_name in ("write_file", "patch") and self._checkpoint_mgr.enabled:
    work_dir = self._checkpoint_mgr.get_working_dir_for_path(file_path)
    self._checkpoint_mgr.ensure_checkpoint(work_dir, f"before {function_name}")

Notes

The proposed fix assumes that the CheckpointManager is properly configured and initialized in gateway/run.py. Additional debugging may be required to ensure that the ensure_checkpoint() calls are being executed correctly.

Recommendation

Apply workaround: Add the ensure_checkpoint() calls to gateway/run.py as described, to enable snapshot creation for file-mutating operations. This fix is necessary to ensure that the /rollback command functions as expected.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#callback error#memory management#API rate limit#retriever error#indexing error

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING