agent-state-machine 1.3.3 → 1.4.0

package/bin/cli.js

@@ -23,13 +23,16 @@ function getVersion() {
   }
 }
 
+// Default remote server URL (can be overridden with STATE_MACHINE_REMOTE_URL env var)
+const DEFAULT_REMOTE_URL = process.env.STATE_MACHINE_REMOTE_URL || 'http://localhost:3001';
+
 function printHelp() {
   console.log(`
 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 (loads existing state)
+  state-machine run <workflow-name> [--remote]  Run a workflow (--remote enables remote follow)
   state-machine follow <workflow-name>    View prompt trace history in browser with live updates
   state-machine status [workflow-name]     Show current state (or list all)
   state-machine history <workflow-name> [limit]  Show execution history logs
@@ -40,9 +43,13 @@ Usage:
 
 Options:
   --setup, -s     Initialize a new workflow with directory structure
+  --remote, -r    Enable remote follow (generates shareable URL for browser access)
   --help, -h      Show help
   --version, -v   Show version
 
+Environment Variables:
+  STATE_MACHINE_REMOTE_URL    Override the default remote server URL
+
 Workflow Structure:
   workflows/<name>/
   ├── workflow.js        # Native JS workflow (async/await)
@@ -136,7 +143,7 @@ function listWorkflows() {
   console.log('');
 }
 
-async function runOrResume(workflowName) {
+async function runOrResume(workflowName, { remoteEnabled = false } = {}) {
   const workflowDir = resolveWorkflowDir(workflowName);
 
   if (!fs.existsSync(workflowDir)) {
@@ -154,7 +161,20 @@ async function runOrResume(workflowName) {
   const runtime = new WorkflowRuntime(workflowDir);
   const workflowUrl = pathToFileURL(entry).href;
 
-  await runtime.runWorkflow(workflowUrl);
+  // Enable remote follow mode if requested
+  if (remoteEnabled) {
+    const remoteUrl = process.env.STATE_MACHINE_REMOTE_URL || DEFAULT_REMOTE_URL;
+    await runtime.enableRemote(remoteUrl);
+  }
+
+  try {
+    await runtime.runWorkflow(workflowUrl);
+  } finally {
+    // Always disable remote on completion
+    if (remoteEnabled) {
+      await runtime.disableRemote();
+    }
+  }
 }
 
 async function main() {
@@ -185,14 +205,17 @@ async function main() {
     case 'run':
       if (!workflowName) {
         console.error('Error: Workflow name required');
-        console.error(`Usage: state-machine ${command} <workflow-name>`);
+        console.error(`Usage: state-machine ${command} <workflow-name> [--remote]`);
         process.exit(1);
       }
-      try {
-        await runOrResume(workflowName);
-      } catch (err) {
-        console.error('Error:', err.message || String(err));
-        process.exit(1);
+      {
+        const remoteEnabled = args.includes('--remote') || args.includes('-r');
+        try {
+          await runOrResume(workflowName, { remoteEnabled });
+        } catch (err) {
+          console.error('Error:', err.message || String(err));
+          process.exit(1);
+        }
       }
       break;
 

package/lib/remote/client.js

@@ -0,0 +1,252 @@
+/**
+ * File: /lib/remote/client.js
+ *
+ * RemoteClient - HTTP client for connecting to the remote follow server
+ * Uses HTTP POST for sending events and long-polling for receiving interactions
+ */
+
+import crypto from 'crypto';
+import http from 'http';
+import https from 'https';
+
+// ANSI Colors
+const C = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  cyan: '\x1b[36m'
+};
+
+/**
+ * Generate a cryptographically secure session token
+ * @returns {string} 32-byte base64url-encoded token
+ */
+export function generateSessionToken() {
+  return crypto.randomBytes(32).toString('base64url');
+}
+
+/**
+ * Make an HTTP/HTTPS request
+ */
+function makeRequest(url, options, body = null) {
+  return new Promise((resolve, reject) => {
+    const parsedUrl = new URL(url);
+    const client = parsedUrl.protocol === 'https:' ? https : http;
+
+    const req = client.request(parsedUrl, options, (res) => {
+      let data = '';
+
+      res.on('data', (chunk) => {
+        data += chunk;
+      });
+
+      res.on('end', () => {
+        let parsedData = null;
+        if (data) {
+          try {
+            parsedData = JSON.parse(data);
+          } catch {
+            // Response is not JSON (could be HTML error page)
+            parsedData = { error: data.substring(0, 200) };
+          }
+        }
+        resolve({
+          status: res.statusCode,
+          data: parsedData,
+        });
+      });
+    });
+
+    req.on('error', reject);
+
+    if (body) {
+      req.write(JSON.stringify(body));
+    }
+
+    req.end();
+  });
+}
+
+/**
+ * RemoteClient class - manages HTTP connection to remote server
+ */
+export class RemoteClient {
+  /**
+   * @param {object} options
+   * @param {string} options.serverUrl - Base URL of remote server (e.g., https://example.vercel.app)
+   * @param {string} options.workflowName - Name of the workflow
+   * @param {function} options.onInteractionResponse - Callback when interaction response received
+   * @param {function} [options.onStatusChange] - Callback when connection status changes
+   */
+  constructor(options) {
+    this.serverUrl = options.serverUrl.replace(/\/$/, ''); // Remove trailing slash
+    this.workflowName = options.workflowName;
+    this.onInteractionResponse = options.onInteractionResponse;
+    this.onStatusChange = options.onStatusChange || (() => {});
+
+    this.sessionToken = generateSessionToken();
+    this.connected = false;
+    this.polling = false;
+    this.pollAbortController = null;
+    this.initialHistorySent = false;
+  }
+
+  /**
+   * Get the full remote URL for browser access
+   */
+  getRemoteUrl() {
+    return `${this.serverUrl}/s/${this.sessionToken}`;
+  }
+
+  /**
+   * Connect to the remote server
+   * @returns {Promise<void>}
+   */
+  async connect() {
+    try {
+      // Test connection by making a simple request
+      const testUrl = `${this.serverUrl}/api/history/${this.sessionToken}`;
+      const response = await makeRequest(testUrl, { method: 'GET' });
+
+      // 404 is expected for new sessions
+      if (response.status !== 404 && response.status !== 200) {
+        throw new Error(`Server returned ${response.status}`);
+      }
+
+      this.connected = true;
+      this.onStatusChange('connected');
+
+      // Start polling for interactions
+      this.startPolling();
+
+    } catch (err) {
+      console.log(`${C.yellow}Warning: Could not connect to remote server: ${err.message}${C.reset}`);
+      // Don't fail - remote is optional
+    }
+  }
+
+  /**
+   * Send a message to the server via HTTP POST
+   */
+  async send(msg) {
+    if (!this.connected) {
+      return;
+    }
+
+    try {
+      const url = `${this.serverUrl}/api/ws/cli`;
+      await makeRequest(url, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+      }, msg);
+    } catch (err) {
+      console.error(`${C.dim}Remote: Failed to send message: ${err.message}${C.reset}`);
+    }
+  }
+
+  /**
+   * Send initial session info with history
+   * @param {Array} history - Array of history entries
+   */
+  async sendSessionInit(history = []) {
+    this.initialHistorySent = true;
+    await this.send({
+      type: 'session_init',
+      sessionToken: this.sessionToken,
+      workflowName: this.workflowName,
+      history,
+    });
+  }
+
+  /**
+   * Send an event to the server
+   * @param {object} event - Event object with timestamp, event type, etc.
+   */
+  async sendEvent(event) {
+    // Only send events after initial history has been sent
+    if (!this.initialHistorySent) {
+      return;
+    }
+
+    await this.send({
+      type: 'event',
+      sessionToken: this.sessionToken,
+      ...event,
+    });
+  }
+
+  /**
+   * Send session end notification
+   * @param {string} reason - Reason for ending (completed, failed, user_quit)
+   */
+  async sendSessionEnd(reason = 'completed') {
+    await this.send({
+      type: 'session_end',
+      sessionToken: this.sessionToken,
+      reason,
+    });
+  }
+
+  /**
+   * Start polling for interaction responses
+   */
+  startPolling() {
+    if (this.polling) return;
+    this.polling = true;
+
+    this.poll();
+  }
+
+  /**
+   * Poll for interaction responses
+   */
+  async poll() {
+    while (this.polling && this.connected) {
+      try {
+        const url = `${this.serverUrl}/api/ws/cli?token=${this.sessionToken}&timeout=30000`;
+        const response = await makeRequest(url, { method: 'GET' });
+
+        if (response.status === 200 && response.data) {
+          const { type, slug, targetKey, response: interactionResponse } = response.data;
+
+          if (type === 'interaction_response' && this.onInteractionResponse) {
+            this.onInteractionResponse(slug, targetKey, interactionResponse);
+          }
+        }
+
+        // If 204 (no content), just continue polling
+        // Small delay between polls
+        await new Promise(resolve => setTimeout(resolve, 500));
+
+      } catch (err) {
+        // Connection error - wait and retry
+        await new Promise(resolve => setTimeout(resolve, 5000));
+      }
+    }
+  }
+
+  /**
+   * Stop polling
+   */
+  stopPolling() {
+    this.polling = false;
+  }
+
+  /**
+   * Disconnect from the server
+   */
+  async disconnect() {
+    this.stopPolling();
+
+    if (this.connected) {
+      await this.sendSessionEnd('completed');
+    }
+
+    this.connected = false;
+  }
+}

package/lib/runtime/prompt.js

@@ -11,6 +11,15 @@ import path from 'path';
 import readline from 'readline';
 import { getCurrentRuntime } from './runtime.js';
 
+const C = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  cyan: '\x1b[36m',
+  yellow: '\x1b[33m',
+  green: '\x1b[32m',
+  dim: '\x1b[2m'
+};
+
 /**
  * Request user input with memory-based resume support
  * @param {string} question - Question to ask the user
@@ -35,9 +44,8 @@ export async function initialPrompt(question, options = {}) {
 
   // Check if we're in TTY mode (interactive terminal)
   if (process.stdin.isTTY && process.stdout.isTTY) {
-    // Interactive mode - prompt directly
-    console.log('');
-    const answer = await askQuestion(question);
+    // Interactive mode - prompt directly, with remote support
+    const answer = await askQuestionWithRemote(runtime, question, slug, memoryKey);
     console.log('');
 
     // Save the response to memory
@@ -88,7 +96,57 @@ ${question}
 }
 
 /**
- * Interactive terminal question
+ * Interactive terminal question with remote support
+ * Allows both local TTY input and remote browser responses
+ */
+function askQuestionWithRemote(runtime, question, slug, memoryKey) {
+  return new Promise((resolve) => {
+    let resolved = false;
+
+    const cleanup = () => {
+      resolved = true;
+      runtime.pendingRemoteInteraction = null;
+    };
+
+    // Set up remote interaction listener if remote is enabled
+    if (runtime.remoteEnabled) {
+      runtime.pendingRemoteInteraction = {
+        slug,
+        targetKey: memoryKey,
+        resolve: (response) => {
+          if (resolved) return;
+          cleanup();
+          rl.close();
+          console.log(`\n${C.green}✓ Answered via remote${C.reset}`);
+          resolve(response);
+        },
+        reject: () => {} // Prompts don't reject
+      };
+    }
+
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout
+    });
+
+    // Show remote URL if available
+    let prompt = `\n${C.cyan}${C.bold}${question}${C.reset}`;
+    if (runtime.remoteEnabled && runtime.remoteUrl) {
+      prompt += `\n${C.dim}(Remote: ${runtime.remoteUrl})${C.reset}`;
+    }
+    prompt += `\n${C.yellow}> ${C.reset}`;
+
+    rl.question(prompt, (answer) => {
+      if (resolved) return;
+      cleanup();
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+/**
+ * Interactive terminal question (simple, no remote support)
  */
 function askQuestion(question) {
   return new Promise((resolve) => {
@@ -97,7 +155,8 @@ function askQuestion(question) {
       output: process.stdout
     });
 
-    rl.question(`${question}\n> `, (answer) => {
+    // Colorize the question and the input marker
+    rl.question(`\n${C.cyan}${C.bold}${question}${C.reset}\n${C.yellow}> ${C.reset}`, (answer) => {
       rl.close();
       resolve(answer.trim());
     });
@@ -113,4 +172,4 @@ function generateSlug(question) {
     .replace(/[^a-z0-9]+/g, '-')
     .replace(/^-+|-+$/g, '')
     .substring(0, 30);
-}
+}

package/lib/runtime/runtime.js

@@ -10,11 +10,26 @@ import fs from 'fs';
 import path from 'path';
 import readline from 'readline';
 import { createMemoryProxy } from './memory.js';
+import { RemoteClient } from '../remote/client.js';
 
 // Global runtime reference for agent() and memory access
 // stored on globalThis to ensure singleton access across different module instances (CLI vs local)
 const RUNTIME_KEY = Symbol.for('agent-state-machine.runtime');
 
+// ANSI Colors
+const C = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  magenta: '\x1b[35m',
+  cyan: '\x1b[36m',
+  gray: '\x1b[90m'
+};
+
 export function getCurrentRuntime() {
   return globalThis[RUNTIME_KEY];
 }
@@ -63,6 +78,12 @@ export class WorkflowRuntime {
 
     // Load steering
     this.steering = this.loadSteering();
+
+    // Remote follow state
+    this.remoteClient = null;
+    this.remoteEnabled = false;
+    this.remoteUrl = null;
+    this.pendingRemoteInteraction = null; // { slug, targetKey, resolve, reject }
   }
 
   ensureDirectories() {
@@ -82,7 +103,7 @@ export class WorkflowRuntime {
       try {
         return JSON.parse(fs.readFileSync(this.stateFile, 'utf-8'));
       } catch (err) {
-        console.warn(`Warning: Failed to load state: ${err.message}`);
+        console.warn(`${C.yellow}Warning: Failed to load state: ${err.message}${C.reset}`);
       }
     }
     return {};
@@ -105,7 +126,7 @@ export class WorkflowRuntime {
         const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
         steering.enabled = config.enabled !== false;
       } catch (err) {
-        console.warn(`Warning: Failed to load steering config: ${err.message}`);
+        console.warn(`${C.yellow}Warning: Failed to load steering config: ${err.message}${C.reset}`);
       }
     }
 
@@ -149,6 +170,39 @@ export class WorkflowRuntime {
       existing = fs.readFileSync(this.historyFile, 'utf-8');
     }
     fs.writeFileSync(this.historyFile, line + existing);
+
+    // Forward to remote if connected
+    if (this.remoteClient && this.remoteEnabled) {
+      this.remoteClient.sendEvent(entry);
+    }
+  }
+
+  /**
+   * Load all history entries from history.jsonl
+   * @returns {Array} Array of history entry objects
+   */
+  loadHistory() {
+    if (!fs.existsSync(this.historyFile)) {
+      return [];
+    }
+
+    try {
+      const content = fs.readFileSync(this.historyFile, 'utf-8');
+      return content
+        .trim()
+        .split('\n')
+        .filter(Boolean)
+        .map(line => {
+          try {
+            return JSON.parse(line);
+          } catch {
+            return null;
+          }
+        })
+        .filter(Boolean);
+    } catch {
+      return [];
+    }
   }
 
   /**
@@ -188,7 +242,7 @@ export class WorkflowRuntime {
       this.persist();
       this.prependHistory({ event: 'WORKFLOW_COMPLETED' });
 
-      console.log(`\n✓ Workflow '${this.workflowName}' completed successfully!`);
+      console.log(`\n${C.green}✓ Workflow '${this.workflowName}' completed successfully!${C.reset}`);
     } catch (err) {
       this.status = 'FAILED';
       this._error = err.message;
@@ -199,7 +253,7 @@ export class WorkflowRuntime {
         error: err.message
       });
 
-      console.error(`\n✗ Workflow '${this.workflowName}' failed: ${err.message}`);
+      console.error(`\n${C.red}✗ Workflow '${this.workflowName}' failed: ${err.message}${C.reset}`);
       throw err;
     } finally {
       clearCurrentRuntime();
@@ -208,10 +262,17 @@ export class WorkflowRuntime {
 
   /**
    * Wait for user to confirm interaction is complete, then return the response
+   * Supports both local TTY input and remote browser responses
    */
   async waitForInteraction(filePath, slug, targetKey) {
-    console.log(`\n⏸ Interaction required. Edit: ${filePath}`);
-    console.log(`  Enter 'y' to proceed or 'q' to quit.\n`);
+    console.log(`\n${C.yellow}${C.bold}⏸  Interaction required.${C.reset}`);
+
+    if (this.remoteEnabled && this.remoteUrl) {
+      console.log(`  ${C.cyan}Remote:${C.reset} ${this.remoteUrl}`);
+    }
+
+    console.log(`  ${C.dim}Edit: ${filePath}${C.reset}`);
+    console.log(`  Enter ${C.bold}y${C.reset} to proceed or ${C.bold}q${C.reset} to quit.\n`);
 
     const rl = readline.createInterface({
       input: process.stdin,
@@ -219,12 +280,57 @@ export class WorkflowRuntime {
     });
 
     return new Promise((resolve, reject) => {
+      // Track if we've already resolved (to prevent double-resolution)
+      let resolved = false;
+
+      const cleanup = () => {
+        resolved = true;
+        rl.close();
+        this.pendingRemoteInteraction = null;
+      };
+
+      // Set up remote interaction listener
+      if (this.remoteEnabled) {
+        this.pendingRemoteInteraction = {
+          slug,
+          targetKey,
+          resolve: (response) => {
+            if (resolved) return;
+            cleanup();
+
+            // Store in memory
+            this._rawMemory[targetKey] = response;
+            this.persist();
+
+            this.prependHistory({
+              event: 'INTERACTION_RESOLVED',
+              slug,
+              targetKey,
+              source: 'remote'
+            });
+
+            console.log(`\n${C.green}✓ Interaction resolved (remote): ${slug}${C.reset}`);
+            resolve(response);
+          },
+          reject: (err) => {
+            if (resolved) return;
+            cleanup();
+            reject(err);
+          }
+        };
+      }
+
+      // Local TTY input loop
       const ask = () => {
-        rl.question('> ', (answer) => {
+        if (resolved) return;
+
+        rl.question(`${C.dim}> ${C.reset}`, (answer) => {
+          if (resolved) return;
+
           const a = answer.trim().toLowerCase();
           if (a === 'y') {
-            rl.close();
-            // Read and return the response
+            cleanup();
+            // Read and return the response from file
             try {
               const response = this.readInteractionResponse(filePath, slug, targetKey);
               resolve(response);
@@ -232,7 +338,7 @@ export class WorkflowRuntime {
               reject(err);
             }
           } else if (a === 'q') {
-            rl.close();
+            cleanup();
             reject(new Error('User quit workflow'));
           } else {
             ask();
@@ -243,6 +349,17 @@ export class WorkflowRuntime {
     });
   }
 
+  /**
+   * Handle interaction response received from remote browser
+   * Called by RemoteClient when it receives an interaction_response message
+   */
+  handleRemoteInteraction(slug, targetKey, response) {
+    if (this.pendingRemoteInteraction &&
+        this.pendingRemoteInteraction.slug === slug) {
+      this.pendingRemoteInteraction.resolve(response);
+    }
+  }
+
   /**
    * Read the user's response from an interaction file
    */
@@ -268,7 +385,7 @@ export class WorkflowRuntime {
       targetKey
     });
 
-    console.log(`\n✓ Interaction resolved: ${slug}`);
+    console.log(`\n${C.green}✓ Interaction resolved: ${slug}${C.reset}`);
     return response;
   }
 
@@ -276,20 +393,27 @@ export class WorkflowRuntime {
    * Show workflow status
    */
   showStatus() {
-    console.log(`\nWorkflow: ${this.workflowName}`);
-    console.log('─'.repeat(40));
-    console.log(`Status: ${this.status}`);
+    console.log(`\n${C.bold}Workflow: ${C.cyan}${this.workflowName}${C.reset}`);
+    console.log(`${C.dim}${'─'.repeat(40)}${C.reset}`);
+    
+    let statusColor = C.reset;
+    if (this.status === 'COMPLETED') statusColor = C.green;
+    if (this.status === 'FAILED') statusColor = C.red;
+    if (this.status === 'RUNNING') statusColor = C.blue;
+    if (this.status === 'IDLE') statusColor = C.gray;
+    
+    console.log(`Status: ${statusColor}${this.status}${C.reset}`);
 
     if (this.startedAt) {
       console.log(`Started: ${this.startedAt}`);
     }
 
     if (this._error) {
-      console.log(`Error: ${this._error}`);
+      console.log(`Error: ${C.red}${this._error}${C.reset}`);
     }
 
     const memoryKeys = Object.keys(this._rawMemory).filter((k) => !k.startsWith('_'));
-    console.log(`\nMemory Keys: ${memoryKeys.length}`);
+    console.log(`\nMemory Keys: ${C.yellow}${memoryKeys.length}${C.reset}`);
     if (memoryKeys.length > 0) {
       console.log(`  ${memoryKeys.slice(0, 10).join(', ')}${memoryKeys.length > 10 ? '...' : ''}`);
     }
@@ -299,8 +423,8 @@ export class WorkflowRuntime {
    * Show execution history
    */
   showHistory(limit = 20) {
-    console.log(`\nHistory: ${this.workflowName}`);
-    console.log('─'.repeat(40));
+    console.log(`\n${C.bold}History: ${C.cyan}${this.workflowName}${C.reset}`);
+    console.log(`${C.dim}${'─'.repeat(40)}${C.reset}`);
 
     if (!fs.existsSync(this.historyFile)) {
       console.log('No history found.');
@@ -318,10 +442,17 @@ export class WorkflowRuntime {
       try {
         const entry = JSON.parse(line);
         const time = entry.timestamp ? entry.timestamp.split('T')[1]?.split('.')[0] : '';
-        console.log(`[${time}] ${entry.event}`);
-        if (entry.agent) console.log(`  Agent: ${entry.agent}`);
-        if (entry.slug) console.log(`  Slug: ${entry.slug}`);
-        if (entry.error) console.log(`  Error: ${entry.error}`);
+        
+        let eventColor = C.reset;
+        if (entry.event.endsWith('_STARTED')) eventColor = C.blue;
+        if (entry.event.endsWith('_COMPLETED')) eventColor = C.green;
+        if (entry.event.endsWith('_FAILED')) eventColor = C.red;
+        if (entry.event.includes('INTERACTION')) eventColor = C.yellow;
+
+        console.log(`${C.dim}[${time}]${C.reset} ${eventColor}${entry.event}${C.reset}`);
+        if (entry.agent) console.log(`  ${C.dim}Agent:${C.reset} ${entry.agent}`);
+        if (entry.slug) console.log(`  ${C.dim}Slug:${C.reset} ${entry.slug}`);
+        if (entry.error) console.log(`  ${C.red}Error: ${entry.error}${C.reset}`);
       } catch {}
     }
   }
@@ -341,7 +472,7 @@ export class WorkflowRuntime {
     this.persist();
     this.prependHistory({ event: 'WORKFLOW_RESET' });
 
-    console.log(`\n✓ Workflow '${this.workflowName}' reset`);
+    console.log(`\n${C.yellow}✓ Workflow '${this.workflowName}' reset${C.reset}`);
   }
 
   /**
@@ -370,10 +501,62 @@ export class WorkflowRuntime {
 
     this.persist();
 
-    console.log(`\n✓ Workflow '${this.workflowName}' hard reset (history and interactions cleared)`);
+    console.log(`\n${C.red}✓ Workflow '${this.workflowName}' hard reset (history and interactions cleared)${C.reset}`);
+  }
+
+  /**
+   * Enable remote follow mode
+   * @param {string} serverUrl - Base URL of the remote server
+   * @returns {Promise<string>} The remote URL for browser access
+   */
+  async enableRemote(serverUrl) {
+    this.remoteClient = new RemoteClient({
+      serverUrl,
+      workflowName: this.workflowName,
+      onInteractionResponse: (slug, targetKey, response) => {
+        this.handleRemoteInteraction(slug, targetKey, response);
+      },
+      onStatusChange: (status) => {
+        if (status === 'disconnected') {
+          console.log(`${C.yellow}Remote: Connection lost, attempting to reconnect...${C.reset}`);
+        } else if (status === 'connected' && this.remoteEnabled) {
+          console.log(`${C.green}Remote: Reconnected${C.reset}`);
+        }
+      }
+    });
+
+    await this.remoteClient.connect();
+
+    // Send existing history if connected
+    if (this.remoteClient.connected) {
+      const history = this.loadHistory();
+      this.remoteClient.sendSessionInit(history);
+    }
+
+    this.remoteEnabled = true;
+    this.remoteUrl = this.remoteClient.getRemoteUrl();
+
+    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;
+  }
+
+  /**
+   * Disable remote follow mode and disconnect
+   */
+  async disableRemote() {
+    if (this.remoteClient) {
+      await this.remoteClient.disconnect();
+      this.remoteClient = null;
+    }
+
+    this.remoteEnabled = false;
+    this.remoteUrl = null;
+    this.pendingRemoteInteraction = null;
   }
 }
 
 function escapeRegExp(string) {
   return string.replace(/[.*+?^${}()|[\\]/g, '\\$&'); // $& means the whole matched string
-}
+}

package/package.json

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