agent-working-memory 0.5.6 → 0.6.1

package/src/coordination/events.ts

@@ -0,0 +1,90 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Typed internal event emitter for coordination.
+ * Lightweight Node EventEmitter wrapper with typed events.
+ * Used to decouple route handlers from side-effects (channel push, logging, etc).
+ */
+
+import { EventEmitter } from 'events';
+
+// ─── Event Payloads ──────────────────────────────────────────────
+
+export interface AssignmentCreatedEvent {
+  assignmentId: string;
+  agentId: string;
+  task: string;
+  workspace?: string;
+}
+
+export interface AssignmentUpdatedEvent {
+  assignmentId: string;
+  agentId: string | null;
+  status: string;
+  result?: string;
+}
+
+export interface AssignmentCompletedEvent {
+  assignmentId: string;
+  agentId: string | null;
+  result: string | null;
+}
+
+export interface AgentCheckinEvent {
+  agentId: string;
+  name: string;
+  role: string;
+  workspace?: string;
+}
+
+export interface AgentCheckoutEvent {
+  agentId: string;
+  name: string;
+}
+
+export interface SessionStartedEvent {
+  agentId: string;
+  channelId: string;
+}
+
+export interface SessionClosedEvent {
+  agentId: string;
+  channelId: string;
+}
+
+// ─── Event Map ───────────────────────────────────────────────────
+
+export interface CoordinationEvents {
+  'assignment.created': [AssignmentCreatedEvent];
+  'assignment.updated': [AssignmentUpdatedEvent];
+  'assignment.completed': [AssignmentCompletedEvent];
+  'agent.checkin': [AgentCheckinEvent];
+  'agent.checkout': [AgentCheckoutEvent];
+  'session.started': [SessionStartedEvent];
+  'session.closed': [SessionClosedEvent];
+}
+
+// ─── Typed Event Bus ─────────────────────────────────────────────
+
+export class CoordinationEventBus extends EventEmitter {
+  emit<K extends keyof CoordinationEvents>(event: K, ...args: CoordinationEvents[K]): boolean {
+    return super.emit(event, ...args);
+  }
+
+  on<K extends keyof CoordinationEvents>(event: K, listener: (...args: CoordinationEvents[K]) => void): this {
+    return super.on(event, listener as (...args: unknown[]) => void);
+  }
+
+  once<K extends keyof CoordinationEvents>(event: K, listener: (...args: CoordinationEvents[K]) => void): this {
+    return super.once(event, listener as (...args: unknown[]) => void);
+  }
+
+  off<K extends keyof CoordinationEvents>(event: K, listener: (...args: CoordinationEvents[K]) => void): this {
+    return super.off(event, listener as (...args: unknown[]) => void);
+  }
+}
+
+/** Create a new coordination event bus. */
+export function createEventBus(): CoordinationEventBus {
+  return new CoordinationEventBus();
+}

package/src/coordination/index.ts

@@ -7,10 +7,29 @@
 
 import type { FastifyInstance } from 'fastify';
 import type Database from 'better-sqlite3';
+import type { EngramStore } from '../storage/sqlite.js';
 import { ZodError } from 'zod';
 import { initCoordinationTables } from './schema.js';
 import { registerCoordinationRoutes } from './routes.js';
-import { cleanSlate } from './stale.js';
+import { cleanSlate, pruneOldHeartbeats, purgeDeadAgents } from './stale.js';
+import { createWriteMutex, needsWriteLock } from './write-mutex.js';
+import { createEventBus, type CoordinationEventBus } from './events.js';
+import { loadPlugins, teardownPlugins } from './plugin-loader.js';
+
+export type * from './types.js';
+export { type CoordinationEventBus, type CoordinationEvents } from './events.js';
+export type { AWMPlugin, AWMPluginContext } from './plugin.js';
+
+/** Active cleanup intervals — cleared on shutdown. */
+const cleanupIntervals: NodeJS.Timeout[] = [];
+
+/** Singleton event bus for this coordination module instance. */
+let coordinationEventBus: CoordinationEventBus | null = null;
+
+/** Get the coordination event bus (available after initCoordination). */
+export function getEventBus(): CoordinationEventBus | null {
+  return coordinationEventBus;
+}
 
 /** Check if coordination is enabled via environment variable. */
 export function isCoordinationEnabled(): boolean {
@@ -19,15 +38,49 @@ export function isCoordinationEnabled(): boolean {
 }
 
 /** Initialize the coordination module: create tables, clean slate, mount routes, error handler. */
-export function initCoordination(app: FastifyInstance, db: Database.Database): void {
+export function initCoordination(app: FastifyInstance, db: Database.Database, store?: EngramStore): void {
   // Create coordination tables (idempotent)
   initCoordinationTables(db);
 
   // Clean slate: mark stale agents as dead from previous sessions
   cleanSlate(db);
 
+  // CORS — allow localhost origins only (coordination is local-only)
+  app.addHook('onRequest', async (request, reply) => {
+    const origin = request.headers.origin ?? '';
+    if (/^https?:\/\/localhost(:\d+)?$/.test(origin) || /^https?:\/\/127\.0\.0\.1(:\d+)?$/.test(origin)) {
+      reply.header('Access-Control-Allow-Origin', origin);
+      reply.header('Access-Control-Allow-Methods', 'GET, POST, PATCH, PUT, DELETE, OPTIONS');
+      reply.header('Access-Control-Allow-Headers', 'Content-Type, Authorization');
+    }
+    if (request.method === 'OPTIONS') {
+      return reply.code(204).send();
+    }
+  });
+
+  // Body size limit — 256KB max for coordination requests (tasks with context can be large)
+  app.addHook('onRoute', (routeOptions) => {
+    if (!routeOptions.bodyLimit) {
+      routeOptions.bodyLimit = 256_000;
+    }
+  });
+
+  // Write serialization: serialize POST/PATCH/PUT/DELETE through a mutex
+  // to prevent SQLITE_BUSY under 5+ concurrent worker burst
+  const writeMutex = createWriteMutex();
+  app.addHook('preHandler', async (request, reply) => {
+    if (needsWriteLock(request.method, request.url)) {
+      const release = await writeMutex.acquire();
+      // Release after response is sent (onResponse fires after reply)
+      reply.raw.on('finish', release);
+    }
+  });
+
+  // Create event bus for decoupled side-effects
+  coordinationEventBus = createEventBus();
+
   // Mount all coordination HTTP routes
-  registerCoordinationRoutes(app, db);
+  registerCoordinationRoutes(app, db, store, coordinationEventBus);
 
   // ZodError handler — coordination routes use .parse() which throws on invalid params
   app.setErrorHandler((error: Error & { statusCode?: number }, _request, reply) => {
@@ -43,5 +96,51 @@ export function initCoordination(app: FastifyInstance, db: Database.Database): v
     });
   });
 
+  // Periodic cleanup: prune heartbeat events every 30 min, purge dead agents every hour
+  cleanupIntervals.push(
+    setInterval(() => {
+      try { pruneOldHeartbeats(db); } catch { /* db may be closed */ }
+    }, 30 * 60 * 1000),
+    setInterval(() => {
+      try { purgeDeadAgents(db, 24); } catch { /* db may be closed */ }
+    }, 60 * 60 * 1000),
+  );
+
+  // Periodic channel liveness probe every 60s — mark unreachable sessions as disconnected
+  cleanupIntervals.push(
+    setInterval(async () => {
+      try {
+        const sessions = db.prepare(
+          `SELECT agent_id, channel_id FROM coord_channel_sessions WHERE status = 'connected'`
+        ).all() as Array<{ agent_id: string; channel_id: string }>;
+
+        for (const session of sessions) {
+          try {
+            const res = await fetch(`${session.channel_id}/health`, {
+              signal: AbortSignal.timeout(3000),
+            });
+            if (!res.ok) {
+              db.prepare(`UPDATE coord_channel_sessions SET status = 'disconnected' WHERE agent_id = ?`).run(session.agent_id);
+            }
+          } catch {
+            db.prepare(`UPDATE coord_channel_sessions SET status = 'disconnected' WHERE agent_id = ?`).run(session.agent_id);
+          }
+        }
+      } catch { /* db may be closed */ }
+    }, 60_000),
+  );
+
+  // Load plugins (async — fire and forget, errors logged per-plugin)
+  loadPlugins({ events: coordinationEventBus, db, fastify: app }).catch((err) => {
+    console.error('  [plugin] Plugin loader error:', (err as Error).message);
+  });
+
   console.log('  Coordination module enabled');
 }
+
+/** Stop periodic cleanup intervals and teardown plugins. Call on server shutdown. */
+export async function stopCoordinationCleanup(): Promise<void> {
+  for (const id of cleanupIntervals) clearInterval(id);
+  cleanupIntervals.length = 0;
+  await teardownPlugins();
+}

package/src/coordination/mcp-tools.ts

@@ -27,14 +27,19 @@ export function registerCoordinationTools(server: McpServer, db: Database.Databa
     async ({ agent_name, role, pid, capabilities, workspace }) => {
       const capsJson = capabilities ? JSON.stringify(capabilities) : null;
 
+      // Look up ANY existing agent with same name+workspace — including dead ones (upsert, reuse UUID)
       const existing = workspace
-        ? db.prepare(`SELECT id, status FROM coord_agents WHERE name = ? AND workspace = ? AND status != 'dead'`).get(agent_name, workspace) as { id: string; status: string } | undefined
-        : db.prepare(`SELECT id, status FROM coord_agents WHERE name = ? AND workspace IS NULL AND status != 'dead'`).get(agent_name) as { id: string; status: string } | undefined;
+        ? db.prepare(`SELECT id, status FROM coord_agents WHERE name = ? AND workspace = ? ORDER BY last_seen DESC LIMIT 1`).get(agent_name, workspace) as { id: string; status: string } | undefined
+        : db.prepare(`SELECT id, status FROM coord_agents WHERE name = ? AND workspace IS NULL ORDER BY last_seen DESC LIMIT 1`).get(agent_name) as { id: string; status: string } | undefined;
 
       if (existing) {
-        db.prepare(`UPDATE coord_agents SET last_seen = datetime('now'), pid = COALESCE(?, pid), capabilities = COALESCE(?, capabilities) WHERE id = ?`).run(pid ?? null, capsJson, existing.id);
-        db.prepare(`INSERT INTO coord_events (agent_id, event_type, detail) VALUES (?, 'heartbeat', ?)`).run(existing.id, `heartbeat from ${agent_name}`);
-        return { content: [{ type: 'text' as const, text: JSON.stringify({ agentId: existing.id, action: 'heartbeat', status: existing.status }) }] };
+        const wasDead = existing.status === 'dead';
+        db.prepare(`UPDATE coord_agents SET last_seen = datetime('now'), status = CASE WHEN status = 'dead' THEN 'idle' ELSE status END, pid = COALESCE(?, pid), capabilities = COALESCE(?, capabilities) WHERE id = ?`).run(pid ?? null, capsJson, existing.id);
+        const action = wasDead ? 'reconnected' : 'heartbeat';
+        const eventType = wasDead ? 'reconnected' : 'heartbeat';
+        const detail = wasDead ? `${agent_name} reconnected via MCP (was dead)` : `heartbeat from ${agent_name}`;
+        db.prepare(`INSERT INTO coord_events (agent_id, event_type, detail) VALUES (?, ?, ?)`).run(existing.id, eventType, detail);
+        return { content: [{ type: 'text' as const, text: JSON.stringify({ agentId: existing.id, action, status: wasDead ? 'idle' : existing.status }) }] };
       }
 
       const id = randomUUID();

package/src/coordination/peer-decisions.ts

@@ -0,0 +1,105 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Peer-decision injection for memory_recall.
+ *
+ * When coordination is enabled, memory_recall appends recent decisions
+ * made by OTHER agents that are relevant to the current recall query.
+ * This enables passive cross-agent knowledge sharing without explicit
+ * communication.
+ */
+
+import type Database from 'better-sqlite3';
+
+export interface PeerDecision {
+  id: number;
+  author_name: string;
+  assignment_id: string | null;
+  tags: string | null;
+  summary: string;
+  created_at: string;
+}
+
+/** Stop words filtered out before keyword matching. */
+const STOP_WORDS = new Set([
+  'that', 'this', 'with', 'from', 'have', 'been', 'will', 'when', 'what',
+  'which', 'then', 'than', 'into', 'over', 'after', 'some', 'more', 'also',
+  'most', 'other', 'each', 'such', 'only', 'just', 'about', 'there', 'their',
+  'where', 'would', 'could', 'should', 'these', 'those', 'make', 'made',
+  'using', 'used', 'call', 'calls', 'does', 'done', 'were', 'they',
+]);
+
+/**
+ * Extract significant keywords from a recall query for relevance matching.
+ * Returns up to maxKeywords words of length >= 4 that are not stop words.
+ */
+export function extractKeywords(query: string, maxKeywords = 8): string[] {
+  return query
+    .toLowerCase()
+    .replace(/[^a-z0-9\s]/g, ' ')
+    .split(/\s+/)
+    .filter(w => w.length >= 4 && !STOP_WORDS.has(w))
+    .slice(0, maxKeywords);
+}
+
+/**
+ * Query coord_decisions for recent decisions by agents OTHER than the current one
+ * that are relevant to the given query string.
+ *
+ * @param db         The shared coordination database handle.
+ * @param selfName   The current agent's name (AWM_AGENT_ID / WORKER_NAME). Excluded from results.
+ * @param query      The recall query text used for keyword relevance matching.
+ * @param windowHours  How far back to look (default 1 hour).
+ * @param limit      Maximum number of decisions to return (default 5).
+ * @returns Array of peer decisions, ordered newest-first. Empty array on any error.
+ */
+export function queryPeerDecisions(
+  db: Database.Database,
+  selfName: string,
+  query: string,
+  windowHours = 1,
+  limit = 5,
+): PeerDecision[] {
+  try {
+    const safeHours = Math.max(0.1, Math.min(windowHours, 168)); // 6min – 1 week
+    const safeLimit = Math.max(1, Math.min(limit, 50));
+    const keywords = extractKeywords(query);
+
+    const baseWhere = `
+      d.created_at >= datetime('now', '-${safeHours} hours')
+      AND a.name != ?
+    `;
+
+    const select = `
+      SELECT d.id, a.name AS author_name, d.assignment_id, d.tags, d.summary, d.created_at
+      FROM coord_decisions d
+      JOIN coord_agents a ON d.author_id = a.id
+    `;
+
+    if (keywords.length === 0) {
+      // No useful keywords — return the N most recent decisions from other agents
+      const sql = `${select} WHERE ${baseWhere} ORDER BY d.created_at DESC LIMIT ?`;
+      return db.prepare(sql).all(selfName, safeLimit) as PeerDecision[];
+    }
+
+    // Build keyword filter: match any keyword in summary or tags
+    const kwClauses = keywords.map(() => `(d.summary LIKE ? OR d.tags LIKE ?)`).join(' OR ');
+    const sql = `${select} WHERE ${baseWhere} AND (${kwClauses}) ORDER BY d.created_at DESC LIMIT ?`;
+    const kwParams = keywords.flatMap(kw => [`%${kw}%`, `%${kw}%`]);
+
+    return db.prepare(sql).all(selfName, ...kwParams, safeLimit) as PeerDecision[];
+  } catch {
+    return []; // non-fatal — peer decisions are best-effort
+  }
+}
+
+/**
+ * Format peer decisions as a text section to append to memory_recall output.
+ * Returns an empty string when there are no peer decisions.
+ */
+export function formatPeerDecisions(decisions: PeerDecision[], windowHours = 1): string {
+  if (decisions.length === 0) return '';
+  const label = windowHours === 1 ? '1h' : `${windowHours}h`;
+  const lines = decisions.map(d => `[${d.author_name}] ${d.summary}`);
+  return `\n--- Peer Decisions (last ${label}) ---\n${lines.join('\n')}`;
+}

package/src/coordination/plugin-loader.ts

@@ -0,0 +1,60 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Plugin loader for AWM coordination.
+ *
+ * Reads AWM_PLUGINS env var (comma-separated module paths or package names),
+ * dynamically imports each, and calls register() with the plugin context.
+ *
+ * Usage:
+ *   AWM_PLUGINS=./plugins/slack-notify.js,my-awm-plugin npm start
+ */
+
+import type { AWMPlugin, AWMPluginContext } from './plugin.js';
+
+/** Loaded plugin instances (for teardown). */
+const loadedPlugins: AWMPlugin[] = [];
+
+/**
+ * Load and register all plugins specified in AWM_PLUGINS env var.
+ * Errors in individual plugins are logged but don't prevent other plugins from loading.
+ */
+export async function loadPlugins(ctx: AWMPluginContext): Promise<void> {
+  const pluginList = process.env.AWM_PLUGINS;
+  if (!pluginList) return;
+
+  const paths = pluginList
+    .split(',')
+    .map((p) => p.trim())
+    .filter(Boolean);
+
+  for (const modulePath of paths) {
+    try {
+      const mod = await import(modulePath);
+      const plugin: AWMPlugin = mod.default ?? mod;
+
+      if (!plugin.name || typeof plugin.register !== 'function') {
+        console.warn(`  [plugin] Skipping ${modulePath}: missing name or register()`);
+        continue;
+      }
+
+      await plugin.register(ctx);
+      loadedPlugins.push(plugin);
+      console.log(`  [plugin] Loaded: ${plugin.name}`);
+    } catch (err) {
+      console.error(`  [plugin] Failed to load ${modulePath}:`, (err as Error).message);
+    }
+  }
+}
+
+/** Teardown all loaded plugins (call on shutdown). */
+export async function teardownPlugins(): Promise<void> {
+  for (const plugin of loadedPlugins) {
+    try {
+      await plugin.teardown?.();
+    } catch (err) {
+      console.error(`  [plugin] Teardown error (${plugin.name}):`, (err as Error).message);
+    }
+  }
+  loadedPlugins.length = 0;
+}

package/src/coordination/plugin.ts

@@ -0,0 +1,44 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * AWM Plugin contract.
+ *
+ * Plugins extend coordination with custom behavior by subscribing to
+ * events, adding routes, or querying the DB. They are loaded at startup
+ * via AWM_PLUGINS env var (comma-separated module paths).
+ *
+ * Example plugin:
+ *   import type { AWMPlugin } from 'agent-working-memory';
+ *   export default {
+ *     name: 'my-plugin',
+ *     register(ctx) {
+ *       ctx.events.on('assignment.completed', (evt) => {
+ *         console.log(`Task done: ${evt.assignmentId}`);
+ *       });
+ *     },
+ *   } satisfies AWMPlugin;
+ */
+
+import type { FastifyInstance } from 'fastify';
+import type Database from 'better-sqlite3';
+import type { CoordinationEventBus } from './events.js';
+
+/** Context passed to plugin register(). */
+export interface AWMPluginContext {
+  /** Typed event bus — subscribe to coordination events. */
+  events: CoordinationEventBus;
+  /** Raw better-sqlite3 database handle (coordination tables). */
+  db: Database.Database;
+  /** Fastify instance — add custom routes if needed. */
+  fastify: FastifyInstance;
+}
+
+/** Plugin contract. Every AWM plugin must export this shape. */
+export interface AWMPlugin {
+  /** Unique plugin name (for logging and dedup). */
+  name: string;
+  /** Called once at startup with the plugin context. */
+  register(ctx: AWMPluginContext): void | Promise<void>;
+  /** Optional cleanup on shutdown. */
+  teardown?(): void | Promise<void>;
+}