Skip to content

Manual meta checkpoint: /checkpoint command, save-on-quit, and a save_checkpoint tool#391

Merged
ziatdinovmax merged 1 commit into
mainfrom
meta-manual-checkpoint
Jul 24, 2026
Merged

Manual meta checkpoint: /checkpoint command, save-on-quit, and a save_checkpoint tool#391
ziatdinovmax merged 1 commit into
mainfrom
meta-manual-checkpoint

Conversation

@ziatdinovmax

Copy link
Copy Markdown
Owner

Summary

The meta (explore) session previously saved its state only automatically — every 10 messages, or when a chat error occurred. Quitting at the wrong moment could silently lose up to 9 messages of session state, including the record of recent delegations, and there was no way to ask for a save explicitly.

This PR adds manual checkpointing at the meta level, on all surfaces:

  • /checkpoint CLI command — saves the session state immediately and prints the checkpoint path (listed in /help).
  • Checkpoint on exit/quit, /exit, and Ctrl-C/EOF now save a checkpoint before leaving, so a resumed session always has the full delegation record.
  • "Save a checkpoint" from chat, including the UI — the meta now has a save_checkpoint tool (the planning and analysis specialists already had one), so asking the meta to save the session works in the UI chat as well as the CLI.

A failed explicit save now reports an error instead of quietly logging a warning, so a manual save can't silently do nothing.


Technical details

  • MetaOrchestratorAgent.save_checkpoint() (meta_orchestrator.py): public on-demand save. Wraps _auto_checkpoint() (which now returns a bool), flushes chat history via _save_history(), resets last_checkpoint_message_count so the 10-message auto-save timer restarts, returns the checkpoint path, and raises RuntimeError on write failure.
  • save_checkpoint meta tool (meta_orchestrator_tools.py): registered alongside get_delegation_history, mirroring the children's tool shape; returns {status, checkpoint_path, delegations_saved} JSON. This is what makes the feature reachable from the UI — the UI chat input passes text straight to the agent with no slash-command interception, so tool-mediated saving is the UI path.
  • CLI (cli/meta.py): _save_checkpoint() helper (reports failure, never raises into the loop), /checkpoint command, save on the QUIT branch and on the EOFError/KeyboardInterrupt branch of the main loop.
  • Checkpoint content is unchanged (meta mode, message count, instantiated children, delegation ledger); children continue to checkpoint themselves in their own sub-directories.

Testing: offline smoke tests — happy path writes correct state and resets the timer; unwritable path raises RuntimeError; tool wrapper returns clean success/error JSON; /checkpoint handles success and failure without breaking the CLI loop; case-insensitive command parsing. Existing offline meta suites pass (21/21: test_meta_simulation_delegation, test_meta_fanout_robustness, test_file_prep_metadata_only).

Known limits: no live end-to-end run of the UI chat → save_checkpoint tool → resume cycle yet; the UI still has no dedicated save button (chat-mediated only).

…save-on-quit

The meta orchestrator could only checkpoint automatically (every 10
messages) or on a chat error, so quitting could silently drop up to 9
messages of delegation-ledger state. Now:

- MetaOrchestratorAgent.save_checkpoint(): public on-demand save that
  also flushes chat history, resets the auto-save timer, and raises
  RuntimeError on write failure instead of only logging a warning.
- save_checkpoint meta tool (mirrors the planning/analysis children),
  so "save a checkpoint" works from chat in both the CLI and the UI.
- CLI: /checkpoint command, and a checkpoint is saved on /quit and on
  Ctrl-C/EOF exit.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@ziatdinovmax
ziatdinovmax merged commit 35cb6bf into main Jul 24, 2026
1 check passed
ziatdinovmax added a commit that referenced this pull request Jul 24, 2026
One conflict: both sides registered a new meta tool after
get_delegation_history — main's save_checkpoint (#391) and this
branch's attach_knowledge_base / add_to_knowledge_base. All three kept.
The auto-merged checkpoint machinery composes cleanly: _auto_checkpoint
keeps #391's success boolean AND this branch's knowledge_dir
persistence; verified by smoke (one registry carries all three tools;
checkpoint round-trip incl. knowledge_dir) and 75 offline tests.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant