@fractal-synapse/conversation-monitor-plugin

Tracks conversation activity across all agents and fires an inactivity event after a configurable period of silence (default: 10 minutes). The plugin persists one record per conversation to disk (conversation-monitor.json) so it can detect conversations that went inactive while the app was closed. On startup it immediately checks all persisted records, meaning no inactivity window is missed.

---

ConversationRecord

Persisted to disk — one entry per conversation ever seen.

Field	Type	Description
agentId	string	Agent instance ID (e.g. severin-2026-04-04-1030-00-000)
definitionName	string	Agent definition key (e.g. severin)
firstTurnAt	string	ISO timestamp — when this conversation first had activity
lastTurnAt	string	ISO timestamp — when this conversation last had activity
turnCount	number	Total number of assistant responses recorded
inactivityFired	boolean	true after inactivity fires; reset to false on new activity

InactivityEvent

Passed to onInactivity() subscribers.

Field	Type	Description
agentId	string	Agent instance ID
definitionName	string	Agent definition key
firstTurnAt	string	ISO timestamp of the conversation's first activity
lastTurnAt	string	ISO timestamp of the conversation's last activity
turnCount	number	Total assistant responses recorded at the time inactivity fired

---

Constructor config

new ConversationMonitorPlugin({
  storage,               // Required — PluginStorageInterface
  logger,                // Optional — defaults to getLogger()
  inactivityThresholdMs, // Optional — default: 600_000 (10 minutes)
  checkIntervalMs,       // Optional — default: 60_000 (1 minute)
});

Field	Required	Default	Description
storage	Yes	—	PluginStorageInterface used to persist conversation-monitor.json
logger	No	getLogger()	Logger for diagnostic output
inactivityThresholdMs	No	600000 (10 min)	How long a conversation must be silent before the inactivity event fires
checkIntervalMs	No	60000 (1 min)	How often the plugin scans all records for expired conversations

---

How to subscribe

Other plugins can subscribe to inactivity events by finding the ConversationMonitorPlugin instance at init time and registering a callback via onInactivity().

import type { ConversationMonitorPlugin, InactivityEvent } from '@fractal-synapse/conversation-monitor-plugin';

// Inside AnotherPlugin.initializeAgent(agent):
const monitor = (agent as any).plugins?.find(
  (p: any) => p.name === 'conversation-monitor'
) as ConversationMonitorPlugin | undefined;

if (monitor) {
  const handler = async (event: InactivityEvent) => {
    // Load conversation from storage by event.agentId and process it
  };
  monitor.onInactivity(handler);
}

Note: Store the handler reference so you can call monitor.offInactivity(handler) in cleanupAgent() if needed.