agent-state-machine 1.4.2 → 2.0.1

package/README.md

@@ -45,7 +45,7 @@ Requirements: Node.js >= 16.
 state-machine --setup <workflow-name>
 state-machine run <workflow-name>
 
-state-machine follow <workflow-name> (view prompt trace history in browser with live updates)
+
 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)
@@ -298,11 +298,7 @@ export const config = {
 };
 ```
 
-The runtime captures the fully-built prompt in `state/history.jsonl`, viewable in the browser with live updates via:
-
-```bash
-state-machine follow <workflow-name>
-```
+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.
 
 ---
 

package/bin/cli.js

@@ -5,7 +5,7 @@ import fs from 'fs';
 import { pathToFileURL, fileURLToPath } from 'url';
 import { WorkflowRuntime } from '../lib/index.js';
 import { setup } from '../lib/setup.js';
-import { startServer } from '../lib/ui/server.js';
+
 import { startLocalServer } from '../vercel-server/local-server.js';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -34,8 +34,8 @@ Agent State Machine CLI (Native JS Workflows Only) v${getVersion()}
 Usage:
   state-machine --setup <workflow-name>    Create a new workflow project
   state-machine run <workflow-name>        Run a workflow (remote follow enabled by default)
-  state-machine run <workflow-name> --local  Run with local server (localhost:3000)
-  state-machine follow <workflow-name>    View prompt trace history in browser with live updates
+  state-machine run <workflow-name> -l  Run with local server (localhost:3000)
+
   state-machine status [workflow-name]     Show current state (or list all)
   state-machine history <workflow-name> [limit]  Show execution history logs
   state-machine reset <workflow-name>      Reset workflow state (clears memory/state)
@@ -269,22 +269,7 @@ async function main() {
       }
       break;
 
-    case 'follow':
-      if (!workflowName) {
-        console.error('Error: Workflow name required');
-        console.error('Usage: state-machine follow <workflow-name>');
-        process.exit(1);
-      }
-      {
-        const workflowDir = resolveWorkflowDir(workflowName);
-        if (!fs.existsSync(workflowDir)) {
-          console.error(`Error: Workflow '${workflowName}' not found`);
-          process.exit(1);
-        }
-        startServer(workflowDir);
-        // Do not exit, server needs to stay alive
-      }
-      break;
+
 
     case 'reset':
       if (!workflowName) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-state-machine",
-  "version": "1.4.2",
+  "version": "2.0.1",
   "type": "module",
   "description": "A workflow orchestrator for running agents and scripts in sequence with state management",
   "main": "lib/index.js",
@@ -29,6 +29,8 @@
     "bin",
     "lib",
     "vercel-server/local-server.js",
-    "vercel-server/public"
+    "vercel-server/public",
+    "vercel-server/ui",
+    "vercel-server/api"
   ]
 }

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

@@ -0,0 +1,119 @@
+/**
+ * File: /vercel-server/api/events/[token].js
+ *
+ * SSE endpoint for browser connections
+ * Streams history and real-time events to connected browsers
+ */
+
+import {
+  getSession,
+  getHistory,
+  redis,
+  KEYS,
+  refreshSession,
+} from '../../lib/redis.js';
+
+export const config = {
+  maxDuration: 60, // Maximum 60 seconds for SSE
+};
+
+export default async function handler(req, res) {
+  const { token } = req.query;
+
+  if (!token) {
+    return res.status(400).json({ error: 'Missing token parameter' });
+  }
+
+  // Validate session
+  const session = await getSession(token);
+  if (!session) {
+    return res.status(404).json({ error: 'Session not found or expired' });
+  }
+
+  // Set up SSE headers
+  res.setHeader('Content-Type', 'text/event-stream');
+  res.setHeader('Cache-Control', 'no-cache, no-transform');
+  res.setHeader('Connection', 'keep-alive');
+  res.setHeader('Access-Control-Allow-Origin', '*');
+
+  // Send retry interval
+  res.write('retry: 3000\n\n');
+
+  // Send initial data
+  try {
+    // Send connection status
+    res.write(`data: ${JSON.stringify({
+      type: 'status',
+      cliConnected: session.cliConnected,
+      workflowName: session.workflowName,
+    })}\n\n`);
+
+    // Send existing history
+    const history = await getHistory(token);
+    res.write(`data: ${JSON.stringify({
+      type: 'history',
+      entries: history,
+    })}\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;
+
+    const pollInterval = setInterval(async () => {
+      try {
+        // Refresh session TTL
+        await refreshSession(token);
+
+        // Check for new events
+        const newLength = await redis.llen(eventsListKey);
+
+        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`);
+          }
+
+          lastEventIndex = newLength;
+        }
+
+        // Check CLI status
+        const updatedSession = await getSession(token);
+        if (updatedSession && updatedSession.cliConnected !== session.cliConnected) {
+          session.cliConnected = updatedSession.cliConnected;
+          res.write(`data: ${JSON.stringify({
+            type: updatedSession.cliConnected ? 'cli_reconnected' : 'cli_disconnected',
+          })}\n\n`);
+        }
+      } catch (err) {
+        console.error('Error polling events:', err);
+      }
+    }, 2000);
+
+    // 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');
+    }, 15000);
+
+    req.on('close', () => {
+      clearInterval(keepaliveInterval);
+    });
+
+  } catch (err) {
+    console.error('SSE error:', err);
+    res.write(`data: ${JSON.stringify({ type: 'error', message: err.message })}\n\n`);
+    res.end();
+  }
+}

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

@@ -0,0 +1,51 @@
+/**
+ * File: /vercel-server/api/history/[token].js
+ *
+ * REST endpoint to get session history
+ */
+
+import { getSession, getHistory, refreshSession } from '../../lib/redis.js';
+
+export default async function handler(req, res) {
+  // Enable CORS
+  res.setHeader('Access-Control-Allow-Origin', '*');
+  res.setHeader('Access-Control-Allow-Methods', 'GET, OPTIONS');
+  res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+
+  if (req.method === 'OPTIONS') {
+    return res.status(200).end();
+  }
+
+  if (req.method !== 'GET') {
+    return res.status(405).json({ error: 'Method not allowed' });
+  }
+
+  const { token } = req.query;
+
+  if (!token) {
+    return res.status(400).json({ error: 'Missing token parameter' });
+  }
+
+  try {
+    // Validate session
+    const session = await getSession(token);
+    if (!session) {
+      return res.status(404).json({ error: 'Session not found or expired' });
+    }
+
+    // Refresh session TTL
+    await refreshSession(token);
+
+    // Get history
+    const entries = await getHistory(token);
+
+    return res.status(200).json({
+      workflowName: session.workflowName,
+      cliConnected: session.cliConnected,
+      entries,
+    });
+  } catch (err) {
+    console.error('Error getting history:', err);
+    return res.status(500).json({ error: err.message });
+  }
+}

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

@@ -0,0 +1,49 @@
+// /vercel-server/api/session/[token].js
+import path from 'path';
+import { readFile } from 'fs/promises';
+import { fileURLToPath } from 'url';
+
+import { getSession } from '../../lib/redis.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+let cachedTemplate = null;
+async function getTemplate() {
+  if (cachedTemplate) return cachedTemplate;
+  // Point to the unified template in vercel-server/ui/index.html
+  const templatePath = path.join(__dirname, '..', '..', 'ui', 'index.html');
+  cachedTemplate = await readFile(templatePath, 'utf8');
+  return cachedTemplate;
+}
+
+export default async function handler(req, res) {
+  const { token } = req.query;
+
+  if (!token) return res.status(400).send('Missing session token');
+
+  const session = await getSession(token);
+  if (!session) {
+    return res.status(404).send(`<!DOCTYPE html>
+<html>
+  <head>
+    <title>Session Not Found</title>
+    <style>body { font-family: system-ui; max-width: 600px; margin: 100px auto; text-align: center; }</style>
+  </head>
+  <body>
+    <h1>Session Not Found</h1>
+    <p>This session has expired or does not exist.</p>
+    <p>Sessions expire 30 minutes after the last activity.</p>
+  </body>
+</html>`);
+  }
+
+  const template = await getTemplate();
+
+  const html = template
+    .replace(/\{\{SESSION_TOKEN\}\}/g, token)
+    .replace(/\{\{WORKFLOW_NAME\}\}/g, session.workflowName || 'Workflow');
+
+  res.setHeader('Content-Type', 'text/html; charset=utf-8');
+  res.send(html);
+}

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

@@ -0,0 +1,94 @@
+/**
+ * File: /vercel-server/api/submit/[token].js
+ *
+ * POST endpoint for browser interaction submissions
+ */
+
+import {
+  getSession,
+  addHistoryEvent,
+  publishEvent,
+  redis,
+  KEYS,
+} from '../../lib/redis.js';
+
+export default async function handler(req, res) {
+  // Enable CORS
+  res.setHeader('Access-Control-Allow-Origin', '*');
+  res.setHeader('Access-Control-Allow-Methods', 'POST, OPTIONS');
+  res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+
+  if (req.method === 'OPTIONS') {
+    return res.status(200).end();
+  }
+
+  if (req.method !== 'POST') {
+    return res.status(405).json({ error: 'Method not allowed' });
+  }
+
+  const { token } = req.query;
+
+  if (!token) {
+    return res.status(400).json({ error: 'Missing token parameter' });
+  }
+
+  try {
+    // Validate session
+    const session = await getSession(token);
+    if (!session) {
+      return res.status(404).json({ error: 'Session not found or expired' });
+    }
+
+    // Check if CLI is connected
+    if (!session.cliConnected) {
+      return res.status(503).json({ error: 'CLI is disconnected. Cannot submit interaction.' });
+    }
+
+    // Parse body
+    const body = typeof req.body === 'string' ? JSON.parse(req.body) : req.body;
+    const { slug, targetKey, response } = body;
+
+    if (!slug || !response) {
+      return res.status(400).json({ error: 'Missing required fields: slug, response' });
+    }
+
+    // Validate response size (max 1MB)
+    if (response.length > 1024 * 1024) {
+      return res.status(413).json({ error: 'Response too large (max 1MB)' });
+    }
+
+    // Push to pending interactions list (for CLI to poll)
+    const pendingKey = `${KEYS.interactions(token)}:pending`;
+    await redis.rpush(pendingKey, JSON.stringify({
+      slug,
+      targetKey: targetKey || `_interaction_${slug}`,
+      response,
+    }));
+
+    // Set TTL on pending list
+    await redis.expire(pendingKey, 300); // 5 minutes
+
+    // Log event to history (include answer preview)
+    const event = {
+      timestamp: new Date().toISOString(),
+      event: 'INTERACTION_SUBMITTED',
+      slug,
+      targetKey: targetKey || `_interaction_${slug}`,
+      answer: response.substring(0, 200) + (response.length > 200 ? '...' : ''),
+      source: 'remote',
+    };
+
+    await addHistoryEvent(token, event);
+
+    // Notify other browsers
+    await publishEvent(token, {
+      type: 'event',
+      ...event,
+    });
+
+    return res.status(200).json({ success: true });
+  } catch (err) {
+    console.error('Error submitting interaction:', err);
+    return res.status(500).json({ error: err.message });
+  }
+}

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

@@ -0,0 +1,186 @@
+/**
+ * File: /vercel-server/api/ws/cli.js
+ *
+ * HTTP-based endpoint for CLI communication (replaces WebSocket for serverless)
+ *
+ * POST: Receive messages from CLI (session_init, event, session_end)
+ * GET: Long-poll for interaction responses
+ */
+
+import {
+  createSession,
+  getSession,
+  updateSession,
+  setCLIConnected,
+  addHistoryEvent,
+  addHistoryEvents,
+  publishEvent,
+  redis,
+  KEYS,
+} from '../../lib/redis.js';
+
+export default async function handler(req, res) {
+  // Enable CORS
+  res.setHeader('Access-Control-Allow-Origin', '*');
+  res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+  res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+
+  if (req.method === 'OPTIONS') {
+    return res.status(200).end();
+  }
+
+  if (req.method === 'POST') {
+    return handlePost(req, res);
+  }
+
+  if (req.method === 'GET') {
+    return handleGet(req, res);
+  }
+
+  return res.status(405).json({ error: 'Method not allowed' });
+}
+
+/**
+ * Handle POST requests from CLI
+ */
+async function handlePost(req, res) {
+  const body = typeof req.body === 'string' ? JSON.parse(req.body) : req.body;
+  const { type, sessionToken } = body;
+
+  if (!sessionToken) {
+    return res.status(400).json({ error: 'Missing sessionToken' });
+  }
+
+  try {
+    switch (type) {
+      case 'session_init': {
+        const { workflowName, history } = body;
+
+        // 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,
+        });
+
+        return res.status(200).json({ success: true });
+      }
+
+      case 'session_reconnect': {
+        const { workflowName } = body;
+
+        // Update session as connected
+        await setCLIConnected(sessionToken, true);
+
+        // Notify browsers
+        await publishEvent(sessionToken, {
+          type: 'cli_reconnected',
+          workflowName,
+        });
+
+        return res.status(200).json({ success: true });
+      }
+
+      case 'event': {
+        const { timestamp, event, ...eventData } = body;
+
+        const historyEvent = {
+          timestamp: timestamp || new Date().toISOString(),
+          event,
+          ...eventData,
+        };
+
+        // Remove sessionToken and type from event data
+        delete historyEvent.sessionToken;
+        delete historyEvent.type;
+
+        // Add to history
+        await addHistoryEvent(sessionToken, historyEvent);
+
+        // Notify browsers
+        await publishEvent(sessionToken, {
+          type: 'event',
+          ...historyEvent,
+        });
+
+        return res.status(200).json({ success: true });
+      }
+
+      case 'session_end': {
+        const { reason } = body;
+
+        // Mark CLI as disconnected
+        await setCLIConnected(sessionToken, false);
+
+        // Notify browsers
+        await publishEvent(sessionToken, {
+          type: 'cli_disconnected',
+          reason,
+        });
+
+        return res.status(200).json({ success: true });
+      }
+
+      default:
+        return res.status(400).json({ error: `Unknown message type: ${type}` });
+    }
+  } catch (err) {
+    console.error('Error handling CLI message:', err);
+    return res.status(500).json({ error: err.message });
+  }
+}
+
+/**
+ * Handle GET requests - long-poll for interaction responses
+ */
+async function handleGet(req, res) {
+  const { token, timeout = '30000' } = req.query;
+
+  if (!token) {
+    return res.status(400).json({ error: 'Missing token parameter' });
+  }
+
+  const session = await getSession(token);
+  if (!session) {
+    return res.status(404).json({ error: 'Session not found' });
+  }
+
+  const timeoutMs = Math.min(parseInt(timeout, 10), 55000); // Max 55s for Vercel
+  const channel = KEYS.interactions(token);
+
+  // Check for pending interactions using a list
+  const pendingKey = `${channel}:pending`;
+
+  try {
+    // Try to get a pending interaction
+    const startTime = Date.now();
+
+    while (Date.now() - startTime < timeoutMs) {
+      const pending = await redis.lpop(pendingKey);
+
+      if (pending) {
+        const data = typeof pending === 'object' ? pending : JSON.parse(pending);
+        return res.status(200).json({
+          type: 'interaction_response',
+          ...data,
+        });
+      }
+
+      // Wait before checking again
+      await new Promise((resolve) => setTimeout(resolve, 1000));
+    }
+
+    // Timeout - no interaction received
+    return res.status(204).end();
+  } catch (err) {
+    console.error('Error polling for interactions:', err);
+    return res.status(500).json({ error: err.message });
+  }
+}