templates/openagents: correct why channel history is lost, and drop the Scope section
What
openagents 1.0.0 shipped with the wrong explanation of why channel history does not come back
after a restart, and with a Scope section the README no longer wants. This corrects the
explanation, drops the section, and takes the template to 1.0.1 because 1.0.0's canonical tag is
already published.
How
The explanation was wrong. The claim that shipped was that the messaging mod writes its
history only from shutdown(), so channel history never survives. Reading
sdk/src/openagents/mods/workspace/messaging/, _save_message_history has two call sites:
mod.py:170 | _save_interval = 50, so the mod flushes every 50 messages |
message_storage_helper.py | dump_interval_minutes = 10, a second flush every 10 minutes |
mod.py:338 | shutdown(), the third |
The deploy that verified 1.0.0 posted one message and restarted a few minutes later. Neither
threshold fired, so nothing was ever written, and the storage directory holds no history file and
no dump rather than an empty one. The same instance's forum directory holds the metadata.json
written the minute its topic was created, which is the contrast that rules out the volume and the
platform: one mod in this app batches, the other writes through.
So the accurate statement is narrower. Whatever arrived since the last flush is in memory only.
alwaysOn: true still earns its place, because scale-to-zero on a quiet network drops that
tail with nobody having restarted anything. The manifest comment now argues it from the batching
rather than from a mod that never persists.
The Scope section comes out. Its two caveats go back into the body where a reader meets
them in context: the channel one as part of what the volume does and does not hold, corrected,
and the MCP one back in the walkthrough step that sends people to /api.
1.0.0 -> 1.0.1. version-guard refuses a manifest change against a published canonical tag,
correctly: overwriting :1.0.0 would drift instances already deployed. The Dockerfile and
entrypoint.sh are untouched, so the rebuild carries the same image content under the new tag.
One for upstream, not worked around here
shutdown() calls self.message_history.clear() and self.files.clear() and only then calls
_save_message_history() and _save_file_metadata(), both of which open their file with "w"
and write whatever dict they are handed. A graceful shutdown therefore truncates
message_history.json and files_metadata.json to empty, discarding batches that had already
been written, while an abrupt stop loses only the unflushed tail. On this mod a clean shutdown is
the more destructive of the two. Left alone here because it belongs in openagents-org/openagents.
Verify
$ node scripts/version-guard.mjs origin/main
✓ openagents: 1.0.0 -> 1.0.1
$ npm run lint
✓ openagents
$ npm run check-categories
✓ 32 templates and the UI snapshot match the platform's 15 categories
$ npx vitest run templates/scripts
Test Files 16 passed (16)
Tests 453 passed (453)
The two source facts, read on the pinned tree:
mod.py:170 self._save_interval = 50 # Save every 50 messages
mod.py:2207 self._message_count_since_save += 1
mod.py:2208 if self._message_count_since_save >= self._save_interval:
mod.py:2209 self._save_message_history()
message_storage_helper.py:32 dump_interval_minutes: int = 10,
And on the still-running verification instance, the contrast between the two mods:
mods/…forum/ metadata.json (written the minute the topic was created)
topics/
mods/…messaging/ files/ (no message_history.json, no dump)
🤖 Generated with Claude Code
Summary by cubic
Corrects the openagents template's explanation of why channel history is lost after a restart, and removes the Scope section.
The claim that shipped with 1.0.0 — that the messaging mod writes history only from shutdown() and channels never survive — is wrong. The mod flushes every 50 messages and dumps every 10 minutes; the verification behind 1.0.0 posted a single message, so neither threshold fired and nothing was ever written. What is true is narrower: whatever arrived since the last write is in memory only. alwaysOn: true stays justified, now argued from that batching. The Scope section's caveats move back into the README body, the channel one corrected and the MCP one as it stood. Bumps the manifest to 1.0.1 because the 1.0.0 canonical tag is already published; image content is unchanged.
Upstream, not worked around here
A graceful shutdown is more destructive than an abrupt stop: shutdown() clears the history and file dicts before saving with "w", truncating files that already held batches. Left for openagents-org/openagents.