agent-state-machine 2.0.11 → 2.0.13

package/README.md

@@ -56,6 +56,7 @@ Workflows live in:
 ```text
 workflows/<name>/
 ├── workflow.js        # Native JS workflow (async/await)
+├── config.js          # Model/API key configuration
 ├── 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)
@@ -67,6 +68,8 @@ workflows/<name>/
 
 ## Writing workflows (native JS)
 
+Edit `config.js` to set models and API keys for the workflow.
+
 ```js
 /**
 /**
@@ -83,20 +86,6 @@ workflows/<name>/
 import { agent, memory, askHuman, parallel } from 'agent-state-machine';
 import { notify } from './scripts/mac-notification.js';
 
-// Model configuration (also supports models in a separate config export)
-export const config = {
-  models: {
-    low: "gemini",
-    med: "codex --model gpt-5.2",
-    high: "claude -m claude-opus-4-20250514 -p",
-  },
-  apiKeys: {
-    gemini: process.env.GEMINI_API_KEY,
-    anthropic: process.env.ANTHROPIC_API_KEY,
-    openai: process.env.OPENAI_API_KEY,
-  }
-};
-
 export default async function() {
   console.log('Starting project-builder workflow...');
 
@@ -298,7 +287,7 @@ export const config = {
 };
 ```
 
-The runtime captures the fully-built prompt in `state/history.jsonl`, viewable in the browser with live updates when running with the `--local` flag or via the remote URL. Remote follow links persist across runs (stored in `workflow.js` config) unless you pass `-n`/`--new` to regenerate.
+The runtime captures the fully-built prompt in `state/history.jsonl`, viewable in the browser with live updates when running with the `--local` flag or via the remote URL. Remote follow links persist across runs (stored in `config.js`) unless you pass `-n`/`--new` to regenerate.
 
 ---
 

package/bin/cli.js

@@ -63,6 +63,7 @@ Environment Variables:
 Workflow Structure:
   workflows/<name>/
   ├── workflow.js        # Native JS workflow (async/await)
+  ├── config.js          # Model/API key configuration
   ├── 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)
@@ -185,8 +186,8 @@ function findConfigObjectRange(source) {
   return null;
 }
 
-function readRemotePathFromWorkflow(workflowFile) {
-  const source = fs.readFileSync(workflowFile, 'utf-8');
+function readRemotePathFromConfig(configFile) {
+  const source = fs.readFileSync(configFile, 'utf-8');
   const range = findConfigObjectRange(source);
   if (!range) return null;
   const configSource = source.slice(range.start, range.end + 1);
@@ -194,19 +195,19 @@ function readRemotePathFromWorkflow(workflowFile) {
   return match ? match[2] : null;
 }
 
-function writeRemotePathToWorkflow(workflowFile, remotePath) {
-  const source = fs.readFileSync(workflowFile, 'utf-8');
+function writeRemotePathToConfig(configFile, remotePath) {
+  const source = fs.readFileSync(configFile, 'utf-8');
   const range = findConfigObjectRange(source);
   const remoteLine = `remotePath: "${remotePath}"`;
 
   if (!range) {
     const hasConfigExport = /export\s+const\s+config\s*=/.test(source);
     if (hasConfigExport) {
-      throw new Error('Workflow config export is not an object literal; add remotePath manually.');
+      throw new Error('Config export is not an object literal; add remotePath manually.');
     }
     const trimmed = source.replace(/\s*$/, '');
     const appended = `${trimmed}\n\nexport const config = {\n  ${remoteLine}\n};\n`;
-    fs.writeFileSync(workflowFile, appended);
+    fs.writeFileSync(configFile, appended);
     return;
   }
 
@@ -247,15 +248,15 @@ function writeRemotePathToWorkflow(workflowFile, remotePath) {
     source.slice(0, range.start) +
     updatedConfigSource +
     source.slice(range.end + 1);
-  fs.writeFileSync(workflowFile, updatedSource);
+  fs.writeFileSync(configFile, updatedSource);
 }
 
-function ensureRemotePath(workflowFile, { forceNew = false } = {}) {
-  const existing = readRemotePathFromWorkflow(workflowFile);
+function ensureRemotePath(configFile, { forceNew = false } = {}) {
+  const existing = readRemotePathFromConfig(configFile);
   if (existing && !forceNew) return existing;
 
   const remotePath = generateSessionToken();
-  writeRemotePathToWorkflow(workflowFile, remotePath);
+  writeRemotePathToConfig(configFile, remotePath);
   return remotePath;
 }
 
@@ -276,6 +277,7 @@ function summarizeStatus(state) {
   if (s === 'COMPLETED') return ' [completed]';
   if (s === 'FAILED') return ' [failed - can resume]';
   if (s === 'PAUSED') return ' [paused - can resume]';
+  if (s === 'STOPPED') return ' [stopped - can resume]';
   if (s === 'RUNNING') return ' [running]';
   if (s === 'IDLE') return ' [idle]';
   return state.status ? ` [${state.status}]` : '';
@@ -361,6 +363,7 @@ async function runOrResume(
   }
 
   const workflowUrl = pathToFileURL(entry).href;
+  const configFile = path.join(workflowDir, 'config.js');
 
   let localServer = null;
   let remoteUrl = null;
@@ -382,7 +385,7 @@ async function runOrResume(
 
   // Enable remote follow mode if we have a URL
   if (remoteUrl) {
-    const sessionToken = ensureRemotePath(entry, { forceNew: forceNewRemotePath });
+    const sessionToken = ensureRemotePath(configFile, { forceNew: forceNewRemotePath });
     await runtime.enableRemote(remoteUrl, { sessionToken });
   }
 

package/lib/llm.js

@@ -51,6 +51,7 @@ export function buildPrompt(context, options) {
     delete cleanContext._steering;
     delete cleanContext._loop;
     delete cleanContext._config;
+    delete cleanContext._memory;
 
     // Add the actual prompt
     parts.push('# Task\n\n');
@@ -70,13 +71,22 @@ export function buildPrompt(context, options) {
   parts.push('{ "interact": "your question here" }\n\n');
   parts.push('Only use this format when you genuinely need user input to proceed.\n\n---\n');
 
-  // Add global steering if available
+  // Add global steering if available (always first)
   if (context._steering?.global) {
     parts.push('# System Instructions\n');
     parts.push(context._steering.global);
     parts.push('\n---\n');
   }
 
+  // Add additional steering files if available
+  if (context._steering?.additional && context._steering.additional.length > 0) {
+    parts.push('# Additional Guidelines\n');
+    for (const content of context._steering.additional) {
+      parts.push(content);
+      parts.push('\n---\n');
+    }
+  }
+
   return parts.join('\n');
 }
 
@@ -314,7 +324,7 @@ async function executeAPI(provider, model, prompt, apiKey, options = {}) {
  *
  * @param {object} context - The workflow context (contains _config, _steering, etc.)
  * @param {object} options - Options for the LLM call
- * @param {string} options.model - Model key from workflow.js models config
+ * @param {string} options.model - Model key from config.js models config
  * @param {string} options.prompt - The prompt to send
  * @param {boolean} options.includeContext - Whether to include context in prompt (default: true)
  * @param {number} options.maxTokens - Max tokens for API calls (default: 4096)
@@ -359,7 +369,7 @@ export async function llm(context, options) {
 
     if (!apiKey) {
       throw new Error(
-        `No API key found for ${provider}. Set in workflow.js apiKeys or ${provider.toUpperCase()}_API_KEY env var`
+        `No API key found for ${provider}. Set in config.js apiKeys or ${provider.toUpperCase()}_API_KEY env var`
       );
     }
 
@@ -459,4 +469,4 @@ export async function llmJSON(context, options) {
     ...response,
     data: parseJSON(response.text)
   };
-}
+}

package/lib/runtime/agent.js

@@ -17,50 +17,87 @@ const require = createRequire(import.meta.url);
 /**
  * Run an agent with context
  * @param {string} name - Agent name (file basename)
- * @param {object} params - Parameters passed to agent
+ * @param {object} params - Parameters passed to agent (default: {})
+ * @param {object} options - Agent execution options (default: {})
+ * @param {number|false} options.retry - Number of retries (default: 2, meaning 3 total attempts). Set to false to disable.
+ * @param {string|string[]} options.steering - Additional steering files to load from steering/ folder
  */
-export async function agent(name, params = {}) {
+export async function agent(name, params = {}, options = {}) {
   const runtime = getCurrentRuntime();
   if (!runtime) {
     throw new Error('agent() must be called within a workflow context');
   }
 
-  console.log(`  [Agent: ${name}] Starting...`);
+  // Parse retry option: default is 2 retries (3 total attempts)
+  const retryCount = options.retry === false ? 0 : (options.retry ?? 2);
 
-  try {
-    const result = await executeAgent(runtime, name, params);
+  let lastError;
 
-    if (result && typeof result === 'object' && result._debug_prompt) {
-      delete result._debug_prompt;
-    }
+  for (let attempt = 0; attempt <= retryCount; attempt++) {
+    try {
+      if (attempt > 0) {
+        console.log(`  [Agent: ${name}] Retry attempt ${attempt}/${retryCount}...`);
+      } else {
+        console.log(`  [Agent: ${name}] Starting...`);
+      }
+
+      const result = await executeAgent(runtime, name, params, options);
+
+      if (result && typeof result === 'object' && result._debug_prompt) {
+        delete result._debug_prompt;
+      }
+
+      console.log(`  [Agent: ${name}] Completed`);
+      if (runtime._agentSuppressCompletion?.has(name)) {
+        runtime._agentSuppressCompletion.delete(name);
+        return result;
+      }
+
+      runtime.prependHistory({
+        event: 'AGENT_COMPLETED',
+        agent: name,
+        output: result,
+        attempts: attempt + 1
+      });
 
-    console.log(`  [Agent: ${name}] Completed`);
-    if (runtime._agentSuppressCompletion?.has(name)) {
-      runtime._agentSuppressCompletion.delete(name);
       return result;
+    } catch (error) {
+      lastError = error;
+
+      if (attempt < retryCount) {
+        console.error(`  [Agent: ${name}] Error (attempt ${attempt + 1}/${retryCount + 1}): ${error.message}`);
+        runtime.prependHistory({
+          event: 'AGENT_RETRY',
+          agent: name,
+          attempt: attempt + 1,
+          error: error.message
+        });
+      }
     }
+  }
 
-    runtime.prependHistory({
-      event: 'AGENT_COMPLETED',
-      agent: name,
-      output: result
-    });
+  // All retries exhausted - record failure
+  runtime.prependHistory({
+    event: 'AGENT_FAILED',
+    agent: name,
+    error: lastError.message,
+    attempts: retryCount + 1
+  });
 
-    return result;
-  } catch (error) {
-    runtime.prependHistory({
-      event: 'AGENT_FAILED',
-      agent: name,
-      error: error.message
-    });
-    throw error;
-  }
+  // Store error in accessible location (not auto-spread to context)
+  runtime._agentErrors.push({
+    agent: name,
+    error: lastError.message,
+    timestamp: new Date().toISOString()
+  });
+
+  throw lastError;
 }
 
 /**
  * Execute an agent (load and run)
  */
-export async function executeAgent(runtime, name, params) {
+export async function executeAgent(runtime, name, params, options = {}) {
   const agentsDir = runtime.agentsDir;
 
   // Try JS agents (.js/.mjs/.cjs)
@@ -72,14 +109,14 @@ export async function executeAgent(runtime, name, params) {
 
   for (const p of jsCandidates) {
     if (fs.existsSync(p)) {
-      return executeJSAgent(runtime, p, name, params);
+      return executeJSAgent(runtime, p, name, params, options);
     }
   }
 
   // Try Markdown agent
   const mdPath = path.join(agentsDir, `${name}.md`);
   if (fs.existsSync(mdPath)) {
-    return executeMDAgent(runtime, mdPath, name, params);
+    return executeMDAgent(runtime, mdPath, name, params, options);
   }
 
   throw new Error(
@@ -94,7 +131,7 @@ export async function executeAgent(runtime, name, params) {
  * - ESM (.js/.mjs): loaded via dynamic import with cache-bust for hot reload
  * - CJS (.cjs): loaded via require() with cache clear
  */
-async function executeJSAgent(runtime, agentPath, name, params) {
+async function executeJSAgent(runtime, agentPath, name, params, options = {}) {
   const ext = path.extname(agentPath).toLowerCase();
 
   let agentModule;
@@ -119,11 +156,15 @@ async function executeJSAgent(runtime, agentPath, name, params) {
 
   logAgentStart(runtime, name);
 
-  // Build context
+  // Build steering context (global + any additional files from options)
+  const steeringContext = options.steering
+    ? runtime.loadSteeringFiles(options.steering)
+    : runtime.steering;
+
+  // Build context - only spread params, NOT memory (explicit context passing)
   const context = {
-    ...runtime._rawMemory,
     ...params,
-    _steering: runtime.steering,
+    _steering: steeringContext,
     _config: {
       models: runtime.workflowConfig.models,
       apiKeys: runtime.workflowConfig.apiKeys,
@@ -175,7 +216,7 @@ async function executeJSAgent(runtime, agentPath, name, params) {
 /**
  * Execute a Markdown agent (prompt-based)
  */
-async function executeMDAgent(runtime, agentPath, name, params) {
+async function executeMDAgent(runtime, agentPath, name, params, options = {}) {
   const { llm, buildPrompt, parseJSON, parseInteractionRequest } = await import('../llm.js');
 
   const content = fs.readFileSync(agentPath, 'utf-8');
@@ -184,11 +225,28 @@ async function executeMDAgent(runtime, agentPath, name, params) {
   const outputKey = config.output || 'result';
   const targetKey = config.interactionKey || outputKey;
 
-  // Build context
+  // Combine steering from options (runtime call) and frontmatter (static)
+  let steeringNames = [];
+
+  if (options.steering) {
+    const optSteering = Array.isArray(options.steering) ? options.steering : [options.steering];
+    steeringNames.push(...optSteering);
+  }
+
+  if (config.steering) {
+    const fmSteering = parseSteeringFrontmatter(config.steering);
+    steeringNames.push(...fmSteering);
+  }
+
+  // Build steering context (global + any additional files)
+  const steeringContext = steeringNames.length > 0
+    ? runtime.loadSteeringFiles(steeringNames)
+    : runtime.steering;
+
+  // Build context - only spread params, NOT memory (explicit context passing)
   const context = {
-    ...runtime._rawMemory,
     ...params,
-    _steering: runtime.steering,
+    _steering: steeringContext,
     _config: {
       models: runtime.workflowConfig.models,
       apiKeys: runtime.workflowConfig.apiKeys,
@@ -296,6 +354,36 @@ function parseMarkdownAgent(content) {
   return { config: {}, prompt: content.trim() };
 }
 
+/**
+ * Parse steering value from frontmatter
+ * Supports: "name", "name1, name2", "[name1, name2]", "['name1', 'name2']"
+ * @param {string} value - Frontmatter steering value
+ * @returns {string[]} Array of steering file names
+ */
+function parseSteeringFrontmatter(value) {
+  if (!value) return [];
+
+  const trimmed = value.trim();
+
+  // Handle array format: [a, b, c] or ["a", "b", "c"]
+  if (trimmed.startsWith('[') && trimmed.endsWith(']')) {
+    const inner = trimmed.slice(1, -1);
+    return inner.split(',')
+      .map(s => s.trim().replace(/^["']|["']$/g, ''))
+      .filter(Boolean);
+  }
+
+  // Handle comma-separated: a, b, c
+  if (trimmed.includes(',')) {
+    return trimmed.split(',')
+      .map(s => s.trim())
+      .filter(Boolean);
+  }
+
+  // Single value
+  return [trimmed];
+}
+
 /**
  * Interpolate {{variables}} in prompt template
  */

package/lib/runtime/runtime.js

@@ -9,6 +9,7 @@
 import fs from 'fs';
 import path from 'path';
 import readline from 'readline';
+import { pathToFileURL } from 'url';
 import { createMemoryProxy } from './memory.js';
 import { RemoteClient } from '../remote/client.js';
 
@@ -88,6 +89,9 @@ export class WorkflowRuntime {
     // Agent interaction tracking for history logging
     this._agentResumeFlags = new Set();
     this._agentSuppressCompletion = new Set();
+
+    // Agent error tracking (not persisted to memory, but accessible during run)
+    this._agentErrors = [];
   }
 
   ensureDirectories() {
@@ -141,6 +145,39 @@ export class WorkflowRuntime {
     return steering;
   }
 
+  /**
+   * Load a specific steering file by name
+   * @param {string} name - Name of the steering file (without .md extension)
+   * @returns {string} Content of the steering file, or empty string if not found
+   */
+  loadSteeringFile(name) {
+    const filePath = path.join(this.steeringDir, `${name}.md`);
+
+    if (fs.existsSync(filePath)) {
+      return fs.readFileSync(filePath, 'utf-8');
+    }
+
+    console.warn(`${C.yellow}Warning: Steering file not found: ${name}.md${C.reset}`);
+    return '';
+  }
+
+  /**
+   * Load multiple steering files and combine with global
+   * @param {string|string[]} steeringNames - Names of steering files to load
+   * @returns {{ enabled: boolean, global: string, additional: string[] }}
+   */
+  loadSteeringFiles(steeringNames) {
+    const names = Array.isArray(steeringNames) ? steeringNames : [steeringNames];
+    const additional = names
+      .map(name => this.loadSteeringFile(name))
+      .filter(content => content.length > 0);
+
+    return {
+      ...this.steering,
+      additional
+    };
+  }
+
   /**
    * Persist state to disk
    */
@@ -218,6 +255,50 @@ export class WorkflowRuntime {
   async runWorkflow(workflowPath) {
     setCurrentRuntime(this);
 
+    // Handle Ctrl+C and termination signals to update status before exit
+    const handleShutdown = async (signal) => {
+      this.status = 'STOPPED';
+      this._error = `Workflow interrupted by ${signal}`;
+      this.persist();
+
+      // Log to history (local file)
+      const historyEntry = {
+        timestamp: new Date().toISOString(),
+        event: 'WORKFLOW_STOPPED',
+        reason: signal
+      };
+      const line = JSON.stringify(historyEntry) + '\n';
+      let existing = '';
+      if (fs.existsSync(this.historyFile)) {
+        existing = fs.readFileSync(this.historyFile, 'utf-8');
+      }
+      fs.writeFileSync(this.historyFile, line + existing);
+
+      // Send to remote and wait for it to complete before exiting
+      if (this.remoteClient && this.remoteEnabled) {
+        try {
+          await this.remoteClient.sendEvent(historyEntry);
+        } catch {
+          // Ignore errors during shutdown
+        }
+      }
+
+      console.log(`\n${C.yellow}⚠ Workflow '${this.workflowName}' stopped (${signal})${C.reset}`);
+      cleanupSignalHandlers();
+      clearCurrentRuntime();
+      process.exit(130); // 128 + SIGINT (2)
+    };
+
+    const sigintHandler = () => handleShutdown('SIGINT');
+    const sigtermHandler = () => handleShutdown('SIGTERM');
+    process.on('SIGINT', sigintHandler);
+    process.on('SIGTERM', sigtermHandler);
+
+    const cleanupSignalHandlers = () => {
+      process.removeListener('SIGINT', sigintHandler);
+      process.removeListener('SIGTERM', sigtermHandler);
+    };
+
     try {
       this.status = 'RUNNING';
       this._error = null;
@@ -226,18 +307,24 @@ export class WorkflowRuntime {
 
       this.prependHistory({ event: 'WORKFLOW_STARTED' });
 
-      // Import workflow module
-      const workflowModule = await import(workflowPath);
-      const runFn = workflowModule.default || workflowModule.run || workflowModule;
-
-      // Load workflow config from module export
-      const cfg = workflowModule.config || {};
+      const configPath = path.join(this.workflowDir, 'config.js');
+      if (!fs.existsSync(configPath)) {
+        throw new Error(`config.js not found in ${this.workflowDir}`);
+      }
+      const configUrl = pathToFileURL(configPath);
+      configUrl.searchParams.set('t', Date.now().toString());
+      const configModule = await import(configUrl.href);
+      const cfg = configModule.config || configModule.default || {};
       this.workflowConfig = {
         models: cfg.models || {},
         apiKeys: cfg.apiKeys || {},
         description: cfg.description || ''
       };
 
+      // Import workflow module
+      const workflowModule = await import(workflowPath);
+      const runFn = workflowModule.default || workflowModule.run || workflowModule;
+
       if (typeof runFn !== 'function') {
         throw new Error('Workflow module must export a default async function');
       }
@@ -263,6 +350,7 @@ export class WorkflowRuntime {
       console.error(`\n${C.red}✗ Workflow '${this.workflowName}' failed: ${err.message}${C.reset}`);
       throw err;
     } finally {
+      cleanupSignalHandlers();
       clearCurrentRuntime();
     }
   }
@@ -406,6 +494,7 @@ export class WorkflowRuntime {
     let statusColor = C.reset;
     if (this.status === 'COMPLETED') statusColor = C.green;
     if (this.status === 'FAILED') statusColor = C.red;
+    if (this.status === 'STOPPED') statusColor = C.yellow;
     if (this.status === 'RUNNING') statusColor = C.blue;
     if (this.status === 'IDLE') statusColor = C.gray;
     

package/lib/setup.js

@@ -62,20 +62,6 @@ async function setup(workflowName) {
 import { agent, memory, askHuman, parallel } from 'agent-state-machine';
 import { notify } from './scripts/mac-notification.js';
 
-// Model configuration (also supports models in a separate config export)
-export const config = {
-  models: {
-    low: "gemini",
-    med: "codex --model gpt-5.2",
-    high: "claude -m claude-opus-4-20250514 -p",
-  },
-  apiKeys: {
-    gemini: process.env.GEMINI_API_KEY,
-    anthropic: process.env.ANTHROPIC_API_KEY,
-    openai: process.env.OPENAI_API_KEY,
-  }
-};
-
 export default async function() {
   console.log('Starting ${workflowName} workflow...');
 
@@ -119,6 +105,24 @@ export default async function() {
   fs.writeFileSync(workflowFile, workflowJs);
   console.log(`  Created: ${path.relative(process.cwd(), workflowFile)}`);
 
+  const configJs = `export const config = {
+  models: {
+    low: "gemini",
+    med: "codex --model gpt-5.2",
+    high: "claude -m claude-opus-4-20250514 -p",
+  },
+  apiKeys: {
+    gemini: process.env.GEMINI_API_KEY,
+    anthropic: process.env.ANTHROPIC_API_KEY,
+    openai: process.env.OPENAI_API_KEY,
+  }
+};
+`;
+
+  const configFile = path.join(workflowDir, 'config.js');
+  fs.writeFileSync(configFile, configJs);
+  console.log(`  Created: ${path.relative(process.cwd(), configFile)}`);
+
   // Create example JS agent (ESM)
   // Create example JS agent (ESM)
   const exampleAgent = `/**
@@ -138,7 +142,7 @@ export default async function handler(context) {
     console.log('[Agent: example] Steering loaded (' + context._steering.global.length + ' chars)');
   }
 
-  // Example: Call an LLM (configure models in workflow.js)
+  // Example: Call an LLM (configure models in config.js)
   // const response = await llm(context, {
   //   model: 'smart',
   //   prompt: 'Say hello and describe what you can help with.'
@@ -295,6 +299,7 @@ A workflow created with agent-state-machine (native JS format).
 \\\`\\\`\\\`
 ${workflowName}/
 ├── workflow.js      # Native JS workflow (async/await)
+├── config.js        # Model/API key configuration
 ├── 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)
@@ -304,6 +309,8 @@ ${workflowName}/
 
 ## Usage
 
+Edit \`config.js\` to set models and API keys for this workflow.
+
 Run the workflow (or resume if interrupted):
 \\\`\\\`\\\`bash
 state-machine run ${workflowName}
@@ -411,8 +418,9 @@ Generate a greeting for {{name}}.
   console.log(`\n✓ Workflow '${workflowName}' created successfully!\n`);
   console.log('Next steps:');
   console.log(`  1. Edit workflows/${workflowName}/workflow.js to implement your flow`);
-  console.log(`  2. Add custom agents in workflows/${workflowName}/agents/`);
-  console.log(`  3. Run: state-machine run ${workflowName}\n`);
+  console.log(`  2. Edit workflows/${workflowName}/config.js to set models/API keys`);
+  console.log(`  3. Add custom agents in workflows/${workflowName}/agents/`);
+  console.log(`  4. Run: state-machine run ${workflowName}\n`);
 }
 
 export { setup };

package/package.json

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

package/vercel-server/ui/index.html

@@ -486,11 +486,24 @@
 
             useEffect(() => localStorage.setItem("rf_theme", theme), [theme]);
 
+            // Helper to check if workflow is currently running based on history
+            const isWorkflowRunning = (entries) => {
+                // Find the most recent workflow lifecycle event (history is newest-first)
+                for (const entry of entries) {
+                    if (entry.event === "WORKFLOW_STARTED") return true;
+                    if (entry.event === "WORKFLOW_STOPPED" ||
+                        entry.event === "WORKFLOW_COMPLETED" ||
+                        entry.event === "WORKFLOW_FAILED") return false;
+                }
+                return false; // No lifecycle events found
+            };
+
             useEffect(() => {
                 if (history.length === 0) { setPendingInteraction(null); return; }
 
                 const resolvedSlugs = new Set();
                 let pending = null;
+                const workflowRunning = isWorkflowRunning(history);
 
                 for (const entry of history) {
                     const isResolution =
@@ -510,7 +523,8 @@
                     }
                 }
 
-                setPendingInteraction(pending);
+                // Only show pending interaction if workflow is running
+                setPendingInteraction(workflowRunning ? pending : null);
             }, [history]);
 
             const fetchData = async () => {
@@ -520,8 +534,18 @@
                     if (data.entries) setHistory(data.entries);
                     if (data.workflowName) setWorkflowName(data.workflowName);
 
-                    if (token && data.cliConnected !== undefined) setStatus(data.cliConnected ? "connected" : "disconnected");
-                    else if (!token) setStatus("connected");
+                    // Check if workflow is currently running based on most recent lifecycle event
+                    const workflowRunning = isWorkflowRunning(data.entries || []);
+
+                    if (workflowRunning) {
+                        setStatus("connected");
+                    } else if (token && data.cliConnected !== undefined) {
+                        setStatus(data.cliConnected ? "connected" : "disconnected");
+                    } else if (!token) {
+                        setStatus("connected");
+                    } else {
+                        setStatus("disconnected");
+                    }
 
                     setLoading(false);
                     return true;
@@ -569,6 +593,8 @@
                                     break;
                                 case "history":
                                     setHistory(data.entries || []);
+                                    // Update status based on workflow lifecycle
+                                    setStatus(isWorkflowRunning(data.entries || []) ? "connected" : "disconnected");
                                     break;
                                 case "event":
                                     setHistory((prev) => {
@@ -578,6 +604,14 @@
                                         }
                                         return [data, ...prev];
                                     });
+                                    // Update status based on workflow lifecycle events
+                                    if (data.event === "WORKFLOW_STARTED") {
+                                        setStatus("connected");
+                                    } else if (data.event === "WORKFLOW_STOPPED" ||
+                                               data.event === "WORKFLOW_COMPLETED" ||
+                                               data.event === "WORKFLOW_FAILED") {
+                                        setStatus("disconnected");
+                                    }
                                     break;
                                 case "cli_connected":
                                 case "cli_reconnected":