agent-state-machine 2.2.1 → 2.3.0

package/bin/cli.js

@@ -97,6 +97,8 @@ Options:
   --template, -t  Template name for --setup (default: starter)
   --local, -l     Use local server instead of remote (starts on localhost:3000)
   --new, -n       Generate a new remote follow path
+  --full-auto, -a Auto-select first option for choice interactions (no blocking)
+  --delay, -d     Seconds to wait before auto-select in full-auto mode (default: 20)
   -reset          Reset workflow state before running
   -reset-hard     Hard reset workflow before running
   --help, -h      Show help
@@ -106,7 +108,7 @@ Environment Variables:
   STATE_MACHINE_REMOTE_URL    Override the default remote server URL (for local dev testing)
 
 Workflow Structure:
-  workflows/<name>/
+  .workflows/<name>/
   ├── workflow.js        # Native JS workflow (async/await)
   ├── config.js          # Model/API key configuration
   ├── package.json       # Sets "type": "module" for this workflow folder
@@ -140,7 +142,7 @@ async function confirmHardReset(workflowName) {
 }
 
 function workflowsRoot() {
-  return path.join(process.cwd(), 'workflows');
+  return path.join(process.cwd(), '.workflows');
 }
 
 function resolveWorkflowDir(workflowName) {
@@ -192,7 +194,7 @@ function listWorkflows() {
   const root = workflowsRoot();
 
   if (!fs.existsSync(root)) {
-    console.log('No workflows directory found.');
+    console.log('No .workflows directory found.');
     console.log('Run `state-machine --setup <name>` to create your first workflow.');
     return;
   }
@@ -238,7 +240,9 @@ async function runOrResume(
     useLocalServer = false,
     forceNewRemotePath = false,
     preReset = false,
-    preResetHard = false
+    preResetHard = false,
+    fullAuto = false,
+    autoSelectDelay = null
   } = {}
 ) {
   const workflowDir = resolveWorkflowDir(workflowName);
@@ -294,6 +298,16 @@ async function runOrResume(
     await runtime.enableRemote(remoteUrl, { sessionToken, uiBaseUrl: useLocalServer });
   }
 
+  // Set full-auto mode from CLI flag (will be merged with config.js during runWorkflow)
+  if (fullAuto) {
+    runtime.workflowConfig.fullAuto = true;
+    if (autoSelectDelay !== null) {
+      runtime.workflowConfig.autoSelectDelay = autoSelectDelay;
+    }
+    const delay = runtime.workflowConfig.autoSelectDelay;
+    console.log(`\n\x1b[36m\x1b[1m⚡ Full-auto mode enabled\x1b[0m - Agent will auto-select recommended options after ${delay}s countdown`);
+  }
+
   // Prevent system sleep while workflow runs (macOS only)
   // Display can still sleep, but system stays awake for remote follow
   const stopCaffeinate = preventSleep();
@@ -370,14 +384,28 @@ async function main() {
         const forceNewRemotePath = args.includes('--new') || args.includes('-n');
         const preReset = args.includes('-reset');
         const preResetHard = args.includes('-reset-hard');
+        const fullAuto = args.includes('--full-auto') || args.includes('-a');
         const remoteEnabled = !useLocalServer; // Use Vercel if not local
+
+        // Parse --delay or -d flag
+        let autoSelectDelay = null;
+        const delayFlagIndex = args.findIndex((arg) => arg === '--delay' || arg === '-d');
+        if (delayFlagIndex !== -1 && args[delayFlagIndex + 1]) {
+          const delayValue = parseInt(args[delayFlagIndex + 1], 10);
+          if (!isNaN(delayValue) && delayValue >= 0) {
+            autoSelectDelay = delayValue;
+          }
+        }
+
         try {
           await runOrResume(workflowName, {
             remoteEnabled,
             useLocalServer,
             forceNewRemotePath,
             preReset,
-            preResetHard
+            preResetHard,
+            fullAuto,
+            autoSelectDelay
           });
         } catch (err) {
           console.error('Error:', err.message || String(err));

package/lib/file-tree.js

@@ -21,7 +21,7 @@ export const DEFAULT_IGNORE = [
   'coverage/**',
   '.next/**',
   '.cache/**',
-  'workflows/**',
+  '.workflows/**',
   '*.log',
   '.DS_Store'
 ];

package/lib/runtime/agent.js

@@ -533,7 +533,10 @@ ${content}
     validation: interaction.validation,
     confirmLabel: interaction.confirmLabel,
     cancelLabel: interaction.cancelLabel,
-    context: interaction.context
+    context: interaction.context,
+    // Include full-auto info for remote UI countdown
+    fullAuto: runtime.workflowConfig.fullAuto || false,
+    autoSelectDelay: runtime.workflowConfig.autoSelectDelay ?? 20
   });
 
   if (effectiveAgentName) {
@@ -541,7 +544,8 @@ ${content}
   }
 
   // Block and wait for user input (instead of throwing)
-  const response = await runtime.waitForInteraction(filePath, slug, targetKey);
+  // Pass the full interaction object for full-auto mode support
+  const response = await runtime.waitForInteraction(filePath, slug, targetKey, interaction);
 
   return response;
 }

package/lib/runtime/interaction.js

@@ -117,8 +117,9 @@ export function formatInteractionPrompt(interaction) {
     interaction.options.forEach((opt, index) => {
       const letter = String.fromCharCode(65 + index);
       const label = opt.label || opt.key || `Option ${index + 1}`;
+      const recommended = index === 0 ? ' (Recommended)' : '';
       const desc = opt.description ? ` - ${opt.description}` : '';
-      lines.push(`- ${letter}: ${label}${desc}`);
+      lines.push(`- ${letter}: ${label}${recommended}${desc}`);
     });
     if (interaction.allowCustom) {
       lines.push('- Other: Provide a custom response');

package/lib/runtime/prompt.js

@@ -51,9 +51,45 @@ export async function askHuman(question, options = {}) {
     validation: interaction?.validation,
     confirmLabel: interaction?.confirmLabel,
     cancelLabel: interaction?.cancelLabel,
-    context: interaction?.context
+    context: interaction?.context,
+    // Include full-auto info for remote UI countdown
+    fullAuto: runtime.workflowConfig.fullAuto || false,
+    autoSelectDelay: runtime.workflowConfig.autoSelectDelay ?? 20
   });
 
+  // Full-auto mode: show countdown and auto-select first option for choice interactions
+  if (runtime.workflowConfig.fullAuto && interaction?.type === 'choice') {
+    const options = interaction.options || [];
+    if (options.length > 0) {
+      const firstOption = options[0];
+      const autoResponse = firstOption.key || firstOption.label;
+      const delay = runtime.workflowConfig.autoSelectDelay ?? 20;
+
+      console.log(`\n${C.cyan}${C.bold}${interaction.prompt || 'Choice required'}${C.reset}`);
+      if (runtime.remoteEnabled && runtime.remoteUrl) {
+        console.log(`${C.dim}(Remote: ${runtime.remoteUrl})${C.reset}`);
+      }
+
+      // Countdown timer
+      for (let i = delay; i > 0; i--) {
+        process.stdout.write(`\r${C.yellow}⚡ Agent deciding for you in ${i}...${C.reset}  `);
+        await new Promise(r => setTimeout(r, 1000));
+      }
+      console.log(`\r${C.green}${C.bold}⚡ Auto-selected: ${autoResponse}${C.reset}          \n`);
+
+      runtime._rawMemory[memoryKey] = autoResponse;
+      runtime.persist();
+
+      await runtime.prependHistory({
+        event: 'PROMPT_AUTO_ANSWERED',
+        slug,
+        autoSelected: autoResponse
+      });
+
+      return autoResponse;
+    }
+  }
+
   // Check if we're in TTY mode (interactive terminal)
   if (process.stdin.isTTY && process.stdout.isTTY) {
     // Interactive mode - prompt directly, with remote support

package/lib/runtime/runtime.js

@@ -80,7 +80,11 @@ export class WorkflowRuntime {
       projectRoot: path.resolve(workflowDir, '../..'),
       fileTracking: true,
       fileTrackingIgnore: DEFAULT_IGNORE,
-      fileTrackingKeepDeleted: false
+      fileTrackingKeepDeleted: false,
+      // Full-auto mode (auto-select first option for choice interactions)
+      fullAuto: false,
+      maxQuickFixAttempts: 10,
+      autoSelectDelay: 20  // seconds before auto-selecting in full-auto mode
     };
 
     // Load steering
@@ -320,6 +324,8 @@ export class WorkflowRuntime {
       configUrl.searchParams.set('t', Date.now().toString());
       const configModule = await import(configUrl.href);
       const cfg = configModule.config || configModule.default || {};
+      // Preserve CLI-set fullAuto (it takes precedence over config.js)
+      const cliFullAuto = this.workflowConfig.fullAuto;
       this.workflowConfig = {
         models: cfg.models || {},
         apiKeys: cfg.apiKeys || {},
@@ -328,7 +334,11 @@ export class WorkflowRuntime {
         projectRoot: cfg.projectRoot || path.resolve(this.workflowDir, '../..'),
         fileTracking: cfg.fileTracking ?? true,
         fileTrackingIgnore: cfg.fileTrackingIgnore || DEFAULT_IGNORE,
-        fileTrackingKeepDeleted: cfg.fileTrackingKeepDeleted ?? false
+        fileTrackingKeepDeleted: cfg.fileTrackingKeepDeleted ?? false,
+        // Full-auto mode: CLI flag takes precedence, then config.js, then default false
+        fullAuto: cliFullAuto || cfg.fullAuto || false,
+        maxQuickFixAttempts: cfg.maxQuickFixAttempts ?? 10,
+        autoSelectDelay: cfg.autoSelectDelay ?? this.workflowConfig.autoSelectDelay  // seconds before auto-selecting
       };
 
       // Import workflow module
@@ -368,8 +378,17 @@ export class WorkflowRuntime {
   /**
    * Wait for user to confirm interaction is complete, then return the response
    * Supports both local TTY input and remote browser responses
+   * @param {string} filePath - Path to the interaction file
+   * @param {string} slug - Interaction slug
+   * @param {string} targetKey - Memory key to store response
+   * @param {object} [interaction] - Optional interaction object for full-auto mode
    */
-  async waitForInteraction(filePath, slug, targetKey) {
+  async waitForInteraction(filePath, slug, targetKey, interaction = null) {
+    // Determine if we're in full-auto mode for choice interactions
+    const isFullAutoChoice = this.workflowConfig.fullAuto && interaction?.type === 'choice' && interaction.options?.length > 0;
+    const autoResponse = isFullAutoChoice ? (interaction.options[0].key || interaction.options[0].label) : null;
+    const delay = isFullAutoChoice ? (this.workflowConfig.autoSelectDelay ?? 20) : 0;
+
     console.log(`\n${C.yellow}${C.bold}⏸  Interaction required.${C.reset}`);
 
     if (this.remoteEnabled && this.remoteUrl) {
@@ -387,11 +406,16 @@ export class WorkflowRuntime {
     return new Promise((resolve, reject) => {
       // Track if we've already resolved (to prevent double-resolution)
       let resolved = false;
+      let countdownTimer = null;
 
       const cleanup = () => {
         resolved = true;
         rl.close();
         this.pendingRemoteInteraction = null;
+        if (countdownTimer) {
+          clearTimeout(countdownTimer);
+          countdownTimer = null;
+        }
       };
 
       // Set up remote interaction listener
@@ -414,7 +438,9 @@ export class WorkflowRuntime {
               source: 'remote'
             });
 
+            const displayResponse = typeof response === 'object' ? JSON.stringify(response) : response;
             console.log(`\n${C.green}✓ Interaction resolved (remote): ${slug}${C.reset}`);
+            console.log(`  ${C.cyan}Selected:${C.reset} ${displayResponse}`);
             resolve(response);
           },
           reject: (err) => {
@@ -425,7 +451,38 @@ export class WorkflowRuntime {
         };
       }
 
-      // Local TTY input loop
+      // Full-auto countdown (can be interrupted by remote submission or local input)
+      if (isFullAutoChoice) {
+        let remaining = delay;
+        const tick = () => {
+          if (resolved) return;
+          if (remaining <= 0) {
+            // Auto-select
+            cleanup();
+            console.log(`\r  ${C.cyan}${C.bold}⚡ Auto-selected: ${autoResponse}${C.reset}                    `);
+            console.log(`  ${C.cyan}Selected:${C.reset} ${autoResponse}`);
+
+            this._rawMemory[targetKey] = autoResponse;
+            this.persist();
+
+            this.prependHistory({
+              event: 'INTERACTION_AUTO_RESOLVED',
+              slug,
+              targetKey,
+              autoSelected: autoResponse
+            });
+
+            resolve(autoResponse);
+            return;
+          }
+          process.stdout.write(`\r  ${C.cyan}${C.bold}⚡ Agent deciding for you in ${remaining}...${C.reset}  `);
+          remaining--;
+          countdownTimer = setTimeout(tick, 1000);
+        };
+        tick();
+      }
+
+      // Local TTY input loop (always active - can interrupt countdown in full-auto mode)
       const ask = () => {
         if (resolved) return;
 
@@ -438,13 +495,18 @@ export class WorkflowRuntime {
             // Read and return the response from file
             try {
               const response = await this.readInteractionResponse(filePath, slug, targetKey);
+              console.log(`  ${C.cyan}Selected:${C.reset} ${typeof response === 'object' ? JSON.stringify(response) : response}`);
               resolve(response);
             } catch (err) {
               reject(err);
             }
           } else if (a === 'q') {
             cleanup();
-            reject(new Error('User quit workflow'));
+            console.log(`\n${C.yellow}⏹  Workflow stopped by user${C.reset}`);
+            this.status = 'STOPPED';
+            this.persist();
+            this.prependHistory({ event: 'WORKFLOW_STOPPED', reason: 'user_quit' });
+            process.exit(0);
           } else {
             ask();
           }

package/lib/setup.js

@@ -70,7 +70,7 @@ function copyTemplateDir(srcDir, destDir, replacements, createdPaths) {
  * Setup a new workflow with directory structure
  */
 async function setup(workflowName, options = {}) {
-  const workflowsDir = path.join(process.cwd(), 'workflows');
+  const workflowsDir = path.join(process.cwd(), '.workflows');
   const workflowDir = path.join(workflowsDir, workflowName);
   const templateName = options.template || DEFAULT_TEMPLATE;
 
@@ -111,9 +111,9 @@ async function setup(workflowName, options = {}) {
   console.log('─'.repeat(40));
   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. Edit workflows/${workflowName}/config.js to set models/API keys`);
-  console.log(`  3. Add custom agents in workflows/${workflowName}/agents/`);
+  console.log(`  1. Edit .workflows/${workflowName}/workflow.js to implement your flow`);
+  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`);
 }
 

package/package.json

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

package/templates/project-builder/agents/code-fixer.md

@@ -0,0 +1,50 @@
+---
+model: high
+format: json
+---
+
+# Code Fixer Agent
+
+You fix specific issues in existing code based on sanity check failures.
+
+## Critical Guidelines
+
+**DO NOT** disable, skip, or remove failing tests to make them pass.
+Your fixes must address the actual underlying code issues that cause tests to fail.
+
+- ❌ Never add `.skip()`, `.todo()`, or comment out tests
+- ❌ Never modify test expectations to match broken behavior
+- ❌ Never delete test files or test cases
+- ❌ Never wrap tests in `try/catch` to swallow errors
+- ✅ Fix the implementation code to pass existing tests
+- ✅ Fix test setup/teardown issues if the tests themselves are misconfigured
+- ✅ Update tests ONLY if the original requirements were misunderstood
+
+If the issue truly cannot be fixed within the current architecture, set `"confidence": "low"` and explain why in the analysis.
+
+## Input
+- task: Task definition
+- originalImplementation: Current code-writer output
+- sanityCheckResults: Failed checks with specific errors
+- testPlan: Test plan for context
+- previousAttempts: Number of quick-fix attempts so far
+
+## Output Format
+
+{
+  "analysis": {
+    "rootCauses": ["What caused each failure"],
+    "fixApproach": "Strategy for fixing"
+  },
+  "fixes": [
+    {
+      "path": "src/feature.js",
+      "operation": "replace",
+      "code": "// Full corrected file content"
+    }
+  ],
+  "expectedResolutions": ["Which checks should now pass"],
+  "confidence": "high|medium|low"
+}
+
+Focus on minimal, targeted fixes. Don't rewrite entire files unless necessary.

package/templates/project-builder/agents/code-writer.md

@@ -27,6 +27,9 @@ Implement the task following these principles:
 - Implement to satisfy the test plan
 - Ensure all test cases can pass
 - Consider edge cases identified in testing
+- Write runnable test files, not just descriptions
+- Use appropriate test locations (e.g. *.test.js, *.spec.js, __tests__/)
+- Tests must import and exercise real implementation functions
 
 ## Output Format
 

package/templates/project-builder/agents/sanity-checker.md

@@ -9,6 +9,7 @@ Input:
 - task: { title, description, doneDefinition, sanityCheck }
 - implementation: code-writer output
 - testPlan: test-planner output
+- testFramework: { framework, command }
 
 Return JSON only in this shape:
 {
@@ -34,6 +35,8 @@ Guidelines:
 - If the task describes a server endpoint, include a curl check.
 - Keep checks short, clear, and runnable.
 - Include at least one file_exists or file_contains check when files are created/modified.
+- If tests exist (from testPlan or implementation), include a type "test_suite" check.
+- Use testFramework.command for running tests (optionally target specific files when possible).
 
 Task:
 {{task}}
@@ -43,3 +46,6 @@ Implementation:
 
 Test Plan:
 {{testPlan}}
+
+Test Framework:
+{{testFramework}}

package/templates/project-builder/agents/test-planner.md

@@ -22,6 +22,7 @@ Create a comprehensive test plan for the task. Include:
 - Cover happy path and error cases
 - Include tests for security concerns flagged in review
 - Prioritize tests by risk and importance
+- Provide expected test file paths for planned tests
 
 ## Output Format
 
@@ -59,7 +60,8 @@ Return a valid JSON object:
         "scenario": "Empty input handling",
         "expectedBehavior": "Return validation error"
       }
-    ]
+    ],
+    "testFilePaths": ["src/feature.test.js"]
   },
   "testingNotes": "Any special considerations or setup needed"
 }

package/templates/project-builder/config.js

@@ -1,9 +1,9 @@
 export const config = {
   models: {
-    fast: "gemini",
-    low: "gemini",
-    med: "gemini",
-    high: "gemini",
+    fast: "gemini -m gemini-2.5-flash-lite",
+    low: "gemini -m gemini-2.5-flash-lite",
+    med: "gemini -m gemini-2.5-flash-lite",
+    high: "gemini -m gemini-2.5-flash-lite",
   },
   apiKeys: {
     gemini: process.env.GEMINI_API_KEY,

package/templates/project-builder/scripts/workflow-helpers.js

@@ -1,6 +1,39 @@
 import fs from 'fs';
 import path from 'path';
-import { memory } from 'agent-state-machine';
+import { memory, getCurrentRuntime } from 'agent-state-machine';
+
+// Write implementation files from code-writer agent output
+function writeImplementationFiles(implementation) {
+  const runtime = getCurrentRuntime();
+  if (!runtime) {
+    throw new Error('writeImplementationFiles must be called within a workflow context');
+  }
+
+  const projectRoot = runtime.workflowConfig.projectRoot;
+  const files = implementation?.implementation?.files || implementation?.files || [];
+  const written = [];
+
+  for (const file of files) {
+    if (!file.path || !file.code) {
+      console.warn(`  [File] Skipping invalid file entry: ${JSON.stringify(file)}`);
+      continue;
+    }
+
+    const fullPath = path.resolve(projectRoot, file.path);
+
+    // Ensure directory exists
+    const dir = path.dirname(fullPath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+
+    fs.writeFileSync(fullPath, file.code);
+    written.push(file.path);
+    console.log(`  [File] Created: ${file.path}`);
+  }
+
+  return written;
+}
 
 // Write markdown file to workflow state directory
 function writeMarkdownFile(stateDir, filename, content) {
@@ -109,8 +142,72 @@ function setTaskData(phaseIndex, taskId, dataKey, value) {
   memory[key] = value;
 }
 
+function clearPartialTaskData(phaseIndex, taskId, keepKeys = []) {
+  const allKeys = [
+    'security_pre',
+    'tests',
+    'code',
+    'review',
+    'security_post',
+    'sanity_checks',
+    'sanity_results'
+  ];
+  for (const key of allKeys) {
+    if (!keepKeys.includes(key)) {
+      setTaskData(phaseIndex, taskId, key, null);
+    }
+  }
+}
+
+function getQuickFixAttempts(phaseIndex, taskId) {
+  return getTaskData(phaseIndex, taskId, 'quick_fix_attempts') || 0;
+}
+
+function incrementQuickFixAttempts(phaseIndex, taskId) {
+  const current = getQuickFixAttempts(phaseIndex, taskId);
+  setTaskData(phaseIndex, taskId, 'quick_fix_attempts', current + 1);
+}
+
+function resetQuickFixAttempts(phaseIndex, taskId) {
+  setTaskData(phaseIndex, taskId, 'quick_fix_attempts', 0);
+}
+
+function detectTestFramework() {
+  const runtime = getCurrentRuntime();
+  const projectRoot = runtime?.workflowConfig?.projectRoot || process.cwd();
+  const pkgPath = path.join(projectRoot, 'package.json');
+
+  if (!fs.existsSync(pkgPath)) {
+    return { framework: 'vitest', command: 'npx vitest run', isDefault: true };
+  }
+
+  let pkg;
+  try {
+    pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+  } catch (error) {
+    console.warn(`  [Test] Failed to parse package.json: ${error.message}`);
+    return { framework: 'vitest', command: 'npx vitest run', isDefault: true };
+  }
+
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+  const testScript = pkg.scripts?.test || '';
+
+  if (testScript.includes('vitest') || deps.vitest) {
+    return { framework: 'vitest', command: 'npm test' };
+  }
+  if (testScript.includes('jest') || deps.jest) {
+    return { framework: 'jest', command: 'npm test' };
+  }
+  if (testScript.includes('mocha') || deps.mocha) {
+    return { framework: 'mocha', command: 'npm test' };
+  }
+
+  return { framework: 'vitest', command: 'npx vitest run', isDefault: true };
+}
+
 export {
   writeMarkdownFile,
+  writeImplementationFiles,
   isApproval,
   renderRoadmapMarkdown,
   renderTasksMarkdown,
@@ -118,5 +215,10 @@ export {
   getTaskStage,
   setTaskStage,
   getTaskData,
-  setTaskData
+  setTaskData,
+  clearPartialTaskData,
+  getQuickFixAttempts,
+  incrementQuickFixAttempts,
+  resetQuickFixAttempts,
+  detectTestFramework
 };