agent-state-machine 1.0.2 → 1.1.0

package/README.md

@@ -11,14 +11,28 @@ You write normal `async/await` code. The runtime handles:
 
 ## Install
 
+You need to install the package **globally** to get the CLI, and **locally** in your project so your workflow can import the library.
+
+### Global CLI
+Provides the `state-machine` command.
+
 ```bash
-npm i agent-state-machine
+# npm
+npm i -g agent-state-machine
+
+# pnpm
+pnpm add -g agent-state-machine
 ```
 
-Global CLI:
+### Local Library
+Required so your `workflow.js` can `import { agent, memory } from 'agent-state-machine'`.
 
 ```bash
-npm i -g agent-state-machine
+# npm
+npm i agent-state-machine
+
+# pnpm (for monorepos/turbo, install in root)
+pnpm add agent-state-machine -w
 ```
 
 Requirements: Node.js >= 16.
@@ -33,6 +47,7 @@ state-machine run <workflow-name>
 state-machine resume <workflow-name>
 state-machine status <workflow-name>
 state-machine history <workflow-name> [limit]
+state-machine trace-logs <workflow-name>
 state-machine reset <workflow-name>
 ```
 
@@ -44,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
 ```
 
@@ -278,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 via:
 
-```text
-workflows/<name>/state/generated-prompt.md
+```bash
+state-machine trace-logs <workflow-name>
 ```
 
 ---

package/bin/cli.js

@@ -2,16 +2,30 @@
 
 import path from 'path';
 import fs from 'fs';
-import { pathToFileURL } from 'url';
+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);
 
 const args = process.argv.slice(2);
 const command = args[0];
 
+function getVersion() {
+  try {
+    const pkgPath = path.join(__dirname, '../package.json');
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+    return pkg.version;
+  } catch {
+    return 'unknown';
+  }
+}
+
 function printHelp() {
   console.log(`
-Agent State Machine CLI (Native JS Workflows Only)
+Agent State Machine CLI (Native JS Workflows Only) v${getVersion()}
 
 Usage:
   state-machine --setup <workflow-name>    Create a new workflow project
@@ -19,6 +33,7 @@ Usage:
   state-machine resume <workflow-name>     Resume a paused workflow
   state-machine status [workflow-name]     Show current state (or list all)
   state-machine history <workflow-name> [limit]  Show execution history
+  state-machine trace-logs <workflow-name>   View prompt trace history in browser
   state-machine reset <workflow-name>      Reset workflow state
   state-machine reset-hard <workflow-name> Hard reset (clear history/interactions)
   state-machine list                       List all workflows
@@ -27,6 +42,7 @@ Usage:
 Options:
   --setup, -s     Initialize a new workflow with directory structure
   --help, -h      Show help
+  --version, -v   Show version
 
 Workflow Structure:
   workflows/<name>/
@@ -34,7 +50,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
 `);
 }
@@ -143,6 +159,11 @@ async function runOrResume(workflowName) {
 }
 
 async function main() {
+  if (command === '--version' || command === '-v') {
+    console.log(getVersion());
+    process.exit(0);
+  }
+
   if (!command || command === 'help' || command === '--help' || command === '-h') {
     printHelp();
     process.exit(0);
@@ -203,6 +224,23 @@ async function main() {
       }
       break;
 
+    case 'trace-logs':
+      if (!workflowName) {
+        console.error('Error: Workflow name required');
+        console.error('Usage: state-machine trace-logs <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

@@ -288,7 +288,7 @@ ${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
 \\\`\\\`\\\`
 
@@ -314,6 +314,11 @@ View history:
 state-machine history ${workflowName}
 \\\`\\\`\\\`
 
+View trace logs in browser:
+\\\`\\\`\\\`bash
+state-machine trace-logs ${workflowName}
+\\\`\\\`\\\`
+
 Reset state:
 \\\`\\\`\\\`bash
 state-machine reset ${workflowName}

package/lib/ui/index.html

@@ -0,0 +1,294 @@
+<!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 SortDescIcon = () => (
+            <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>
+        );
+
+        const SortAscIcon = () => (
+            <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 4h5m4 0l4-4m0 0l4 4m-4-4v12" transform="scale(1, -1) translate(0, -24)" />
+                {/* Simple Down Arrow for Newest Top */}
+                <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M19 14l-7 7m0 0l-7-7m7 7V3" />
+            </svg>
+        );
+
+        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">
+                                                            <div className="text-[9px] font-black text-blue-300 dark:text-blue-800/60 mb-3 uppercase tracking-[0.2em] text-right">Output / Response</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">
+                                                            <div className="text-[9px] font-black text-zinc-300 dark:text-zinc-700 mb-3 uppercase tracking-[0.2em]">Prompt / Input</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,125 @@
+/**
+ * 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, port = 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);
+  }
+
+  const server = http.createServer((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');
+  });
+
+  server.listen(port, () => {
+    console.log(`\n> Trace Logs running at http://localhost:${port}`);
+    console.log(`> Viewing history for: ${workflowDir}`);
+    console.log(`> Press Ctrl+C to stop`);
+  });
+}

package/package.json

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