agent-state-machine 1.0.3 → 1.2.0

package/README.md

@@ -44,10 +44,11 @@ Requirements: Node.js >= 16.
 ```bash
 state-machine --setup <workflow-name>
 state-machine run <workflow-name>
-state-machine resume <workflow-name>
-state-machine status <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>
+state-machine reset <workflow-name> (clears memory/state)
+state-machine reset-hard <workflow-name> (clears everything: history/interactions/memory)
 ```
 
 Workflows live in:
@@ -58,7 +59,7 @@ workflows/<name>/
 ├── package.json       # Sets "type": "module" for this workflow folder
 ├── agents/            # Custom agents (.js/.mjs/.cjs or .md)
 ├── interactions/      # Human-in-the-loop files (auto-created)
-├── state/             # current.json, history.jsonl, generated-prompt.md
+├── state/             # current.json, history.jsonl
 └── steering/          # global.md + config.json
 ```
 
@@ -130,13 +131,13 @@ export default async function() {
 }
 ```
 
-### How “resume” works
+### Resuming workflows
 
-`resume` restarts your workflow from the top. 
+`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 process is interrupted, running `state-machine resume <workflow-name>` will restart the execution. Use the `memory` object to store and skip work manually if needed.
+If the process is interrupted, running `state-machine run <workflow-name>` again will continue execution (assuming your workflow uses `memory` to skip completed steps).
 
 ---
 
@@ -292,10 +293,10 @@ export const config = {
 };
 ```
 
-The runtime writes the fully-built prompt to:
+The runtime captures the fully-built prompt in `state/history.jsonl`, viewable in the browser with live updates via:
 
-```text
-workflows/<name>/state/generated-prompt.md
+```bash
+state-machine follow <workflow-name>
 ```
 
 ---

package/bin/cli.js

@@ -5,6 +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';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -28,12 +29,12 @@ 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 from the beginning
-  state-machine resume <workflow-name>     Resume a paused workflow
+  state-machine run <workflow-name>        Run a workflow (loads existing state)
+  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
-  state-machine reset <workflow-name>      Reset workflow state
-  state-machine reset-hard <workflow-name> Hard reset (clear history/interactions)
+  state-machine history <workflow-name> [limit]  Show execution history logs
+  state-machine reset <workflow-name>      Reset workflow state (clears memory/state)
+  state-machine reset-hard <workflow-name> Hard reset (clears everything: history/interactions/memory)
   state-machine list                       List all workflows
   state-machine help                       Show this help
 
@@ -48,7 +49,7 @@ Workflow Structure:
   ├── package.json       # Sets "type": "module" for this workflow folder
   ├── agents/            # Custom agents (.js/.mjs/.cjs or .md)
   ├── interactions/      # Human-in-the-loop files (auto-created)
-  ├── state/             # current.json, history.jsonl, generated-prompt.md
+  ├── state/             # current.json, history.jsonl
   └── steering/          # global.md + config.json
 `);
 }
@@ -182,7 +183,6 @@ async function main() {
 
   switch (command) {
     case 'run':
-    case 'resume':
       if (!workflowName) {
         console.error('Error: Workflow name required');
         console.error(`Usage: state-machine ${command} <workflow-name>`);
@@ -222,6 +222,23 @@ 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) {
         console.error('Error: Workflow name required');

package/lib/llm.js

@@ -4,6 +4,7 @@
 
 import fs from 'fs';
 import path from 'path';
+import os from 'os';
 import { spawn, execSync } from 'child_process';
 import { createRequire } from 'module';
 
@@ -38,21 +39,6 @@ export function detectAvailableCLIs() {
   return available;
 }
 
-/**
- * Write the generated prompt file
- */
-export function writeGeneratedPrompt(workflowDir, content) {
-  const promptDir = path.join(workflowDir, 'state');
-  const promptFile = path.join(promptDir, 'generated-prompt.md');
-
-  if (!fs.existsSync(promptDir)) {
-    fs.mkdirSync(promptDir, { recursive: true });
-  }
-
-  fs.writeFileSync(promptFile, content);
-  return promptFile;
-}
-
 /**
  * Build the full prompt with steering and context
  */
@@ -96,17 +82,18 @@ export function buildPrompt(context, options) {
 
 /**
  * Execute CLI command and return response
+ * Uses Stdin for supported tools, and temporary files for generic tools.
  */
-async function executeCLI(command, promptFile, options = {}, apiKeys = {}) {
+async function executeCLI(command, promptText, options = {}, apiKeys = {}) {
   return new Promise((resolve, reject) => {
     // Parse command to extract base command and args
-    // Note: naive split; if you need quoted args, consider a shell-args parser.
     const parts = command.split(' ');
     const baseCmd = parts[0];
     const baseArgs = parts.slice(1);
 
     // Build full args
     const args = [...baseArgs];
+    let tempPromptFile = null;
 
     const ensureCodexExec = () => {
       const CODEX_SUBCOMMANDS = new Set([
@@ -140,7 +127,7 @@ async function executeCLI(command, promptFile, options = {}, apiKeys = {}) {
         '-o', '--output-last-message'
       ]);
 
-      // Insert `exec` after any leading global options so codex doesn't start interactive mode.
+      // Insert `exec` after any leading global options
       let i = 0;
       while (i < args.length) {
         const token = args[i];
@@ -150,7 +137,6 @@ async function executeCLI(command, promptFile, options = {}, apiKeys = {}) {
           i += 2;
           continue;
         }
-
         i += 1;
       }
 
@@ -158,41 +144,38 @@ async function executeCLI(command, promptFile, options = {}, apiKeys = {}) {
       if (firstNonOption && CODEX_SUBCOMMANDS.has(firstNonOption)) {
         return;
       }
-
       args.splice(i, 0, 'exec');
     };
 
-    // Different CLIs handle file input differently
+    // Configure args based on the tool
+    const isStandardCLI = (baseCmd === 'claude' || baseCmd === 'gemini' || baseCmd === 'codex');
+
     if (baseCmd === 'claude') {
-      // Claude CLI: use stdin for prompt input
-      args.push('--print'); // Print response only
+      args.push('--print');
       args.push('--permission-mode', 'acceptEdits');
-      // File content will be piped via stdin (no additional args needed)
+      // Input via stdin
     } else if (baseCmd === 'gemini') {
-      // Gemini CLI
       args.push('--approval-mode', 'auto_edit');
-      // No specific args needed for stdin input + one-shot mode
+      // Input via stdin
     } else if (baseCmd === 'codex') {
-      // Codex CLI defaults to an interactive TUI, which requires a TTY.
-      // Force non-interactive mode via `codex exec`, and feed PROMPT via stdin ("-").
       ensureCodexExec();
-
-      // Write only the final message to a file to avoid parsing extra output.
       const lastMessageFile = path.join(
-        path.dirname(promptFile),
+        os.tmpdir(),
         `codex-last-message-${process.pid}-${Date.now()}.txt`
       );
       args.push('--output-last-message', lastMessageFile);
-
-      args.push('-');
+      args.push('-'); // Explicitly read from stdin
     } else {
-      // Generic: try passing file as argument
-      args.push(promptFile);
+      // Generic CLI: Fallback to temp file if not a known stdin consumer
+      // We assume generic tools might expect a filename as an argument.
+      const uniqueId = Date.now().toString(36) + Math.random().toString(36).substr(2, 5);
+      tempPromptFile = path.join(os.tmpdir(), `asm-prompt-${uniqueId}.md`);
+      fs.writeFileSync(tempPromptFile, promptText);
+      args.push(tempPromptFile);
     }
 
     console.log(`  [LLM] Running: ${baseCmd} ${args.join(' ')}`);
 
-    // Prepare environment variables with API keys if provided
     const env = { ...process.env };
     if (apiKeys.gemini) env.GEMINI_API_KEY = apiKeys.gemini;
     if (apiKeys.anthropic) env.ANTHROPIC_API_KEY = apiKeys.anthropic;
@@ -203,10 +186,12 @@ async function executeCLI(command, promptFile, options = {}, apiKeys = {}) {
       env: env
     });
 
-    // Feed stdin for Codex, Claude, and Gemini from the prompt file; otherwise close stdin.
-    if (baseCmd === 'codex' || baseCmd === 'claude' || baseCmd === 'gemini') {
-      fs.createReadStream(promptFile).pipe(child.stdin);
+    // Write prompt to stdin if it's a standard tool or we decided to use stdin
+    if (isStandardCLI) {
+      child.stdin.write(promptText);
+      child.stdin.end();
     } else {
+      // For generic tools using temp files, just close stdin
       child.stdin.end();
     }
 
@@ -222,6 +207,11 @@ async function executeCLI(command, promptFile, options = {}, apiKeys = {}) {
     });
 
     child.on('close', (code) => {
+      // Cleanup temp file if used
+      if (tempPromptFile && fs.existsSync(tempPromptFile)) {
+        try { fs.unlinkSync(tempPromptFile); } catch {}
+      }
+
       if (code === 0) {
         if (baseCmd === 'codex') {
           const outputFlagIndex = args.findIndex(a => a === '--output-last-message' || a === '-o');
@@ -247,6 +237,10 @@ async function executeCLI(command, promptFile, options = {}, apiKeys = {}) {
     });
 
     child.on('error', (err) => {
+      // Cleanup temp file if used
+      if (tempPromptFile && fs.existsSync(tempPromptFile)) {
+        try { fs.unlinkSync(tempPromptFile); } catch {}
+      }
       reject(new Error(`Failed to execute CLI: ${err.message}`));
     });
   });
@@ -259,7 +253,6 @@ async function executeAPI(provider, model, prompt, apiKey, options = {}) {
   console.log(`  [LLM] Calling API: ${provider}/${model}`);
 
   if (provider === 'anthropic') {
-    // Dynamic import to avoid requiring the package if not used
     let Anthropic;
     try {
       Anthropic = require('@anthropic-ai/sdk');
@@ -341,8 +334,9 @@ export async function llm(context, options) {
   const config = context._config || {};
   const models = config.models || {};
   const apiKeys = config.apiKeys || {};
-  const workflowDir = config.workflowDir || process.cwd();
-
+  
+  // No longer needed to write to prompts/ directory here
+  
   // Look up the model command/config
   const modelConfig = models[options.model];
 
@@ -356,13 +350,9 @@ export async function llm(context, options) {
   // Build the full prompt
   const fullPrompt = buildPrompt(context, options);
 
-  // Write to generated-prompt.md
-  const promptFile = writeGeneratedPrompt(workflowDir, fullPrompt);
-  console.log(`  [LLM] Prompt written to: ${promptFile}`);
-
   // Check if it's an API call or CLI
+  let result;
   if (modelConfig.startsWith('api:')) {
-    // Format: api:provider:model
     const parts = modelConfig.split(':');
     const provider = parts[1];
     const model = parts.slice(2).join(':');
@@ -375,11 +365,13 @@ export async function llm(context, options) {
       );
     }
 
-    return executeAPI(provider, model, fullPrompt, apiKey, options);
+    result = await executeAPI(provider, model, fullPrompt, apiKey, options);
+  } else {
+    // CLI execution - pass fullPrompt string directly
+    result = await executeCLI(modelConfig, fullPrompt, options, apiKeys);
   }
 
-  // CLI execution
-  return executeCLI(modelConfig, promptFile, options, apiKeys);
+  return { ...result, fullPrompt };
 }
 
 /**
@@ -446,7 +438,7 @@ export function parseJSON(text) {
     } catch {}
   }
 
-  const arrayMatch = text.match(/\[[\s\S]*\]/);
+  const arrayMatch = text.match(/\{[\[\s\S]*\]\}/);
   if (arrayMatch) {
     try {
       return JSON.parse(arrayMatch[0]);
@@ -469,4 +461,4 @@ export async function llmJSON(context, options) {
     ...response,
     data: parseJSON(response.text)
   };
-}
+}

package/lib/runtime/agent.js

@@ -34,11 +34,18 @@ export async function agent(name, params = {}) {
   try {
     const result = await executeAgent(runtime, name, params);
 
+    let prompt = undefined;
+    if (result && typeof result === 'object' && result._debug_prompt) {
+      prompt = result._debug_prompt;
+      delete result._debug_prompt;
+    }
+
     console.log(`  [Agent: ${name}] Completed`);
     runtime.prependHistory({
       event: 'AGENT_COMPLETED',
       agent: name,
-      output: result
+      output: result,
+      prompt: prompt
     });
 
     return result;
@@ -243,11 +250,11 @@ async function executeMDAgent(runtime, agentPath, name, params) {
     });
 
     // Return the user's response as the agent result
-    return { [outputKey]: userResponse };
+    return { [outputKey]: userResponse, _debug_prompt: response.fullPrompt };
   }
 
   // Return result object
-  return { [outputKey]: output };
+  return { [outputKey]: output, _debug_prompt: response.fullPrompt };
 }
 
 /**

package/lib/runtime/runtime.js

@@ -38,7 +38,6 @@ export class WorkflowRuntime {
     this.agentsDir = path.join(workflowDir, 'agents');
     this.interactionsDir = path.join(workflowDir, 'interactions');
     this.steeringDir = path.join(workflowDir, 'steering');
-    this.generatedPromptFile = path.join(this.stateDir, 'generated-prompt.md');
     this.historyFile = path.join(this.stateDir, 'history.jsonl');
     this.stateFile = path.join(this.stateDir, 'current.json');
 
@@ -361,11 +360,6 @@ export class WorkflowRuntime {
       fs.unlinkSync(this.historyFile);
     }
 
-    // 2. Delete generated-prompt.md file
-    if (fs.existsSync(this.generatedPromptFile)) {
-      fs.unlinkSync(this.generatedPromptFile);
-    }
-
     // 3. Clear interactions directory
     if (fs.existsSync(this.interactionsDir)) {
       fs.rmSync(this.interactionsDir, { recursive: true, force: true });

package/lib/setup.js

@@ -173,7 +173,7 @@ Once you have it create a yoda-greeting.md file in root dir with the greeting.
 You are a fast, direct worker. Do NOT investigate the codebase or read files unless strictly necessary. Perform the requested action immediately using the provided context. Avoid "thinking" steps or creating plans if the task is simple.
 `;
 
-const yodaNameCollectorAgent = `---
+  const yodaNameCollectorAgent = `---
 model: low
 output: name
 ---
@@ -288,22 +288,17 @@ ${workflowName}/
 ├── package.json     # Sets "type": "module" for this workflow folder
 ├── agents/          # Custom agents (.js/.mjs/.cjs or .md)
 ├── interactions/    # Human-in-the-loop inputs (created at runtime)
-├── state/           # Runtime state (current.json, history.jsonl)
+├── state/           # Runtime state (current.json, history.jsonl, prompts/)
 └── steering/        # Steering configuration
 \\\`\\\`\\\`
 
 ## Usage
 
-Run the workflow:
+Run the workflow (or resume if interrupted):
 \\\`\\\`\\\`bash
 state-machine run ${workflowName}
 \\\`\\\`\\\`
 
-Resume a paused workflow:
-\\\`\\\`\\\`bash
-state-machine resume ${workflowName}
-\\\`\\\`\\\`
-
 Check status:
 \\\`\\\`\\\`bash
 state-machine status ${workflowName}
@@ -314,11 +309,21 @@ View history:
 state-machine history ${workflowName}
 \\\`\\\`\\\`
 
-Reset state:
+View trace logs in browser with live updates:
+\\\`\\\`\\\`bash
+state-machine follow ${workflowName}
+\\\`\\\`\\\`
+
+Reset state (clears memory/state):
 \\\`\\\`\\\`bash
 state-machine reset ${workflowName}
 \\\`\\\`\\\`
 
+Hard reset (clears everything: history/interactions/memory):
+\\\`\\\`\\\`bash
+state-machine reset-hard ${workflowName}
+\\\`\\\`\\\`
+
 ## Writing Workflows
 
 Edit \`workflow.js\` - write normal async JavaScript:

package/lib/ui/index.html

@@ -0,0 +1,324 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Workflow Prompts Viewer</title>
+    <script src="https://cdn.tailwindcss.com"></script>
+    <script>
+        tailwind.config = {
+            darkMode: 'class',
+        }
+    </script>
+    <script src="https://unpkg.com/react@18/umd/react.development.js" crossorigin></script>
+    <script src="https://unpkg.com/react-dom@18/umd/react-dom.development.js" crossorigin></script>
+    <script src="https://unpkg.com/@babel/standalone/babel.min.js"></script>
+    <style>
+        .markdown-body { white-space: pre-wrap; font-family: monospace; }
+        /* Scrollbar styles for dark mode */
+        .dark ::-webkit-scrollbar { width: 10px; height: 10px; }
+        .dark ::-webkit-scrollbar-track { background: #000000; }
+        .dark ::-webkit-scrollbar-thumb { background: #27272a; border-radius: 5px; }
+        .dark ::-webkit-scrollbar-thumb:hover { background: #3f3f46; }
+    </style>
+</head>
+<body>
+    <div id="root"></div>
+
+    <script type="text/babel">
+        const { useState, useEffect } = React;
+
+        // Icons
+        const SunIcon = () => (
+            <svg xmlns="http://www.w3.org/2000/svg" className="h-5 w-5" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M12 3v1m0 16v1m9-9h-1M4 12H3m15.364 6.364l-.707-.707M6.343 6.343l-.707-.707m12.728 0l-.707.707M6.343 17.657l-.707.707M16 12a4 4 0 11-8 0 4 4 0 018 0z" />
+            </svg>
+        );
+
+        const MoonIcon = () => (
+            <svg xmlns="http://www.w3.org/2000/svg" className="h-5 w-5" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M20.354 15.354A9 9 0 018.646 3.646 9.003 9.003 0 0012 21a9.003 9.003 0 008.354-5.646z" />
+            </svg>
+        );
+
+        const CopyIcon = () => (
+            <svg xmlns="http://www.w3.org/2000/svg" className="h-3 w-3" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M8 16H6a2 2 0 01-2-2V6a2 2 0 012-2h8a2 2 0 012 2v2m-6 12h8a2 2 0 002-2v-8a2 2 0 00-2-2h-8a2 2 0 00-2 2v8a2 2 0 002 2z" />
+            </svg>
+        );
+
+        const CheckIcon = () => (
+            <svg xmlns="http://www.w3.org/2000/svg" className="h-3 w-3" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M5 13l4 4L19 7" />
+            </svg>
+        );
+
+        function CopyButton({ text, className }) {
+            const [copied, setCopied] = useState(false);
+
+            const handleCopy = () => {
+                const content = typeof text === 'object' ? JSON.stringify(text, null, 2) : text;
+                navigator.clipboard.writeText(content);
+                setCopied(true);
+                setTimeout(() => setCopied(false), 2000);
+            };
+
+            return (
+                <button 
+                    onClick={handleCopy} 
+                    className={`flex items-center space-x-1 text-[9px] uppercase tracking-wider transition-colors hover:text-blue-500 focus:outline-none ${className}`}
+                    title="Copy to clipboard"
+                >
+                    {copied ? <CheckIcon /> : <CopyIcon />}
+                    <span>{copied ? 'Copied' : 'Copy'}</span>
+                </button>
+            );
+        }
+
+        function App() {
+            const [history, setHistory] = useState([]);
+            const [loading, setLoading] = useState(true);
+            const [error, setError] = useState(null);
+            const [workflowName, setWorkflowName] = useState('');
+            const [theme, setTheme] = useState('dark');
+            const [sortOrder, setSortOrder] = useState('newest'); // 'newest' | 'oldest'
+
+            useEffect(() => {
+                const fetchData = () => {
+                    fetch('/api/history')
+                        .then(res => res.json())
+                        .then(data => {
+                            setHistory(data.entries);
+                            setWorkflowName(data.workflowName);
+                            setLoading(false);
+                        })
+                        .catch(err => {
+                            setError(err.message);
+                            setLoading(false);
+                        });
+                };
+
+                // Initial fetch
+                fetchData();
+
+                // Setup SSE
+                const eventSource = new EventSource('/api/events');
+                eventSource.onmessage = (event) => {
+                    if (event.data === 'update') {
+                        fetchData();
+                    }
+                };
+
+                return () => {
+                    eventSource.close();
+                };
+            }, []);
+
+            const toggleTheme = () => {
+                setTheme(prev => prev === 'dark' ? 'light' : 'dark');
+            };
+
+            const toggleSort = () => {
+                setSortOrder(prev => prev === 'newest' ? 'oldest' : 'newest');
+            };
+
+            if (loading) return (
+                <div className={theme}>
+                    <div className="flex items-center justify-center h-screen bg-gray-50 dark:bg-black text-gray-500 dark:text-zinc-500">
+                        Loading history...
+                    </div>
+                </div>
+            );
+            
+            if (error) return (
+                <div className={theme}>
+                    <div className="flex items-center justify-center h-screen bg-gray-50 dark:bg-black text-red-500">
+                        Error: {error}
+                    </div>
+                </div>
+            );
+
+            // Filter for events we want to display
+            let visibleEvents = history.filter(item => 
+                [
+                    'WORKFLOW_STARTED', 'WORKFLOW_COMPLETED', 'WORKFLOW_FAILED', 'WORKFLOW_RESET',
+                    'AGENT_STARTED', 'AGENT_COMPLETED', 'AGENT_FAILED',
+                    'INTERACTION_REQUESTED', 'INTERACTION_RESOLVED'
+                ].includes(item.event)
+            );
+
+            // Apply Sort
+            // History from API is "Newest First" (index 0 is latest)
+            if (sortOrder === 'oldest') {
+                visibleEvents = [...visibleEvents].reverse();
+            }
+
+            const formatTime = (ts) => new Date(ts).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit', second: '2-digit' });
+
+            return (
+                <div className={theme}>
+                    <div className="min-h-screen bg-gray-50 dark:bg-black transition-colors duration-200">
+                        <div className="max-w-5xl mx-auto min-h-screen flex flex-col">
+                            
+                            {/* Sticky Header */}
+                            <header className="sticky top-0 z-50 py-4 px-6 bg-gray-50/90 dark:bg-black/90 backdrop-blur-md border-b border-gray-200 dark:border-zinc-800 flex items-center justify-between mb-8 transition-colors">
+                                <div className="flex-1">
+                                    <h1 className="text-xl font-bold text-gray-800 dark:text-zinc-100 transition-colors uppercase tracking-tight">{workflowName}</h1>
+                                    <p className="text-gray-500 dark:text-zinc-500 text-xs mt-0.5">Runtime History & Prompt Logs</p>
+                                </div>
+                                <div className="flex items-center space-x-2">
+                                    <button 
+                                        onClick={toggleSort}
+                                        className="p-2 rounded-full bg-gray-200 dark:bg-zinc-900 text-gray-800 dark:text-zinc-200 hover:bg-gray-300 dark:hover:bg-zinc-800 transition-colors"
+                                        title={sortOrder === 'newest' ? "Sort: Newest First" : "Sort: Oldest First"}
+                                    >
+                                        {sortOrder === 'newest' ? 
+                                            <svg xmlns="http://www.w3.org/2000/svg" className="h-5 w-5" fill="none" viewBox="0 0 24 24" stroke="currentColor"><path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M3 4h13M3 8h9m-9 4h6m4 0l4-4m0 0l4 4m-4-4v12" /></svg> 
+                                            : 
+                                            <svg xmlns="http://www.w3.org/2000/svg" className="h-5 w-5" fill="none" viewBox="0 0 24 24" stroke="currentColor"><path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M3 4h13M3 8h9m-9 4h6m4 0l4-4m0 0l4 4m-4-4v12" transform="scale(1, -1) translate(0, -24)" /></svg>
+                                        }
+                                    </button>
+                                    <button 
+                                        onClick={toggleTheme}
+                                        className="p-2 rounded-full bg-gray-200 dark:bg-zinc-900 text-gray-800 dark:text-zinc-200 hover:bg-gray-300 dark:hover:bg-zinc-800 transition-colors"
+                                        title="Toggle Theme"
+                                    >
+                                        {theme === 'dark' ? <SunIcon /> : <MoonIcon />}
+                                    </button>
+                                </div>
+                            </header>
+
+                            {/* Content */}
+                            <div className="flex-1 space-y-8 px-6">
+                                {visibleEvents.length === 0 && (
+                                    <div className="text-center text-gray-400 py-10">No execution history found.</div>
+                                )}
+
+                                {visibleEvents.map((item, idx) => {
+                                    // 1. Lifecycle Events
+                                    if (item.event.startsWith('WORKFLOW_')) {
+                                        const colorMap = {
+                                            'WORKFLOW_STARTED': 'text-green-500 dark:text-green-400',
+                                            'WORKFLOW_COMPLETED': 'text-blue-500 dark:text-blue-400',
+                                            'WORKFLOW_FAILED': 'text-red-500 dark:text-red-400',
+                                            'WORKFLOW_RESET': 'text-yellow-500 dark:text-yellow-400'
+                                        };
+                                        return (
+                                            <div key={idx} className="flex flex-col items-center py-4">
+                                                <div className="flex items-center space-x-3 text-[10px] uppercase tracking-[0.2em] font-bold text-zinc-400 dark:text-zinc-600">
+                                                    <div className="h-px w-8 bg-zinc-200 dark:bg-zinc-800"></div>
+                                                    <span className={colorMap[item.event]}>{item.event.replace('_', ' ')}</span>
+                                                    <span>{formatTime(item.timestamp)}</span>
+                                                    <div className="h-px w-8 bg-zinc-200 dark:bg-zinc-800"></div>
+                                                </div>
+                                                {item.error && <div className="mt-2 text-red-500 text-xs font-mono">{item.error}</div>}
+                                            </div>
+                                        );
+                                    }
+
+                                    // 2. Agent Started
+                                    if (item.event === 'AGENT_STARTED') {
+                                        return (
+                                            <div key={idx} className="flex justify-start">
+                                                <div className="text-[10px] text-zinc-400 dark:text-zinc-600 uppercase tracking-widest flex items-center space-x-2">
+                                                    <span className="w-1.5 h-1.5 rounded-full bg-blue-500/50 animate-pulse"></span>
+                                                    <span>Agent <span className="text-zinc-600 dark:text-zinc-400">{item.agent}</span> started</span>
+                                                    <span>&bull;</span>
+                                                    <span>{formatTime(item.timestamp)}</span>
+                                                </div>
+                                            </div>
+                                        );
+                                    }
+
+                                    // 3. Agent Failed
+                                    if (item.event === 'AGENT_FAILED') {
+                                        return (
+                                            <div key={idx} className="flex justify-center">
+                                                <div className="bg-red-50 dark:bg-red-950/20 border border-red-200 dark:border-red-900/50 rounded-lg px-4 py-2 text-red-600 dark:text-red-400 text-xs font-mono w-full max-w-2xl">
+                                                    <div className="font-bold mb-1 underline">AGENT FAILED: {item.agent}</div>
+                                                    <div>{item.error}</div>
+                                                </div>
+                                            </div>
+                                        );
+                                    }
+
+                                    // 4. Interaction Requested
+                                    if (item.event === 'INTERACTION_REQUESTED') {
+                                        return (
+                                            <div key={idx} className="flex justify-center">
+                                                <div className="bg-zinc-100 dark:bg-zinc-900 border border-zinc-200 dark:border-zinc-800 border-dashed rounded-lg px-6 py-4 text-center max-w-md w-full">
+                                                    <div className="text-[10px] text-zinc-400 dark:text-zinc-600 uppercase font-bold tracking-widest mb-1">Human Intervention Needed</div>
+                                                    <div className="text-xs text-zinc-600 dark:text-zinc-400 italic">Waiting for response to "{item.slug}"...</div>
+                                                </div>
+                                            </div>
+                                        );
+                                    }
+
+                                    // 5. Agent Completed / Interaction Resolved (The Bubbles)
+                                    if (item.event === 'AGENT_COMPLETED' || item.event === 'INTERACTION_RESOLVED') {
+                                        return (
+                                            <div key={idx} className="flex flex-col space-y-4">
+                                                {/* Header Line */}
+                                                <div className="flex items-center justify-center space-x-2 text-[10px] text-zinc-400 dark:text-zinc-600 uppercase tracking-widest">
+                                                    <span className="font-black text-zinc-500 dark:text-zinc-400">{item.agent || item.slug}</span>
+                                                    <span>&bull;</span>
+                                                    <span>COMPLETED</span>
+                                                    <span>&bull;</span>
+                                                    <span>{formatTime(item.timestamp)}</span>
+                                                </div>
+
+                                                {/* Output (Response) - NOW ON TOP */}
+                                                {(item.output || item.result) && (
+                                                    <div className="flex justify-end w-full group">
+                                                        <div className="max-w-[85%] bg-blue-50 dark:bg-blue-950/20 border border-blue-100 dark:border-blue-900/40 rounded-2xl rounded-tr-none shadow-sm p-6 transition-all hover:border-blue-200 dark:hover:border-blue-800 relative">
+                                                            <div className="flex justify-between items-center mb-3">
+                                                                <div className="text-[9px] font-black text-blue-300 dark:text-blue-800/60 uppercase tracking-[0.2em] text-right w-full">Output / Response</div>
+                                                                <div className="absolute top-4 right-4 opacity-0 group-hover:opacity-100 transition-opacity">
+                                                                    <CopyButton text={item.output || item.result} className="text-blue-400 hover:text-blue-600 dark:text-blue-600 dark:hover:text-blue-400" />
+                                                                </div>
+                                                            </div>
+                                                            <div className="markdown-body text-gray-800 dark:text-zinc-200 text-sm overflow-x-auto leading-relaxed">
+                                                                {typeof item.output === 'object' ? JSON.stringify(item.output, null, 2) : (item.output || item.result)}
+                                                            </div>
+                                                        </div>
+                                                    </div>
+                                                )}
+
+                                                {/* Prompt (Input) - NOW ON BOTTOM */}
+                                                {item.prompt && (
+                                                    <div className="flex justify-start w-full group">
+                                                        <div className="max-w-[85%] bg-white dark:bg-zinc-900 border border-gray-200 dark:border-zinc-800 rounded-2xl rounded-tl-none shadow-sm p-6 transition-all hover:border-zinc-300 dark:hover:border-zinc-700 relative">
+                                                            <div className="flex justify-between items-center mb-3">
+                                                                <div className="text-[9px] font-black text-zinc-300 dark:text-zinc-700 uppercase tracking-[0.2em]">Prompt / Input</div>
+                                                                <div className="absolute top-4 right-4 opacity-0 group-hover:opacity-100 transition-opacity">
+                                                                    <CopyButton text={item.prompt} className="text-gray-400 hover:text-gray-600 dark:text-zinc-600 dark:hover:text-zinc-400" />
+                                                                </div>
+                                                            </div>
+                                                            <div className="markdown-body text-gray-800 dark:text-zinc-300 text-sm overflow-x-auto leading-relaxed">
+                                                                {item.prompt}
+                                                            </div>
+                                                        </div>
+                                                    </div>
+                                                )}
+                                            </div>
+                                        );
+                                    }
+
+                                    return null;
+                                })}
+                            </div>
+
+                            <footer className="mt-20 mb-8 text-center text-zinc-400 dark:text-zinc-800 text-[10px] uppercase tracking-[0.3em] transition-colors">
+                                Agent State Machine &bull; Debug Terminal
+                            </footer>
+                        </div>
+                    </div>
+                </div>
+            );
+        }
+
+        const root = ReactDOM.createRoot(document.getElementById('root'));
+        root.render(<App />);
+    </script>
+</body>
+</html>

package/lib/ui/server.js

@@ -0,0 +1,150 @@
+/**
+ * File: /lib/ui/server.js
+ */
+
+import http from 'http';
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+export function startServer(workflowDir, initialPort = 3000) {
+  const clients = new Set();
+  const stateDir = path.join(workflowDir, 'state');
+
+  // Watch for changes in the state directory
+  // We debounce slightly to avoid sending multiple events for a single write burst
+  let debounceTimer;
+  const broadcastUpdate = () => {
+    if (debounceTimer) clearTimeout(debounceTimer);
+    debounceTimer = setTimeout(() => {
+      const msg = 'data: update\n\n';
+      for (const client of clients) {
+        try {
+          client.write(msg);
+        } catch (e) {
+          clients.delete(client);
+        }
+      }
+    }, 100);
+  };
+
+  try {
+    if (fs.existsSync(stateDir)) {
+      fs.watch(stateDir, (eventType, filename) => {
+        if (filename && (filename === 'history.jsonl' || filename.startsWith('history'))) {
+          broadcastUpdate();
+        }
+      });
+    } else {
+      console.warn('Warning: State directory does not exist yet. Live updates might not work until it is created.');
+    }
+  } catch (err) {
+    console.warn('Warning: Failed to setup file watcher:', err.message);
+  }
+
+  // Request Handler
+  const requestHandler = (req, res) => {
+    // Serve the main HTML page
+    if (req.url === '/' || req.url === '/index.html') {
+      const htmlPath = path.join(__dirname, 'index.html');
+      fs.readFile(htmlPath, (err, content) => {
+        if (err) {
+          res.writeHead(500);
+          res.end('Error loading UI');
+          return;
+        }
+        res.writeHead(200, { 'Content-Type': 'text/html' });
+        res.end(content);
+      });
+      return;
+    }
+
+    // Server-Sent Events endpoint
+    if (req.url === '/api/events') {
+      res.writeHead(200, {
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache',
+        'Connection': 'keep-alive',
+      });
+      res.write('retry: 10000\n\n');
+
+      clients.add(res);
+
+      req.on('close', () => {
+        clients.delete(res);
+      });
+      return;
+    }
+
+    // Serve API
+    if (req.url === '/api/history') {
+      const historyFile = path.join(stateDir, 'history.jsonl');
+      
+      if (!fs.existsSync(historyFile)) {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+          workflowName: path.basename(workflowDir),
+          entries: [] 
+        }));
+        return;
+      }
+
+      try {
+        const fileContent = fs.readFileSync(historyFile, 'utf-8');
+        const lines = fileContent.trim().split('\n');
+        const entries = lines
+          .map(line => {
+            try { return JSON.parse(line); } catch { return null; }
+          })
+          .filter(Boolean);
+
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+          workflowName: path.basename(workflowDir),
+          entries
+        }));
+      } catch (err) {
+        res.writeHead(500, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: err.message }));
+      }
+      return;
+    }
+
+    // 404
+    res.writeHead(404);
+    res.end('Not found');
+  };
+
+  // Port hunting logic
+  let port = initialPort;
+  const maxPort = initialPort + 100; // Try up to 100 ports
+
+  const attemptServer = () => {
+    const server = http.createServer(requestHandler);
+
+    server.on('error', (e) => {
+      if (e.code === 'EADDRINUSE') {
+        if (port < maxPort) {
+          console.log(`Port ${port} is in use, trying ${port + 1}...`);
+          port++;
+          attemptServer();
+        } else {
+          console.error(`Error: Could not find an open port between ${initialPort} and ${maxPort}.`);
+        }
+      } else {
+        console.error('Server error:', e);
+      }
+    });
+
+    server.listen(port, () => {
+      console.log(`\n> Follow UI running at http://localhost:${port}`);
+      console.log(`> Viewing history for: ${workflowDir}`);
+      console.log(`> Press Ctrl+C to stop`);
+    });
+  };
+
+  attemptServer();
+}

package/package.json

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