Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript

docs(mcp-host): correct persistence comments and document the sweep window

Alfredo Lopeza292ef3c4a06
diff --git a/docs/architecture/host-storage-layout.md b/docs/architecture/host-storage-layout.md
index 3507883ce..f9c357ba9 100644
--- a/docs/architecture/host-storage-layout.md
+++ b/docs/architecture/host-storage-layout.md
@@ -210,10 +210,21 @@ renames the entry.
completes none of them for `CLERUM_DB_WORKER_STALL_TIMEOUT_MS` (default
`30000`, at least `1000`, at most `2147483647` and above
`CLERUM_DB_PERSIST_SYNC_TIMEOUT_MS`, or config load fails), the queue fails
- the same way and the worker is terminated.
+ the same way and the worker is terminated. The bound counts completed
+ operations, so a single operation that runs longer than it counts as a
+ stall too: the boot reaps of processing and awaiting-approval sessions and
+ the checkpoint the worker runs when it closes the database are such single
+ operations.
- At shutdown mcp-host waits for every queued write, bounded only by that
stall timeout and the Pod's termination grace period. A persistence failure
- during shutdown exits 1 instead of 0.
+ detected during shutdown exits 1 instead of 0. With the default settings
+ the stall timeout (30 s) equals the default grace period (30 s), so a worker
+ that stalls during shutdown is killed by the kubelet first and the container
+ ends with SIGKILL (137), not 1.
+- The boot retention sweep of session search runs before the Host listens:
+ `main.ts` awaits it before bootstrap, so its duration counts against the
+ Host startup probe window (310 s; 630 s for desktop Hosts). A restart keeps
+ the batches already committed.
- A failed synchronous write, such as `SQLITE_FULL` on the first write of a
turn, rejects only that request; the queue stays usable and the process
keeps running. A full PVC therefore shows either as turns that fail while
diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.json
index e17d1645e..98cd6f89c 100644
--- a/mcp-host/package-lock.json
+++ b/mcp-host/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.591",
+ "version": "0.1.592",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-mcp-host",
- "version": "0.1.591",
+ "version": "0.1.592",
"license": "SEE LICENSE IN LICENSE",
"dependencies": {
"@anthropic-ai/sdk": "^0.32.0",
diff --git a/mcp-host/package.json b/mcp-host/package.json
index 121a0584d..3abe60399 100644
--- a/mcp-host/package.json
+++ b/mcp-host/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.591",
+ "version": "0.1.592",
"description": "MCP Host - reads Host CRD and provides LLM access via OpenAI/Claude",
"main": "dist/main.js",
"engines": {
diff --git a/mcp-host/src/core/conversation/persistence/persistQueue.ts b/mcp-host/src/core/conversation/persistence/persistQueue.ts
index 1a1fb0b26..8d2228ce0 100644
--- a/mcp-host/src/core/conversation/persistence/persistQueue.ts
+++ b/mcp-host/src/core/conversation/persistence/persistQueue.ts
@@ -265,8 +265,9 @@ export class PersistQueue {
}
/**
- * Wait until every pending async write settles. Intended for graceful
- * shutdown so SIGTERM doesn't truncate the durable trail.
+ * Wait for the keyed async chains, not for in-flight sync operations. Used
+ * by the stateless suspend checkpoint (`main.ts`, `flushFinalCheckpoint`).
+ * `close()` does its own stricter wait.
*/
async drain(): Promise<void> {
const chains = Array.from(this.writeChain.values())
diff --git a/mcp-host/src/core/sessionSearch/service.ts b/mcp-host/src/core/sessionSearch/service.ts
index 34af5b417..651c47cb0 100644
--- a/mcp-host/src/core/sessionSearch/service.ts
+++ b/mcp-host/src/core/sessionSearch/service.ts
@@ -93,8 +93,12 @@ export {
/**
* Rows one retention-sweep operation may delete. Measured on the real worker
- * with 400k expired messages: max 123 ms per batch, far below the sync
- * timeout and the worker progress bound.
+ * with 400k expired messages: max 123 ms per message-phase batch. Session
+ * phase, with 200k expired sessions and the `parent_session_id` index
+ * (migration 017): max 32 ms per batch (about 2.4 s without the index).
+ * Both are far below the sync timeout and the worker progress bound.
+ * The cap counts rows, not bytes: the FTS delete trigger re-tokenizes each
+ * deleted message's content, so a batch of very large messages takes longer.
*/
const RETENTION_SWEEP_BATCH_ROWS = 250
diff --git a/mcp-host/src/main.ts b/mcp-host/src/main.ts
index 10bbf93aa..e400c87ad 100644
--- a/mcp-host/src/main.ts
+++ b/mcp-host/src/main.ts
@@ -1639,7 +1639,8 @@ async function initializeConversationStore(): Promise<ConversationStoreHandle |
onPersistFailure: exitOnPersistFailure(() => isShuttingDown, {
// Flush buffered usage and governed-run events before the exit 1.
// Marking the Host as shutting down keeps a SIGTERM during the flush
- // from running the graceful path, which exits 0.
+ // from starting the graceful shutdown path as a second, concurrent
+ // shutdown.
beforeExit: async () => {
isShuttingDown = true
usageReporter?.stop()