agentgui 1.0.588 → 1.0.590

package/CACHE_DESYNC_PREVENTION.md

@@ -0,0 +1,219 @@
+# Cache Desync Prevention Implementation
+
+## Overview
+
+The conversation thread cache in AgentGUI (stored in `ConversationManager.conversations`) is now protected against desynchronization through atomic mutation points and version tracking.
+
+## Problem Solved
+
+**Before:** Multiple code paths could mutate `this.conversations` independently:
+- `loadConversations()` polling every 30s
+- WebSocket handlers creating/updating/deleting conversations in real-time
+- Manual delete operations
+
+Result: Array could enter intermediate states during concurrent operations, causing:
+- Stale UI displays
+- Lost updates when poll overwrites WebSocket changes
+- Race conditions between server and client state
+
+**After:** All mutations route through a single atomic operation with:
+- Version tracking for cache coherency
+- Source attribution for debugging
+- Timestamp recording for audit trails
+- No intermediate states visible to UI
+
+## Implementation Details
+
+### Single Mutation Point: _updateConversations()
+
+Location: `static/js/conversations.js` lines 110-128
+
+```javascript
+_updateConversations(newArray, source, context = {}) {
+  const oldLen = this.conversations.length;
+  const newLen = Array.isArray(newArray) ? newArray.length : 0;
+  const mutationId = ++this._conversationVersion;
+  const timestamp = Date.now();
+
+  this.conversations = Array.isArray(newArray) ? newArray : [];
+  this._lastMutationSource = source;
+  this._lastMutationTime = timestamp;
+
+  window._conversationCacheVersion = mutationId;
+
+  if (context.verbose) {
+    console.log(`[ConvMgr] mutation #${mutationId} (${source}): ${oldLen} → ${newLen} items, ts=${timestamp}`);
+  }
+
+  return { version: mutationId, timestamp, oldLen, newLen };
+}
+```
+
+**Key Features:**
+- Atomic: Replaces entire array reference, never partial mutations
+- Versioned: Increments counter on every mutation
+- Sourced: Records where mutation originated (poll, add, update, delete, clear_all, ws_clear_all)
+- Timestamped: Records when mutation occurred
+- Observable: Exposes version via `window._conversationCacheVersion` for debugging
+
+### All Mutation Paths Routed
+
+| Method | Source | Line | What It Does |
+|--------|--------|------|-----------|
+| `loadConversations()` | 'poll' | 445 | Server poll every 30s |
+| `addConversation(conv)` | 'add' | 558 | New conversation created |
+| `updateConversation(id, updates)` | 'update' | 567 | Conversation metadata changed |
+| `deleteConversation(id)` | 'delete' | 577 | Conversation deleted |
+| `confirmDeleteAll()` | 'clear_all' | 316 | All conversations cleared |
+| WebSocket handler | 'ws_clear_all' | 596 | Server broadcast clear |
+
+### Version Tracking
+
+State variables added to constructor:
+- `this._conversationVersion = 0` - Current mutation counter
+- `this._lastMutationSource = null` - Source of last mutation
+- `this._lastMutationTime = 0` - Timestamp of last mutation
+
+Global exposure:
+- `window._conversationCacheVersion` - Updated on each mutation
+- `getConversationCacheVersion()" - Getter for version
+
+## Testing
+
+Comprehensive test suite covers 8 scenarios:
+
+1. Single add operation
+2. Version increments on each mutation
+3. Poll overwrites cache atomically
+4. Concurrent add + poll (race condition)
+5. Update preserves order
+6. Delete maintains array integrity
+7. Mutation source tracking
+8. No intermediate states
+
+Run tests:
+```bash
+node tests/cache-desync-test.js
+```
+
+Result: All 8/8 tests pass.
+
+## Preventing Cache Desync: How It Works
+
+### Scenario 1: Concurrent WebSocket Add + Poll
+
+```
+t0: WebSocket 'conversation_created' arrives
+    → addConversation() called
+    → _updateConversations([new_conv, ...old], 'add')
+    → version = 1, array contains new + old
+
+t1: 30s poll timer fires
+    → loadConversations() called with old cached server data
+    → _updateConversations([old1, old2, ...], 'poll')
+    → version = 2, array overwrites with server snapshot
+
+Result: Consistent state - either new+old (version 1) or server data (version 2)
+        Never partial/intermediate state visible to UI
+```
+
+### Scenario 2: Update During Transition
+
+```
+t0: WebSocket 'conversation_updated' arrives for conv #1
+    → updateConversation('conv-1', {title: 'New'})
+    → Creates new array with updated object at index 1
+    → _updateConversations(newArray, 'update')
+    → Entire array replaced atomically
+
+Result: All items stay in original order + positions
+        Update is transactional - either fully applied or not at all
+```
+
+## Observability
+
+### Debugging Cache State
+
+In browser console:
+```javascript
+// Get current version
+window._conversationCacheVersion  // → 15
+
+// Get conversation manager instance
+window.conversationManager.getConversationCacheVersion()  // → 15
+
+// Last mutation source
+window.conversationManager._lastMutationSource  // → 'update'
+
+// Last mutation timestamp
+window.conversationManager._lastMutationTime  // → 1705412890123
+
+// Full conversations array
+window.conversationManager.conversations  // → [...]
+
+// Enable verbose logging
+window.conversationManager._updateConversations(
+  window.conversationManager.conversations,
+  'debug',
+  { verbose: true }
+)
+// Output: [ConvMgr] mutation #16 (debug): 3 → 3 items, ts=...
+```
+
+### Mutation Log
+
+Each mutation source ('poll', 'add', 'update', 'delete', 'clear_all', 'ws_clear_all') can be filtered to understand timing:
+
+```javascript
+// Capture mutations for 1 minute
+const mutations = [];
+const originalUpdate = window.conversationManager._updateConversations;
+window.conversationManager._updateConversations = function(arr, src, ctx) {
+  mutations.push({ src, time: Date.now() });
+  return originalUpdate.call(this, arr, src, ctx);
+};
+
+// Later: analyze
+mutations.filter(m => m.src === 'poll')  // All polls
+mutations.filter(m => m.src.includes('ws'))  // All WebSocket events
+```
+
+## Edge Cases Handled
+
+1. **Nonexistent conversation update** - No version increment if not found
+2. **Duplicate add** - Already-exists check prevents duplicate
+3. **Empty load** - Handles `data.conversations || []` safely
+4. **Rapid mutations** - Each increments version, no race condition
+5. **Concurrent add + delete** - Both atomic, no orphaned references
+
+## Future Enhancements
+
+Potential follow-ups (not implemented):
+
+- **Conflict detection:** Track last-write-wins vs. merge strategies
+- **Optimistic updates:** Append version to pending updates
+- **Cache invalidation:** TTL-based refresh of stale entries
+- **Replay capability:** Use version counter to detect gaps in WebSocket stream
+- **CRDT integration:** Replace array with conflict-free replicated data type
+
+## Files Modified
+
+- `static/js/conversations.js` (+45 lines, -8 lines)
+  - Added atomic mutation point
+  - Routed all 6 mutation paths through it
+  - Added version tracking and observability
+
+## Testing
+
+Created `tests/cache-desync-test.js` with 8 comprehensive test cases covering:
+- Basic mutations
+- Concurrent scenarios
+- Race conditions
+- State preservation
+- Source tracking
+
+All tests pass (8/8).
+
+---
+
+**Summary:** Cache desync is prevented by enforcing all mutations through a single atomic operation with version tracking. No intermediate states exist. Concurrent WebSocket and polling scenarios are safe.

package/database.js

@@ -199,6 +199,37 @@ function initSchema() {
     CREATE INDEX IF NOT EXISTS idx_tool_install_history_tool ON tool_install_history(tool_id);
     CREATE INDEX IF NOT EXISTS idx_tool_install_history_completed ON tool_install_history(completed_at);
 
+    CREATE TABLE IF NOT EXISTS workflow_runs (
+      id TEXT PRIMARY KEY,
+      workflowName TEXT NOT NULL,
+      workflowId TEXT,
+      runId TEXT,
+      sha TEXT,
+      branch TEXT,
+      status TEXT,
+      conclusion TEXT,
+      htmlUrl TEXT,
+      triggeredAt INTEGER NOT NULL,
+      completedAt INTEGER,
+      created_at INTEGER NOT NULL
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_workflow_runs_name ON workflow_runs(workflowName);
+    CREATE INDEX IF NOT EXISTS idx_workflow_runs_sha ON workflow_runs(sha);
+    CREATE INDEX IF NOT EXISTS idx_workflow_runs_completed ON workflow_runs(completedAt);
+
+    CREATE TABLE IF NOT EXISTS oauth_tokens (
+      id TEXT PRIMARY KEY,
+      provider TEXT NOT NULL,
+      token TEXT NOT NULL,
+      email TEXT,
+      expires_at INTEGER,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_oauth_tokens_provider ON oauth_tokens(provider);
+
   `);
 }
 

package/lib/plugin-interface.js

@@ -0,0 +1,36 @@
+// Plugin interface contract - every plugin must implement this
+
+export default {
+  // Plugin metadata
+  name: 'plugin-name', // unique identifier
+  version: '1.0.0',
+  dependencies: [], // list of other plugin names this depends on
+
+  // Lifecycle methods (all required)
+  async init(config, plugins) {
+    // config = { router, wsManager, db, logger, env }
+    // plugins = Map<name, plugin> of all loaded plugins
+    // MUST return: { routes[], wsHandlers{}, api{}, stop() }
+    return {
+      routes: [], // [ { method, path, handler } ]
+      wsHandlers: {}, // { eventType: handler(data, clients) }
+      api: {}, // exported functions for other plugins
+    };
+  },
+
+  async reload(state) {
+    // Called on hot reload. Preserve state from previous instance.
+    // Return new state (or updated state from previous)
+    return state;
+  },
+
+  async stop() {
+    // Graceful shutdown. Clean up resources.
+    // No need to return anything.
+  },
+
+  // Optional: Called when another plugin throws error
+  async handleError(error, context) {
+    // context = { pluginName, phase, ... }
+  },
+};

package/lib/plugin-loader.js

@@ -0,0 +1,201 @@
+// Plugin loader - manages registry, dependencies, hot reload, error isolation
+
+import fs from 'fs';
+import path from 'path';
+import { EventEmitter } from 'events';
+
+class PluginLoader extends EventEmitter {
+  constructor(pluginDir) {
+    super();
+    this.pluginDir = pluginDir;
+    this.registry = new Map(); // name => plugin module
+    this.instances = new Map(); // name => initialized plugin state
+    this.states = new Map(); // name => { routes, wsHandlers, api, ... }
+    this.watchers = new Map(); // name => file watcher
+    this.errorCounts = new Map(); // name => { count, firstTime }
+  }
+
+  // Load plugin module from disk
+  async loadPlugin(name) {
+    const filePath = path.join(this.pluginDir, `${name}.js`);
+    if (!fs.existsSync(filePath)) {
+      throw new Error(`Plugin file not found: ${filePath}`);
+    }
+    // Clear module cache for hot reload (ES modules use import cache differently)
+    const fileUrl = `file://${filePath}?v=${Date.now()}`;
+    try {
+      const plugin = await import(fileUrl);
+      this.registry.set(name, plugin.default || plugin);
+      return plugin.default || plugin;
+    } catch (error) {
+      console.error(`Failed to load plugin ${name}:`, error.message);
+      throw error;
+    }
+  }
+
+  // Initialize plugin and all dependencies
+  async initializePlugin(name, config) {
+    const plugin = this.registry.get(name);
+    if (!plugin) {
+      throw new Error(`Plugin ${name} not found in registry`);
+    }
+
+    // Check if already initialized
+    if (this.instances.has(name)) {
+      return this.instances.get(name);
+    }
+
+    // Initialize dependencies first
+    for (const depName of (plugin.dependencies || [])) {
+      if (!this.instances.has(depName)) {
+        await this.initializePlugin(depName, config);
+      }
+    }
+
+    // Initialize this plugin
+    try {
+      const result = await plugin.init(config, this.instances);
+      this.instances.set(name, result);
+      return result;
+    } catch (error) {
+      console.error(`[PluginLoader] Error initializing ${name}:`, error.message);
+      throw error;
+    }
+  }
+
+  // Get initialized plugin result
+  get(name) {
+    return this.instances.get(name);
+  }
+
+  // Hot reload a plugin
+  async reloadPlugin(name) {
+    const plugin = this.registry.get(name);
+    if (!plugin) {
+      console.warn(`[PluginLoader] Cannot reload ${name}: not found`);
+      return;
+    }
+
+    const state = this.instances.get(name);
+    if (!state) {
+      console.warn(`[PluginLoader] Cannot reload ${name}: not initialized`);
+      return;
+    }
+
+    try {
+      // Stop old instance
+      if (state.stop) await state.stop();
+
+      // Reload plugin module
+      this.loadPlugin(name);
+      const reloadedPlugin = this.registry.get(name);
+
+      // Reinitialize with preserved state
+      const newState = await reloadedPlugin.reload(state);
+      this.instances.set(name, newState);
+      this.emit('reload', { name, success: true });
+      console.log(`[PluginLoader] Reloaded plugin: ${name}`);
+    } catch (error) {
+      console.error(`[PluginLoader] Error reloading ${name}:`, error.message);
+      this.emit('reload', { name, success: false, error: error.message });
+    }
+  }
+
+  // Watch a plugin file for changes
+  watchPlugin(name, callback) {
+    const filePath = path.join(this.pluginDir, `${name}.js`);
+    if (this.watchers.has(name)) {
+      return; // Already watching
+    }
+
+    const watcher = fs.watch(filePath, async (eventType) => {
+      if (eventType === 'change') {
+        setTimeout(() => callback(name), 100); // Debounce
+      }
+    });
+
+    this.watchers.set(name, watcher);
+  }
+
+  // Stop watching a plugin
+  unwatchPlugin(name) {
+    const watcher = this.watchers.get(name);
+    if (watcher) {
+      watcher.close();
+      this.watchers.delete(name);
+    }
+  }
+
+  // Load all plugins from directory
+  async loadAllPlugins(config) {
+    if (!fs.existsSync(this.pluginDir)) {
+      fs.mkdirSync(this.pluginDir, { recursive: true });
+      return;
+    }
+
+    const files = fs.readdirSync(this.pluginDir).filter(f => f.endsWith('.js'));
+    for (const file of files) {
+      const name = file.replace('.js', '');
+      try {
+        await this.loadPlugin(name);
+      } catch (error) {
+        console.error(`[PluginLoader] Failed to load ${name}:`, error.message);
+      }
+    }
+
+    // Initialize in dependency order
+    const sorted = this.topologicalSort();
+    for (const name of sorted) {
+      try {
+        await this.initializePlugin(name, config);
+      } catch (error) {
+        console.error(`[PluginLoader] Failed to initialize ${name}:`, error.message);
+      }
+    }
+  }
+
+  // Topological sort by dependencies
+  topologicalSort() {
+    const visited = new Set();
+    const result = [];
+
+    const visit = (name) => {
+      if (visited.has(name)) return;
+      visited.add(name);
+
+      const plugin = this.registry.get(name);
+      for (const dep of (plugin?.dependencies || [])) {
+        if (this.registry.has(dep)) {
+          visit(dep);
+        }
+      }
+      result.push(name);
+    };
+
+    for (const name of this.registry.keys()) {
+      visit(name);
+    }
+
+    return result;
+  }
+
+  // Graceful shutdown
+  async shutdown() {
+    const sorted = this.topologicalSort().reverse();
+    for (const name of sorted) {
+      const state = this.instances.get(name);
+      if (state && state.stop) {
+        try {
+          await state.stop();
+        } catch (error) {
+          console.error(`[PluginLoader] Error stopping ${name}:`, error.message);
+        }
+      }
+      this.unwatchPlugin(name);
+    }
+    this.instances.clear();
+    this.registry.clear();
+  }
+}
+
+export default PluginLoader;

package/lib/plugins/acp-plugin.js

@@ -0,0 +1,90 @@
+// ACP plugin - OpenCode, Gemini, Kilo, Codex startup and health checks
+
+import { spawn } from 'child_process';
+import path from 'path';
+import fs from 'fs';
+
+export default {
+  name: 'acp',
+  version: '1.0.0',
+  dependencies: ['tools'],
+
+  async init(config, plugins) {
+    const tools = plugins.get('tools');
+    const toolProcesses = new Map();
+    const healthCheckIntervals = new Map();
+    const restartCounts = new Map();
+    const acpPorts = new Map();
+
+    const toolSpecs = [
+      { name: 'opencode', port: 18100, cmd: 'opencode acp --port 18100' },
+      { name: 'gemini', port: 18101, cmd: 'gemini acp --port 18101' },
+      { name: 'kilo', port: 18102, cmd: 'kilo acp --port 18102' },
+      { name: 'codex', port: 18103, cmd: 'codex acp --port 18103' },
+    ];
+
+    const startTool = async (spec) => {
+      try {
+        const proc = spawn('bash', ['-c', spec.cmd]);
+        toolProcesses.set(spec.name, proc);
+        acpPorts.set(spec.name, spec.port);
+        restartCounts.set(spec.name, 0);
+
+        // Health check every 30s
+        const interval = setInterval(() => {
+          if (proc.killed) {
+            clearInterval(interval);
+            healthCheckIntervals.delete(spec.name);
+          }
+        }, 30000);
+        healthCheckIntervals.set(spec.name, interval);
+      } catch (e) {
+        console.error(`[ACP] Failed to start ${spec.name}:`, e.message);
+      }
+    };
+
+    // Start all ACP tools
+    for (const spec of toolSpecs) {
+      await startTool(spec);
+    }
+
+    return {
+      routes: [
+        {
+          method: 'GET',
+          path: '/api/acp/status',
+          handler: (req, res) => {
+            const status = {};
+            for (const [name, proc] of toolProcesses) {
+              status[name] = {
+                running: !proc.killed,
+                port: acpPorts.get(name),
+                pid: proc.pid,
+                restarts: restartCounts.get(name) || 0,
+              };
+            }
+            res.json({ tools: status });
+          },
+        },
+      ],
+      wsHandlers: {},
+      api: {
+        getStatus: () => Object.fromEntries(acpPorts),
+      },
+      stop: async () => {
+        for (const [name, interval] of healthCheckIntervals) {
+          clearInterval(interval);
+        }
+        for (const [name, proc] of toolProcesses) {
+          if (proc && !proc.killed) proc.kill();
+        }
+      },
+    };
+  },
+
+  async reload(state) {
+    return state;
+  },
+
+  async stop() {},
+};

package/lib/plugins/agents-plugin.js

@@ -0,0 +1,80 @@
+// Agents plugin - agent discovery, runner spawning, process management
+
+import path from 'path';
+import { runClaudeWithStreaming } from '../claude-runner.js';
+
+export default {
+  name: 'agents',
+  version: '1.0.0',
+  dependencies: ['database', 'stream'],
+
+  async init(config, plugins) {
+    const db = plugins.get('database');
+    const stream = plugins.get('stream');
+    const discoveredAgents = new Map();
+    const activeExecutions = new Map();
+
+    // Discover agents on startup
+    const discoverAgents = async () => {
+      const agents = [
+        { id: 'gm-cc', name: 'Claude Code', bin: 'claude', installed: true },
+        { id: 'gm-oc', name: 'OpenCode', bin: 'opencode', installed: false },
+        { id: 'gm-gc', name: 'Gemini CLI', bin: 'gemini', installed: false },
+        { id: 'gm-kilo', name: 'Kilo', bin: 'kilo', installed: false },
+      ];
+      agents.forEach(a => discoveredAgents.set(a.id, a));
+      return agents;
+    };
+
+    await discoverAgents();
+
+    return {
+      routes: [
+        {
+          method: 'GET',
+          path: '/api/agents',
+          handler: (req, res) => {
+            res.json({ agents: Array.from(discoveredAgents.values()) });
+          },
+        },
+        {
+          method: 'POST',
+          path: '/api/conversations/:id/stream',
+          handler: async (req, res) => {
+            const { id } = req.params;
+            const { agentId, message } = req.body;
+
+            try {
+              const agent = discoveredAgents.get(agentId);
+              if (!agent) return res.status(404).json({ error: 'Agent not found' });
+
+              const session = stream.api.createSession(id);
+              // Use runClaudeWithStreaming instead
+              activeExecutions.set(id, { sessionId: session.id });
+
+              res.json({ sessionId: session.id, pid: proc.pid });
+            } catch (e) {
+              res.status(500).json({ error: e.message });
+            }
+          },
+        },
+      ],
+      wsHandlers: {},
+      api: {
+        getAgents: () => Array.from(discoveredAgents.values()),
+        discoverAgents,
+      },
+      stop: async () => {
+        for (const proc of activeExecutions.values()) {
+          if (proc && !proc.killed) proc.kill();
+        }
+      },
+    };
+  },
+
+  async reload(state) {
+    return state;
+  },
+
+  async stop() {},
+};