agent-state-machine 1.1.0 → 1.3.0

package/README.md

@@ -44,11 +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 trace-logs <workflow-name>
-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:
@@ -120,24 +120,29 @@ export default async function() {
   // await agent('yoda-greeter', userInfo);
 
   // Example: Parallel execution
-  // const [a, b] = await parallel([
-  //   agent('example', { which: 'a' }),
-  //   agent('example', { which: 'b' })
+  // const [a, b, c] = await parallel([
+  //   agent('yoda-greeter', { name: 'the names augustus but friends call me gus' }),
+  //   agent('yoda-greeter', { name: 'uriah' }),
+  //   agent('yoda-greeter', { name: 'lucas' })
   // ]);
 
+  // console.log('a: ' + JSON.stringify(a))
+  // console.log('b: ' + JSON.stringify(b))
+  // console.log('c: ' + JSON.stringify(c))
+
   notify(['project-builder', userInfo.name || userInfo + ' has been greeted!']);
 
   console.log('Workflow completed!');
 }
 ```
 
-### 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).
 
 ---
 
@@ -293,10 +298,10 @@ export const config = {
 };
 ```
 
-The runtime captures the fully-built prompt in `state/history.jsonl`, viewable via:
+The runtime captures the fully-built prompt in `state/history.jsonl`, viewable in the browser with live updates via:
 
 ```bash
-state-machine trace-logs <workflow-name>
+state-machine follow <workflow-name>
 ```
 
 ---

package/bin/cli.js

@@ -29,13 +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 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 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
 
@@ -184,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>`);
@@ -224,10 +222,10 @@ async function main() {
       }
       break;
 
-    case 'trace-logs':
+    case 'follow':
       if (!workflowName) {
         console.error('Error: Workflow name required');
-        console.error('Usage: state-machine trace-logs <workflow-name>');
+        console.error('Usage: state-machine follow <workflow-name>');
         process.exit(1);
       }
       {

package/lib/runtime/agent.js

@@ -356,7 +356,8 @@ Enter your response below:
   runtime.prependHistory({
     event: 'INTERACTION_REQUESTED',
     slug,
-    targetKey
+    targetKey,
+    question: content
   });
 
   // Block and wait for user input (instead of throwing)

package/lib/runtime/prompt.js

@@ -71,7 +71,8 @@ Enter your response below:
     event: 'INTERACTION_REQUESTED',
     slug,
     targetKey: memoryKey,
-    file: interactionFile
+    file: interactionFile,
+    question
   });
 
   // Block and wait for user input (instead of throwing)

package/lib/setup.js

@@ -99,11 +99,16 @@ export default async function() {
   // await agent('yoda-greeter', userInfo);
 
   // Example: Parallel execution
-  // const [a, b] = await parallel([
-  //   agent('example', { which: 'a' }),
-  //   agent('example', { which: 'b' })
+  // const [a, b, c] = await parallel([
+  //   agent('yoda-greeter', { name: 'the names augustus but friends call me gus' }),
+  //   agent('yoda-greeter', { name: 'uriah' }),
+  //   agent('yoda-greeter', { name: 'lucas' })
   // ]);
 
+  // console.log('a: ' + JSON.stringify(a))
+  // console.log('b: ' + JSON.stringify(b))
+  // console.log('c: ' + JSON.stringify(c))
+
   notify(['${workflowName}', userInfo.name || userInfo + ' has been greeted!']);
 
   console.log('Workflow completed!');
@@ -173,7 +178,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
 ---
@@ -294,16 +299,11 @@ ${workflowName}/
 
 ## 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,16 +314,21 @@ View history:
 state-machine history ${workflowName}
 \\\`\\\`\\\`
 
-View trace logs in browser:
+View trace logs in browser with live updates:
 \\\`\\\`\\\`bash
-state-machine trace-logs ${workflowName}
+state-machine follow ${workflowName}
 \\\`\\\`\\\`
 
-Reset state:
+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:
@@ -354,11 +359,16 @@ export default async function() {
   // await agent('yoda-greeter', userInfo);
 
   // Example: Parallel execution
-  // const [a, b] = await parallel([
-  //   agent('example', { which: 'a' }),
-  //   agent('example', { which: 'b' })
+  // const [a, b, c] = await parallel([
+  //   agent('yoda-greeter', { name: 'the names augustus but friends call me gus' }),
+  //   agent('yoda-greeter', { name: 'uriah' }),
+  //   agent('yoda-greeter', { name: 'lucas' })
   // ]);
 
+  // console.log('a: ' + JSON.stringify(a))
+  // console.log('b: ' + JSON.stringify(b))
+  // console.log('c: ' + JSON.stringify(c))
+
   notify(['project-builder', userInfo.name || userInfo + ' has been greeted!']);
 
   console.log('Workflow completed!');

package/lib/ui/index.html

@@ -41,20 +41,40 @@
             </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" />
+        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 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" />
+        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);
@@ -118,14 +138,9 @@
                 </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)
-            );
+            // Filter for events we want to display - NOW INCLUDES EVERYTHING
+            // We only filter out nulls or malformed entries if any
+            let visibleEvents = history;
 
             // Apply Sort
             // History from API is "Newest First" (index 0 is latest)
@@ -222,19 +237,40 @@
                                         );
                                     }
 
-                                    // 4. Interaction Requested
-                                    if (item.event === 'INTERACTION_REQUESTED') {
+                                    // 4. Interaction / Prompt Requested
+                                    if (item.event === 'INTERACTION_REQUESTED' || item.event === 'PROMPT_REQUESTED') {
+                                        const isPrompt = item.event === 'PROMPT_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 className="text-[10px] text-zinc-400 dark:text-zinc-600 uppercase font-bold tracking-widest mb-1">
+                                                        {isPrompt ? 'User Input Requested' : 'Human Intervention Needed'}
+                                                    </div>
+                                                    <div className="text-xs text-zinc-600 dark:text-zinc-400 italic">
+                                                        {item.question ? `"${item.question}"` : `Waiting for response to "${item.slug}"...`}
+                                                    </div>
                                                 </div>
                                             </div>
                                         );
                                     }
 
-                                    // 5. Agent Completed / Interaction Resolved (The Bubbles)
+                                    // 5. Prompt Answered
+                                    if (item.event === 'PROMPT_ANSWERED') {
+                                        return (
+                                            <div key={idx} className="flex justify-center">
+                                                <div className="bg-green-50 dark:bg-green-950/20 border border-green-200 dark:border-green-900/50 rounded-lg px-4 py-2 text-center max-w-md w-full">
+                                                    <div className="text-[10px] text-green-600 dark:text-green-400 uppercase font-bold tracking-widest mb-1">
+                                                        User Answered
+                                                    </div>
+                                                    <div className="text-xs text-green-700 dark:text-green-300 italic font-medium">
+                                                        "{item.answer}"
+                                                    </div>
+                                                </div>
+                                            </div>
+                                        );
+                                    }
+
+                                    // 6. 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">
@@ -250,8 +286,13 @@
                                                 {/* 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="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>
@@ -262,8 +303,13 @@
                                                 {/* 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="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>
@@ -274,7 +320,26 @@
                                         );
                                     }
 
-                                    return null;
+                                    // 7. CATCH-ALL for Unknown Events
+                                    // If we made it here, it's an event we didn't explicitly handle.
+                                    // Render it generically.
+                                    return (
+                                        <div key={idx} className="flex justify-center px-4">
+                                            <div className="bg-gray-100 dark:bg-zinc-900/50 border border-gray-200 dark:border-zinc-800 rounded-lg px-4 py-3 text-xs w-full max-w-2xl font-mono overflow-x-auto">
+                                                <div className="text-[9px] text-gray-400 dark:text-zinc-600 uppercase tracking-widest mb-1 flex justify-between">
+                                                    <span>{item.event}</span>
+                                                    <span>{formatTime(item.timestamp)}</span>
+                                                </div>
+                                                <div className="text-gray-600 dark:text-zinc-400 whitespace-pre-wrap">
+                                                    {JSON.stringify(item, (key, value) => {
+                                                        // Exclude redundant keys to keep it clean
+                                                        if (key === 'event' || key === 'timestamp') return undefined;
+                                                        return value;
+                                                    }, 2).replace(/^{|}$/g, '').trim()}
+                                                </div>
+                                            </div>
+                                        </div>
+                                    );
                                 })}
                             </div>
 
@@ -291,4 +356,4 @@
         root.render(<App />);
     </script>
 </body>
-</html>
+</html>

package/lib/ui/server.js

@@ -10,7 +10,7 @@ import { fileURLToPath } from 'url';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
-export function startServer(workflowDir, port = 3000) {
+export function startServer(workflowDir, initialPort = 3000) {
   const clients = new Set();
   const stateDir = path.join(workflowDir, 'state');
 
@@ -45,7 +45,8 @@ export function startServer(workflowDir, port = 3000) {
     console.warn('Warning: Failed to setup file watcher:', err.message);
   }
 
-  const server = http.createServer((req, res) => {
+  // 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');
@@ -115,11 +116,35 @@ export function startServer(workflowDir, port = 3000) {
     // 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`);
-  });
-}
+  };
+
+  // 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.1.0",
+  "version": "1.3.0",
   "type": "module",
   "description": "A workflow orchestrator for running agents and scripts in sequence with state management",
   "main": "lib/index.js",