agent-working-memory 0.6.0 → 0.6.1

package/src/coordination/schema.ts

@@ -11,22 +11,21 @@ import type Database from 'better-sqlite3';
 const COORDINATION_TABLES = `
 -- Coordination: agents in the hive
 CREATE TABLE IF NOT EXISTS coord_agents (
-  id           TEXT PRIMARY KEY,
-  name         TEXT NOT NULL,
-  role         TEXT NOT NULL DEFAULT 'worker',
-  status       TEXT NOT NULL DEFAULT 'idle',
-  pid          INTEGER,
-  started_at   TEXT NOT NULL DEFAULT (datetime('now')),
-  last_seen    TEXT NOT NULL DEFAULT (datetime('now')),
-  current_task TEXT,
-  metadata     TEXT,
-  capabilities TEXT,
-  workspace    TEXT
+  id             TEXT PRIMARY KEY,
+  name           TEXT NOT NULL,
+  role           TEXT NOT NULL DEFAULT 'worker',
+  status         TEXT NOT NULL DEFAULT 'idle',
+  pid            INTEGER,
+  started_at     TEXT NOT NULL DEFAULT (datetime('now')),
+  last_seen      TEXT NOT NULL DEFAULT (datetime('now')),
+  current_task   TEXT,
+  metadata       TEXT,
+  capabilities   TEXT,
+  workspace      TEXT,
+  session_token  TEXT
 );
 
--- Prevent duplicate agent registrations for the same name+workspace
-CREATE UNIQUE INDEX IF NOT EXISTS idx_coord_agents_name_workspace
-  ON coord_agents (name, COALESCE(workspace, ''));
+-- unique index on (name, workspace) is created after dedup in initCoordinationTables
 
 -- Coordination: assignments
 CREATE TABLE IF NOT EXISTS coord_assignments (
@@ -43,6 +42,7 @@ CREATE TABLE IF NOT EXISTS coord_assignments (
   result       TEXT,
   commit_sha   TEXT,
   workspace    TEXT,
+  context      TEXT,
   FOREIGN KEY (agent_id) REFERENCES coord_agents(id),
   FOREIGN KEY (blocked_by) REFERENCES coord_assignments(id)
 );
@@ -96,6 +96,32 @@ CREATE TABLE IF NOT EXISTS coord_decisions (
 CREATE INDEX IF NOT EXISTS idx_coord_decisions_assignment
   ON coord_decisions (assignment_id, created_at);
 
+-- Coordination: channel sessions (push-based coordination)
+CREATE TABLE IF NOT EXISTS coord_channel_sessions (
+  agent_id     TEXT PRIMARY KEY REFERENCES coord_agents(id),
+  channel_id   TEXT NOT NULL,
+  connected_at TEXT NOT NULL DEFAULT (datetime('now')),
+  last_push_at TEXT,
+  push_count   INTEGER NOT NULL DEFAULT 0,
+  status       TEXT NOT NULL DEFAULT 'connected'
+);
+
+-- Coordination: named mailbox (persistent message queue per worker name)
+-- Messages survive AWM restarts and worker disconnects.
+-- Delivered on next /next poll, then marked delivered.
+CREATE TABLE IF NOT EXISTS coord_mailbox (
+  id           INTEGER PRIMARY KEY AUTOINCREMENT,
+  worker_name  TEXT NOT NULL,
+  workspace    TEXT,
+  message      TEXT NOT NULL,
+  source       TEXT DEFAULT 'coordinator',
+  created_at   TEXT NOT NULL DEFAULT (datetime('now')),
+  delivered_at TEXT,
+  read_at      TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_coord_mailbox_worker
+  ON coord_mailbox (worker_name, workspace, delivered_at);
+
 -- Coordination: event audit trail
 CREATE TABLE IF NOT EXISTS coord_events (
   id           INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -111,10 +137,37 @@ CREATE TABLE IF NOT EXISTS coord_events (
  * Safe to call multiple times (CREATE IF NOT EXISTS).
  */
 export function initCoordinationTables(db: Database.Database): void {
+  // Create tables (unique index is added separately after dedup)
   db.exec(COORDINATION_TABLES);
 
+  // Deduplicate coord_agents before creating the unique index.
+  // Keep only the most recently seen row for each (name, workspace) pair.
+  try {
+    db.exec(`
+      DELETE FROM coord_agents
+      WHERE rowid NOT IN (
+        SELECT MAX(rowid) FROM coord_agents
+        GROUP BY name, COALESCE(workspace, '')
+      )
+    `);
+  } catch { /* table may not exist yet — that's fine */ }
+
+  // Now create the unique index safely
+  try {
+    db.exec(`
+      CREATE UNIQUE INDEX IF NOT EXISTS idx_coord_agents_name_workspace
+        ON coord_agents (name, COALESCE(workspace, ''));
+    `);
+  } catch {
+    // Index may already exist from a previous run — that's fine
+  }
+
   // Migrations: add columns to existing coord_assignments tables
   try { db.exec(`ALTER TABLE coord_assignments ADD COLUMN commit_sha TEXT`); } catch { /* exists */ }
   try { db.exec(`ALTER TABLE coord_assignments ADD COLUMN priority INTEGER NOT NULL DEFAULT 0`); } catch { /* exists */ }
   try { db.exec(`ALTER TABLE coord_assignments ADD COLUMN blocked_by TEXT`); } catch { /* exists */ }
+  try { db.exec(`ALTER TABLE coord_assignments ADD COLUMN context TEXT`); } catch { /* exists */ }
+
+  // Migration: session token for hijack prevention (added 2026-03-26)
+  try { db.exec(`ALTER TABLE coord_agents ADD COLUMN session_token TEXT`); } catch { /* exists */ }
 }

package/src/coordination/schemas.ts

@@ -9,7 +9,7 @@ import { z } from 'zod';
 
 // ─── Enums ──────────────────────────────────────────────────────
 
-export const agentRoleEnum = z.enum(['worker', 'orchestrator', 'dev-lead']);
+export const agentRoleEnum = z.enum(['worker', 'orchestrator', 'coordinator', 'dev-lead']);
 export const agentStatusEnum = z.enum(['idle', 'working', 'dead']);
 export const assignmentStatusEnum = z.enum(['in_progress', 'completed', 'failed', 'blocked']);
 export const commandEnum = z.enum(['BUILD_FREEZE', 'PAUSE', 'RESUME', 'SHUTDOWN']);
@@ -30,6 +30,7 @@ export const checkinSchema = z.object({
   metadata: z.record(z.string(), z.unknown()).optional(),
   capabilities: z.array(z.string().max(50)).max(20).optional(),
   workspace: z.string().max(50).optional(),
+  channelUrl: z.string().url().max(200).optional(),
 });
 
 export const checkoutSchema = z.object({
@@ -40,11 +41,13 @@ export const checkoutSchema = z.object({
 
 export const assignCreateSchema = z.object({
   agentId: z.string().uuid().optional(),
+  worker_name: z.string().min(1).max(50).optional(),
   task: z.string().min(1).max(1000),
   description: z.string().max(5000).optional(),
   workspace: z.string().max(50).optional(),
   priority: z.number().int().min(0).max(10).default(0),
   blocked_by: z.string().uuid().optional(),
+  context: z.string().max(10000).optional(),
 });
 
 export const assignmentQuerySchema = z.object({
@@ -58,12 +61,27 @@ export const nextSchema = z.object({
   workspace: z.string().max(50).optional(),
   role: agentRoleEnum.default('worker'),
   capabilities: z.array(z.string().max(50)).max(20).optional(),
+  channelUrl: z.string().url().max(200).optional(),
 });
 
 export const assignmentClaimSchema = z.object({
   agentId: z.string().uuid(),
 });
 
+export const assignmentsListSchema = z.object({
+  status: z.enum(['pending', 'assigned', 'in_progress', 'completed', 'failed', 'blocked']).optional(),
+  workspace: z.string().max(50).optional(),
+  agent_id: z.string().uuid().optional(),
+  limit: z.coerce.number().int().min(1).max(100).default(20),
+  offset: z.coerce.number().int().min(0).default(0),
+});
+
+export const reassignSchema = z.object({
+  assignmentId: z.string().uuid(),
+  targetAgentId: z.string().uuid().optional(),
+  target_worker_name: z.string().min(1).max(50).optional(),
+});
+
 export const assignmentUpdateSchema = z.object({
   status: assignmentStatusEnum,
   result: z.string().max(10000).optional(),
@@ -118,6 +136,11 @@ export const findingsQuerySchema = z.object({
   limit: z.coerce.number().int().min(1).max(200).default(50),
 });
 
+export const findingUpdateSchema = z.object({
+  status: findingStatusEnum.optional(),
+  suggestion: z.string().max(5000).optional(),
+});
+
 // ─── Param Schemas ─────────────────────────────────────────────
 
 export const assignmentIdParamSchema = z.object({ id: z.string().uuid() });
@@ -134,12 +157,23 @@ export const pulseSchema = z.object({
 export const decisionsQuerySchema = z.object({
   since_id: z.coerce.number().int().min(0).default(0),
   assignment_id: z.string().max(100).optional(),
+  workspace: z.string().max(50).optional(),
   limit: z.coerce.number().int().min(1).max(200).default(20),
 });
 
+export const decisionCreateSchema = z.object({
+  agentId: z.string().uuid(),
+  assignment_id: z.string().max(100).optional(),
+  tags: z.string().max(500).optional(),
+  summary: z.string().min(1).max(5000),
+});
+
 // ─── Status / Events ────────────────────────────────────────────
 
 export const eventsQuerySchema = z.object({
+  since_id: z.coerce.number().int().min(0).default(0),
+  agent_id: z.string().uuid().optional(),
+  event_type: z.string().max(50).optional(),
   limit: z.coerce.number().int().min(1).max(200).default(50),
 });
 
@@ -153,3 +187,53 @@ export const workersQuerySchema = z.object({
   status: agentStatusEnum.optional(),
   workspace: z.string().max(50).optional(),
 });
+
+// ─── Agent Params ─────────────────────────────────────────
+
+export const agentIdParamSchema = z.object({ id: z.string().uuid() });
+
+// ─── Timeline ─────────────────────────────────────────────
+
+export const timelineQuerySchema = z.object({
+  limit: z.coerce.number().int().min(1).max(200).default(50),
+  since: z.string().max(30).optional(),
+});
+
+// ─── Channel Sessions ──────────────────────────────────────────
+
+export const channelRegisterSchema = z.object({
+  agentId: z.string().uuid(),
+  channelId: z.string().min(1).max(200),
+});
+
+export const channelDeregisterSchema = z.object({
+  agentId: z.string().uuid(),
+});
+
+export const channelPushSchema = z.object({
+  agentId: z.string().uuid(),
+  message: z.string().min(1).max(10000),
+});
+
+// ─── Stats ─────────────────────────────────────────────────────
+
+export const statsResponseSchema = z.object({
+  workers: z.object({
+    total: z.number().int(),
+    alive: z.number().int(),
+    idle: z.number().int(),
+    working: z.number().int(),
+  }),
+  tasks: z.object({
+    total_assigned: z.number().int(),
+    completed: z.number().int(),
+    failed: z.number().int(),
+    pending: z.number().int(),
+    avg_completion_seconds: z.number().nullable(),
+  }),
+  decisions: z.object({
+    total: z.number().int(),
+    last_hour: z.number().int(),
+  }),
+  uptime_seconds: z.number(),
+});

package/src/coordination/stale.ts

@@ -80,6 +80,9 @@ export function purgeDeadAgents(db: Database.Database, maxAgeHours = 24): number
 
 /** Clean slate on startup: mark all live agents dead, release locks, clear commands. */
 export function cleanSlate(db: Database.Database): void {
+  // Always clear commands, even if no alive agents remain
+  db.prepare(`UPDATE coord_commands SET cleared_at = datetime('now') WHERE cleared_at IS NULL`).run();
+
   const alive = db.prepare(
     `SELECT id, name FROM coord_agents WHERE status != 'dead'`
   ).all() as Array<{ id: string; name: string }>;
@@ -91,7 +94,5 @@ export function cleanSlate(db: Database.Database): void {
     db.prepare(`DELETE FROM coord_locks WHERE agent_id = ?`).run(agent.id);
   }
 
-  db.prepare(`UPDATE coord_commands SET cleared_at = datetime('now') WHERE cleared_at IS NULL`).run();
-
   console.log(`  Coordination clean slate: marked ${alive.length} agent(s) from previous session as dead`);
 }

package/src/coordination/types.ts

@@ -0,0 +1,311 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * TypeScript interfaces for coordination API responses.
+ * These types support typed API clients consuming the coordination HTTP endpoints.
+ */
+
+// ─── Shared Primitives ─────────────────────────────────────────
+
+export type AgentRole = 'worker' | 'orchestrator' | 'coordinator' | 'dev-lead';
+export type AgentStatus = 'idle' | 'working' | 'dead';
+export type AssignmentStatus = 'pending' | 'assigned' | 'in_progress' | 'completed' | 'failed' | 'blocked';
+export type CommandType = 'BUILD_FREEZE' | 'PAUSE' | 'RESUME' | 'SHUTDOWN';
+export type FindingSeverity = 'critical' | 'error' | 'warn' | 'info';
+export type FindingStatus = 'open' | 'resolved';
+
+// ─── Agent ─────────────────────────────────────────────────────
+
+export interface CheckinResponse {
+  agentId: string;
+  action: 'registered' | 'heartbeat' | 'reconnected';
+  status: string;
+  workspace: string | null;
+}
+
+export interface AgentDetail {
+  id: string;
+  name: string;
+  role: AgentRole;
+  status: AgentStatus;
+  current_task: string | null;
+  pid: number | null;
+  capabilities: string | null;
+  workspace: string | null;
+  metadata: string | null;
+  last_seen: string;
+  started_at: string | null;
+  seconds_since_seen: number;
+}
+
+export interface AgentResponse {
+  agent: AgentDetail;
+  assignment: AssignmentSummary | null;
+  locks: LockEntry[];
+}
+
+// ─── Assignments ───────────────────────────────────────────────
+
+export interface Assignment {
+  id: string;
+  agent_id: string | null;
+  task: string;
+  description: string | null;
+  status: AssignmentStatus;
+  priority: number;
+  blocked_by: string | null;
+  created_at: string;
+  started_at: string | null;
+  completed_at: string | null;
+  result: string | null;
+  commit_sha: string | null;
+  workspace: string | null;
+  context: string | null;
+}
+
+export interface AssignmentSummary {
+  id: string;
+  task: string;
+  status: AssignmentStatus;
+  priority: number;
+  created_at: string;
+}
+
+export interface AssignmentWithAgent extends Assignment {
+  agent_name: string | null;
+  is_blocked: 0 | 1;
+}
+
+export interface AssignCreateResponse {
+  assignmentId: string;
+  status: 'assigned' | 'pending';
+}
+
+export interface AssignmentsListResponse {
+  assignments: AssignmentWithAgent[];
+  total: number;
+}
+
+// ─── Next ──────────────────────────────────────────────────────
+
+export interface CommandEntry {
+  id: number;
+  command: CommandType;
+  reason: string | null;
+  issued_by: string | null;
+  issued_at: string;
+  workspace: string | null;
+}
+
+export interface NextResponse {
+  agentId: string;
+  status: string;
+  assignment: Assignment | null;
+  commands: CommandEntry[];
+}
+
+// ─── Locks ─────────────────────────────────────────────────────
+
+export interface LockEntry {
+  file_path: string;
+  locked_at: string;
+  reason: string | null;
+}
+
+export interface LockWithAgent extends LockEntry {
+  agent_id: string;
+  agent_name: string;
+}
+
+export interface LocksResponse {
+  locks: LockWithAgent[];
+}
+
+// ─── Commands ──────────────────────────────────────────────────
+
+export interface CommandResponse {
+  active: boolean;
+  command?: CommandType;
+  reason?: string | null;
+  issued_at?: string;
+  commands: CommandEntry[];
+}
+
+// ─── Workers ───────────────────────────────────────────────────
+
+export interface WorkerEntry {
+  id: string;
+  name: string;
+  role: AgentRole;
+  status: AgentStatus;
+  currentTask: string | null;
+  capabilities: string[];
+  workspace: string | null;
+  lastSeen: string;
+  secondsSinceSeen: number;
+  alive: boolean;
+}
+
+export interface WorkersResponse {
+  count: number;
+  idle: number;
+  working: number;
+  workers: WorkerEntry[];
+}
+
+// ─── Events ────────────────────────────────────────────────────
+
+export interface EventEntry {
+  id: number;
+  agent_id: string | null;
+  agent_name: string | null;
+  event_type: string;
+  detail: string | null;
+  created_at: string;
+}
+
+export interface EventsResponse {
+  events: EventEntry[];
+  last_id: number;
+}
+
+// ─── Decisions ─────────────────────────────────────────────────
+
+export interface DecisionEntry {
+  id: number;
+  author_id: string;
+  author_name: string;
+  assignment_id: string | null;
+  tags: string | null;
+  summary: string;
+  created_at: string;
+}
+
+export interface DecisionsResponse {
+  decisions: DecisionEntry[];
+}
+
+// ─── Findings ──────────────────────────────────────────────────
+
+export interface FindingEntry {
+  id: number;
+  category: string;
+  severity: FindingSeverity;
+  file_path: string | null;
+  line_number: number | null;
+  description: string;
+  suggestion: string | null;
+  status: FindingStatus;
+  created_at: string;
+  agent_name: string;
+}
+
+export interface FindingSeverityCount {
+  severity: FindingSeverity;
+  count: number;
+}
+
+export interface FindingsResponse {
+  findings: FindingEntry[];
+  stats: FindingSeverityCount[];
+}
+
+// ─── Channel Sessions ─────────────────────────────────────────
+
+export interface ChannelSession {
+  agent_id: string;
+  agent_name: string;
+  channel_id: string;
+  connected_at: string;
+  last_push_at: string | null;
+  push_count: number;
+  status: string;
+}
+
+export interface ChannelSessionsResponse {
+  sessions: ChannelSession[];
+}
+
+// ─── Status ────────────────────────────────────────────────────
+
+export interface StatusResponse {
+  agents: Array<{
+    id: string;
+    name: string;
+    role: AgentRole;
+    status: AgentStatus;
+    current_task: string | null;
+    last_seen: string;
+    seconds_since_seen: number;
+  }>;
+  assignments: Array<{
+    id: string;
+    task: string;
+    description: string | null;
+    status: AssignmentStatus;
+    agent_id: string | null;
+    agent_name: string | null;
+    created_at: string;
+    started_at: string | null;
+    completed_at: string | null;
+  }>;
+  locks: LockWithAgent[];
+  stats: {
+    alive_agents: number;
+    busy_agents: number;
+    pending_tasks: number;
+    active_tasks: number;
+    active_locks: number;
+    open_findings: number;
+    urgent_findings: number;
+  };
+  recentFindings: Array<{
+    id: number;
+    category: string;
+    severity: FindingSeverity;
+    file_path: string | null;
+    description: string;
+    agent_name: string;
+    created_at: string;
+  }>;
+}
+
+// ─── Stats ─────────────────────────────────────────────────────
+
+export interface StatsResponse {
+  workers: {
+    total: number;
+    alive: number;
+    idle: number;
+    working: number;
+  };
+  tasks: {
+    total_assigned: number;
+    completed: number;
+    failed: number;
+    pending: number;
+    avg_completion_seconds: number | null;
+  };
+  decisions: {
+    total: number;
+    last_hour: number;
+  };
+  uptime_seconds: number;
+}
+
+// ─── Stale ─────────────────────────────────────────────────────
+
+export interface StaleAgent {
+  id: string;
+  name: string;
+  role: string;
+  status: string;
+  last_seen: string;
+  seconds_since_seen: number;
+}
+
+export interface StaleResponse {
+  stale: StaleAgent[];
+  threshold_seconds: number;
+  cleaned?: number;
+}

package/src/coordination/write-mutex.ts

@@ -0,0 +1,69 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Promise-based write mutex for SQLite coordination routes.
+ *
+ * SQLite only allows one writer at a time. Under burst from 5+ concurrent
+ * workers, multiple async handlers can race for the write lock, causing
+ * SQLITE_BUSY errors. This mutex serializes write operations (POST, PATCH,
+ * PUT, DELETE) through a single-concurrency queue while keeping reads (GET)
+ * unguarded for full parallelism.
+ *
+ * Usage: Register as a Fastify preHandler hook in the coordination module.
+ */
+
+/**
+ * Creates a simple single-concurrency mutex.
+ * acquire() returns a release function — call it when done.
+ */
+export function createWriteMutex(): {
+  acquire(): Promise<() => void>;
+  pending: () => number;
+} {
+  let queue: Array<(release: () => void) => void> = [];
+  let locked = false;
+
+  function release(): void {
+    const next = queue.shift();
+    if (next) {
+      // Hand lock directly to next waiter (no unlock/relock gap)
+      next(release);
+    } else {
+      locked = false;
+    }
+  }
+
+  function acquire(): Promise<() => void> {
+    if (!locked) {
+      locked = true;
+      return Promise.resolve(release);
+    }
+    return new Promise<() => void>((resolve) => {
+      queue.push(resolve);
+    });
+  }
+
+  return {
+    acquire,
+    pending: () => queue.length,
+  };
+}
+
+/** HTTP methods that perform writes and need serialization. */
+const WRITE_METHODS = new Set(['POST', 'PATCH', 'PUT', 'DELETE']);
+
+/** Routes that are safe to skip the mutex (read-only despite POST method). */
+const READ_ONLY_ROUTES = new Set(['/next']);
+
+/**
+ * Check if a request needs write serialization.
+ * GET/HEAD/OPTIONS are always reads. POST /next is a read (checkin is idempotent upsert
+ * but low-contention). All other write methods go through the mutex.
+ */
+export function needsWriteLock(method: string, url: string): boolean {
+  if (!WRITE_METHODS.has(method)) return false;
+  // Strip query string for route matching
+  const path = url.split('?')[0];
+  if (READ_ONLY_ROUTES.has(path)) return false;
+  return true;
+}

package/src/core/embeddings.ts

@@ -53,6 +53,11 @@ export async function embed(text: string): Promise<number[]> {
   return Array.from(result.data as Float32Array).slice(0, DIMENSIONS);
 }
 
+/** Get the current embedding model ID (for version tracking in stored embeddings) */
+export function getModelId(): string {
+  return MODEL_ID;
+}
+
 /**
  * Generate embeddings for multiple texts in a batch.
  * More efficient than calling embed() in a loop.