agent-working-memory 0.7.16 → 0.8.5

package/src/coordination/peer-decisions.ts

@@ -1,105 +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')}`;
-}
+// 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

@@ -1,60 +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;
-}
+// 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

@@ -1,44 +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>;
-}
+// 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>;
+}

package/src/coordination/routes.ts

@@ -21,7 +21,9 @@ import {
   agentIdParamSchema, timelineQuerySchema,
   channelRegisterSchema, channelDeregisterSchema, channelPushSchema,
 } from './schemas.js';
-import { detectStale, cleanupStale } from './stale.js';
+import { detectStale, cleanupStale, retryOrFailAssignment } from './stale.js';
+import { classifyFailure, FailureMode } from './failure-modes.js';
+import { recordSuccess, recordFailure as circuitRecordFailure, isAvailable } from './circuit-breaker.js';
 
 /** Pretty timestamp for coordination logs. */
 function ts(): string {
@@ -444,6 +446,11 @@ export function registerCoordinationRoutes(app: FastifyInstance, db: Database.Da
             `SELECT * FROM coord_assignments WHERE status = 'pending' AND agent_id IS NULL ${blockedFilter} ORDER BY priority DESC, created_at ASC LIMIT 1`
           ).get() as { id: string } | undefined);
 
+      // Circuit breaker: refuse assignment if worker is in open state
+      if (pending && !isAvailable(db, agentId)) {
+        return reply.code(423).send({ status: 'idle', assignment: null, circuit_open: true, reason: 'circuit_open' });
+      }
+
       if (pending) {
         const claimed = db.prepare(
           `UPDATE coord_assignments SET agent_id = ?, status = 'assigned', started_at = datetime('now') WHERE id = ? AND status = 'pending'`
@@ -724,6 +731,11 @@ export function registerCoordinationRoutes(app: FastifyInstance, db: Database.Da
           `SELECT * FROM coord_assignments WHERE status = 'pending' AND agent_id IS NULL ${blockedFilter} ORDER BY priority DESC, created_at ASC LIMIT 1`
         ).get() as { id: string } | undefined);
 
+    // Circuit breaker: refuse assignment if worker is in open state
+    if (pending && !isAvailable(db, agentId)) {
+      return reply.code(423).send({ assignment: null, circuit_open: true, reason: 'circuit_open' });
+    }
+
     if (pending) {
       const claimed = db.prepare(
         `UPDATE coord_assignments SET agent_id = ?, status = 'assigned', started_at = datetime('now') WHERE id = ? AND status = 'pending'`
@@ -847,6 +859,12 @@ export function registerCoordinationRoutes(app: FastifyInstance, db: Database.Da
       coordLog(`${assignInfo?.agent_name ?? 'unknown'} ${status}: ${assignInfo?.task?.slice(0, 80) ?? id}`);
     }
 
+    // Circuit breaker: track success/failure per worker
+    if (assignInfo?.agent_id) {
+      if (status === 'completed') recordSuccess(db, assignInfo.agent_id);
+      else if (status === 'failed') circuitRecordFailure(db, assignInfo.agent_id);
+    }
+
     // Emit events
     eventBus?.emit('assignment.updated', { assignmentId: id, agentId: assignInfo?.agent_id ?? null, status, result });
     if (status === 'completed') {
@@ -1011,6 +1029,38 @@ export function registerCoordinationRoutes(app: FastifyInstance, db: Database.Da
     return reply.send({ ok: true });
   });
 
+  /** POST /assignment/:id/fail — Worker voluntarily fails an assignment with retry logic.
+   *  Body: { result: string, mode?: FailureMode }
+   *  Returns: { outcome: 'retried' | 'failed', attempt_count, last_failure_mode }
+   */
+  app.post('/assignment/:id/fail', async (req, reply) => {
+    const { id } = assignmentIdParamSchema.parse(req.params);
+    const body = req.body as { result?: string; mode?: string } | undefined;
+    const result = body?.result ?? 'worker-initiated failure';
+    const mode = body?.mode as FailureMode | undefined;
+
+    const row = db.prepare(
+      `SELECT id, agent_id, status FROM coord_assignments WHERE id = ?`
+    ).get(id) as { id: string; agent_id: string | null; status: string } | undefined;
+
+    if (!row) return reply.code(404).send({ error: 'assignment not found' });
+    if (['completed', 'failed'].includes(row.status)) {
+      return reply.code(400).send({ error: `cannot fail a ${row.status} assignment` });
+    }
+
+    const agentId = row.agent_id ?? 'unknown';
+    const outcome = retryOrFailAssignment(db, id, agentId, result, mode);
+
+    // Circuit breaker: record failure on voluntary fail
+    if (agentId !== 'unknown') circuitRecordFailure(db, agentId);
+
+    const updated = db.prepare(
+      `SELECT attempt_count, last_failure_mode FROM coord_assignments WHERE id = ?`
+    ).get(id) as { attempt_count: number; last_failure_mode: string | null } | undefined;
+
+    return reply.send({ ok: true, outcome, attempt_count: updated?.attempt_count ?? 0, last_failure_mode: updated?.last_failure_mode ?? null });
+  });
+
   app.put('/assignment/:id', async (req, reply) => {
     const { id } = assignmentIdParamSchema.parse(req.params);
     const parsed = assignmentUpdateSchema.safeParse(req.body);
@@ -1961,6 +2011,11 @@ export function registerCoordinationRoutes(app: FastifyInstance, db: Database.Da
     const agent = db.prepare(`SELECT name, workspace FROM coord_agents WHERE id = ?`).get(agentId) as { name: string; workspace: string | null } | undefined;
     if (!agent) return reply.status(404).send({ error: 'Agent not found' });
 
+    // Circuit breaker: refuse push to open-circuit workers
+    if (!isAvailable(db, agentId)) {
+      return reply.status(423).send({ error: 'circuit_open', reason: 'Worker circuit is open — too many consecutive failures. Try again after 30s or after a successful assignment.' });
+    }
+
     // Try live channel delivery first
     const session = db.prepare(
       `SELECT agent_id, channel_id FROM coord_channel_sessions WHERE agent_id = ? AND status = 'connected'`

package/src/coordination/schema.ts

@@ -130,6 +130,15 @@ CREATE TABLE IF NOT EXISTS coord_events (
   detail       TEXT,
   created_at   TEXT NOT NULL DEFAULT (datetime('now'))
 );
+
+-- Coordination: per-worker circuit breaker state (AWM 0.8.1)
+CREATE TABLE IF NOT EXISTS coord_circuit_state (
+  agent_id             TEXT PRIMARY KEY REFERENCES coord_agents(id),
+  state                TEXT NOT NULL DEFAULT 'closed',
+  consecutive_failures INTEGER NOT NULL DEFAULT 0,
+  opened_at            TEXT NULL,
+  last_transition_at   TEXT NOT NULL DEFAULT (datetime('now'))
+);
 `;
 
 /**
@@ -170,4 +179,8 @@ export function initCoordinationTables(db: Database.Database): void {
 
   // Migration: session token for hijack prevention (added 2026-03-26)
   try { db.exec(`ALTER TABLE coord_agents ADD COLUMN session_token TEXT`); } catch { /* exists */ }
+
+  // Migrations: control-layer columns for retry tracking (AWM 0.8.1)
+  try { db.exec(`ALTER TABLE coord_assignments ADD COLUMN attempt_count INTEGER NOT NULL DEFAULT 0`); } catch { /* exists */ }
+  try { db.exec(`ALTER TABLE coord_assignments ADD COLUMN last_failure_mode TEXT`); } catch { /* exists */ }
 }