agent-state-machine 2.0.3 → 2.0.5

package/README.md

@@ -44,11 +44,11 @@ Requirements: Node.js >= 16.
 ```bash
 state-machine --setup <workflow-name>
 state-machine run <workflow-name>
+state-machine run <workflow-name> -reset
+state-machine run <workflow-name> -reset-hard
 
 
 state-machine history <workflow-name> [limit]
-state-machine reset <workflow-name> (clears memory/state)
-state-machine reset-hard <workflow-name> (clears everything: history/interactions/memory)
 ```
 
 Workflows live in:
@@ -140,7 +140,7 @@ export default async function() {
 
 `state-machine run` restarts your workflow from the top, loading the persisted state.
 
-If the workflow needs human input, it will **block inline** in the terminal. You’ll be told which `interactions/<slug>.md` file to edit; after you fill it in, press `y` in the same terminal session to continue.
+If the workflow needs human input, it will **block inline** in the terminal. You can answer in the terminal, edit `interactions/<slug>.md`, or respond in the browser.
 
 If the process is interrupted, running `state-machine run <workflow-name>` again will continue execution (assuming your workflow uses `memory` to skip completed steps).
 
@@ -172,8 +172,8 @@ memory.count = (memory.count || 0) + 1;
 
 Gets user input.
 
-- In a TTY, it prompts in the terminal.
-- Otherwise it creates `interactions/<slug>.md` and blocks until you confirm in the terminal.
+- In a TTY, it prompts in the terminal (or via the browser when remote follow is enabled).
+- Otherwise it creates `interactions/<slug>.md` and blocks until you confirm in the terminal (or respond in the browser).
 
 ```js
 const repo = await initialPrompt('What repo should I work on?', { slug: 'repo' });
@@ -298,7 +298,7 @@ export const config = {
 };
 ```
 
-The runtime captures the fully-built prompt in `state/history.jsonl`, viewable in the browser with live updates when running with the `--local` flag or via the remote URL.
+The runtime captures the fully-built prompt in `state/history.jsonl`, viewable in the browser with live updates when running with the `--local` flag or via the remote URL. Remote follow links persist across runs (stored in `workflow.js` config) unless you pass `-n`/`--new` to regenerate.
 
 ---
 

package/lib/remote/client.js

@@ -164,6 +164,18 @@ export class RemoteClient {
     });
   }
 
+  /**
+   * Sync history to remote (for manual edits to history.jsonl)
+   * @param {Array} history - Array of history entries
+   */
+  async sendHistorySync(history = []) {
+    await this.send({
+      type: 'history_sync',
+      sessionToken: this.sessionToken,
+      history,
+    });
+  }
+
   /**
    * Send an event to the server
    * @param {object} event - Event object with timestamp, event type, etc.

package/lib/runtime/runtime.js

@@ -164,6 +164,9 @@ export class WorkflowRuntime {
 
     const line = JSON.stringify(entry) + '\n';
 
+    // Track when we're writing to avoid triggering the file watcher
+    this._lastHistoryWrite = Date.now();
+
     // Prepend to file (read existing, write new + existing)
     let existing = '';
     if (fs.existsSync(this.historyFile)) {
@@ -533,22 +536,69 @@ export class WorkflowRuntime {
     // Send existing history if connected
     if (this.remoteClient.connected) {
       const history = this.loadHistory();
-      this.remoteClient.sendSessionInit(history);
+      await this.remoteClient.sendSessionInit(history);
     }
 
     this.remoteEnabled = true;
     this.remoteUrl = this.remoteClient.getRemoteUrl();
 
+    // Watch history.jsonl for manual edits and sync to remote
+    this.startHistoryWatcher();
+
     console.log(`\n${C.cyan}${C.bold}Remote follow enabled${C.reset}`);
     console.log(`  ${C.dim}URL:${C.reset} ${this.remoteUrl}\n`);
 
     return this.remoteUrl;
   }
 
+  /**
+   * Start watching history.jsonl for manual edits
+   */
+  startHistoryWatcher() {
+    if (this.historyWatcher) return;
+
+    // Debounce to avoid multiple syncs for rapid changes
+    let debounceTimer = null;
+
+    try {
+      this.historyWatcher = fs.watch(this.historyFile, (eventType) => {
+        if (eventType !== 'change') return;
+
+        // Debounce: wait 300ms after last change before syncing
+        if (debounceTimer) clearTimeout(debounceTimer);
+
+        debounceTimer = setTimeout(async () => {
+          // Don't sync if we just wrote to the file ourselves (within 500ms)
+          if (this._lastHistoryWrite && Date.now() - this._lastHistoryWrite < 500) return;
+
+          if (this.remoteClient && this.remoteEnabled) {
+            const history = this.loadHistory();
+            await this.remoteClient.sendHistorySync(history);
+            console.log(`${C.dim}Remote: History synced from file${C.reset}`);
+          }
+        }, 300);
+      });
+    } catch (err) {
+      // File might not exist yet, that's ok
+    }
+  }
+
+  /**
+   * Stop watching history.jsonl
+   */
+  stopHistoryWatcher() {
+    if (this.historyWatcher) {
+      this.historyWatcher.close();
+      this.historyWatcher = null;
+    }
+  }
+
   /**
    * Disable remote follow mode and disconnect
    */
   async disableRemote() {
+    this.stopHistoryWatcher();
+
     if (this.remoteClient) {
       await this.remoteClient.disconnect();
       this.remoteClient = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-state-machine",
-  "version": "2.0.3",
+  "version": "2.0.5",
   "type": "module",
   "description": "A workflow orchestrator for running agents and scripts in sequence with state management",
   "main": "lib/index.js",

package/vercel-server/api/events/[token].js

@@ -2,14 +2,14 @@
  * File: /vercel-server/api/events/[token].js
  *
  * SSE endpoint for browser connections
- * Streams history and real-time events to connected browsers
+ * Streams events to connected browsers from a single source of truth (events list)
  */
 
 import {
   getSession,
-  getHistory,
-  redis,
-  KEYS,
+  getEvents,
+  getEventsLength,
+  getEventsRange,
   refreshSession,
 } from '../../lib/redis.js';
 
@@ -48,20 +48,15 @@ export default async function handler(req, res) {
       workflowName: session.workflowName,
     })}\n\n`);
 
-    // Send existing history
-    const history = await getHistory(token);
+    // Send all existing events (single source of truth)
+    const events = await getEvents(token);
     res.write(`data: ${JSON.stringify({
       type: 'history',
-      entries: history,
+      entries: events,
     })}\n\n`);
 
-    // Poll for new events
-    const eventsListKey = `${KEYS.events(token)}:list`;
-    let lastEventIndex = 0;
-
-    // Get current list length to start from
-    const currentLength = await redis.llen(eventsListKey);
-    lastEventIndex = currentLength;
+    // Track current position for polling new events
+    let lastEventIndex = await getEventsLength(token);
 
     const pollInterval = setInterval(async () => {
       try {
@@ -69,15 +64,19 @@ export default async function handler(req, res) {
         await refreshSession(token);
 
         // Check for new events
-        const newLength = await redis.llen(eventsListKey);
+        const newLength = await getEventsLength(token);
 
         if (newLength > lastEventIndex) {
-          // Get new events (newest first)
-          const newEvents = await redis.lrange(eventsListKey, 0, newLength - lastEventIndex - 1);
-
-          for (const event of newEvents.reverse()) {
-            const eventData = typeof event === 'object' ? event : JSON.parse(event);
-            res.write(`data: ${JSON.stringify(eventData)}\n\n`);
+          // Get new events (they're prepended, so newest are at the start)
+          const newCount = newLength - lastEventIndex;
+          const newEvents = await getEventsRange(token, 0, newCount - 1);
+
+          // Send in chronological order (oldest first of the new batch)
+          for (const eventData of newEvents.reverse()) {
+            res.write(`data: ${JSON.stringify({
+              type: 'event',
+              ...eventData,
+            })}\n\n`);
           }
 
           lastEventIndex = newLength;
@@ -94,14 +93,13 @@ export default async function handler(req, res) {
       } catch (err) {
         console.error('Error polling events:', err);
       }
-    }, 2000);
+    }, 1000); // Poll every 1 second for faster updates
 
     // Clean up on client disconnect
     req.on('close', () => {
       clearInterval(pollInterval);
     });
 
-    // For Vercel, we need to keep the connection alive but also respect function timeout
     // Send keepalive pings
     const keepaliveInterval = setInterval(() => {
       res.write(': keepalive\n\n');

package/vercel-server/api/ws/cli.js

@@ -12,9 +12,8 @@ import {
   getSession,
   updateSession,
   setCLIConnected,
-  addHistoryEvent,
-  addHistoryEvents,
-  publishEvent,
+  addEvent,
+  setEvents,
   redis,
   KEYS,
 } from '../../lib/redis.js';
@@ -59,16 +58,8 @@ async function handlePost(req, res) {
         // Create session
         await createSession(sessionToken, { workflowName, cliConnected: true });
 
-        // Store initial history
-        if (history && history.length > 0) {
-          await addHistoryEvents(sessionToken, history);
-        }
-
-        // Notify browsers
-        await publishEvent(sessionToken, {
-          type: 'cli_connected',
-          workflowName,
-        });
+        // Replace events with the provided history snapshot (single source of truth)
+        await setEvents(sessionToken, history || []);
 
         return res.status(200).json({ success: true });
       }
@@ -79,9 +70,10 @@ async function handlePost(req, res) {
         // Update session as connected
         await setCLIConnected(sessionToken, true);
 
-        // Notify browsers
-        await publishEvent(sessionToken, {
-          type: 'cli_reconnected',
+        // Add reconnect event to events list
+        await addEvent(sessionToken, {
+          timestamp: new Date().toISOString(),
+          event: 'CLI_RECONNECTED',
           workflowName,
         });
 
@@ -101,14 +93,8 @@ async function handlePost(req, res) {
         delete historyEvent.sessionToken;
         delete historyEvent.type;
 
-        // Add to history
-        await addHistoryEvent(sessionToken, historyEvent);
-
-        // Notify browsers
-        await publishEvent(sessionToken, {
-          type: 'event',
-          ...historyEvent,
-        });
+        // Add to events list (single source of truth)
+        await addEvent(sessionToken, historyEvent);
 
         return res.status(200).json({ success: true });
       }
@@ -119,15 +105,25 @@ async function handlePost(req, res) {
         // Mark CLI as disconnected
         await setCLIConnected(sessionToken, false);
 
-        // Notify browsers
-        await publishEvent(sessionToken, {
-          type: 'cli_disconnected',
+        // Add disconnect event to events list
+        await addEvent(sessionToken, {
+          timestamp: new Date().toISOString(),
+          event: 'CLI_DISCONNECTED',
           reason,
         });
 
         return res.status(200).json({ success: true });
       }
 
+      case 'history_sync': {
+        const { history } = body;
+
+        // Replace events with synced history (for manual edits to history.jsonl)
+        await setEvents(sessionToken, history || []);
+
+        return res.status(200).json({ success: true });
+      }
+
       default:
         return res.status(400).json({ error: `Unknown message type: ${type}` });
     }