agent-state-machine 2.4.0 → 2.6.0

package/bin/cli.js

@@ -338,13 +338,7 @@ async function runOrResume(
     remoteUrl = process.env.STATE_MACHINE_REMOTE_URL || DEFAULT_REMOTE_URL;
   }
 
-  // Enable remote follow mode if we have a URL
-  if (remoteUrl) {
-    const sessionToken = ensureRemotePath(configFile, { forceNew: forceNewRemotePath });
-    await runtime.enableRemote(remoteUrl, { sessionToken, uiBaseUrl: useLocalServer });
-  }
-
-  // Set full-auto mode from CLI flag (will be merged with config.js during runWorkflow)
+  // Set full-auto mode from CLI flag BEFORE enabling remote (so session_init includes correct config)
   if (fullAuto) {
     runtime.workflowConfig.fullAuto = true;
     if (autoSelectDelay !== null) {
@@ -354,6 +348,12 @@ async function runOrResume(
     console.log(`\n\x1b[36m\x1b[1m⚡ Full-auto mode enabled\x1b[0m - Agent will auto-select recommended options after ${delay}s countdown`);
   }
 
+  // Enable remote follow mode if we have a URL
+  if (remoteUrl) {
+    const sessionToken = ensureRemotePath(configFile, { forceNew: forceNewRemotePath });
+    await runtime.enableRemote(remoteUrl, { sessionToken, uiBaseUrl: useLocalServer });
+  }
+
   // Set non-verbose mode from CLI flag
   if (nonVerbose) {
     runtime.workflowConfig.nonVerbose = true;

package/lib/llm.js

@@ -354,15 +354,21 @@ async function executeCLI(command, promptText, options = {}, apiKeys = {}) {
 
     if (baseCmd === 'claude') {
       args.push('--print');
-      args.push('--permission-mode', 'acceptEdits');
+      const permissionMode = options.cliPermissions?.claude || 'acceptEdits';
+      args.push('--permission-mode', permissionMode);
       args.push('--output-format', 'json');
       // Input via stdin
     } else if (baseCmd === 'gemini') {
-      args.push('--approval-mode', 'auto_edit');
+      const approvalMode = options.cliPermissions?.gemini || 'auto_edit';
+      args.push('--approval-mode', approvalMode);
       args.push('--output-format', 'json');
       // Input via stdin
     } else if (baseCmd === 'codex') {
       ensureCodexExec();
+      const bypassMode = options.cliPermissions?.codex;
+      if (bypassMode === 'bypass') {
+        args.push('--dangerously-bypass-approvals-and-sandbox');
+      }
       args.push('--json');
       args.push('-'); // Explicitly read from stdin
     } else {
@@ -581,7 +587,12 @@ export async function llm(context, options) {
     result = await executeAPI(provider, model, fullPrompt, apiKey, options);
   } else {
     // CLI execution - pass fullPrompt string directly
-    result = await executeCLI(modelConfig, fullPrompt, options, apiKeys);
+    // Include cliPermissions from config if available
+    const cliOptions = {
+      ...options,
+      cliPermissions: config.cliPermissions || {}
+    };
+    result = await executeCLI(modelConfig, fullPrompt, cliOptions, apiKeys);
   }
 
   // Record usage in agent tracker (if active)

package/lib/remote/client.js

@@ -89,6 +89,7 @@ export class RemoteClient {
    * @param {string} options.serverUrl - Base URL of remote server (e.g., https://example.vercel.app)
    * @param {string} options.workflowName - Name of the workflow
    * @param {function} options.onInteractionResponse - Callback when interaction response received
+   * @param {function} [options.onConfigUpdate] - Callback when config update received from browser
    * @param {function} [options.onStatusChange] - Callback when connection status changes
    * @param {string} [options.sessionToken] - Optional session token to reuse
    * @param {boolean} [options.uiBaseUrl] - If true, return base URL for UI instead of /s/{token}
@@ -97,6 +98,7 @@ export class RemoteClient {
     this.serverUrl = options.serverUrl.replace(/\/$/, ''); // Remove trailing slash
     this.workflowName = options.workflowName;
     this.onInteractionResponse = options.onInteractionResponse;
+    this.onConfigUpdate = options.onConfigUpdate || (() => {});
     this.onStatusChange = options.onStatusChange || (() => {});
     this.uiBaseUrl = Boolean(options.uiBaseUrl);
 
@@ -166,16 +168,18 @@ export class RemoteClient {
   }
 
   /**
-   * Send initial session info with history
+   * Send initial session info with history and config
    * @param {Array} history - Array of history entries
+   * @param {object} [config] - Optional workflow config (fullAuto, autoSelectDelay)
    */
-  async sendSessionInit(history = []) {
+  async sendSessionInit(history = [], config = null) {
     this.initialHistorySent = true;
     await this.send({
       type: 'session_init',
       sessionToken: this.sessionToken,
       workflowName: this.workflowName,
       history,
+      config,
     });
   }
 
@@ -231,7 +235,7 @@ export class RemoteClient {
   }
 
   /**
-   * Poll for interaction responses
+   * Poll for interaction responses and config updates
    * Uses 35s timeout to stay under Vercel's 50s limit with buffer
    */
   async poll() {
@@ -246,20 +250,29 @@ export class RemoteClient {
         consecutiveErrors = 0; // Reset on success
 
         if (response.status === 200 && response.data) {
-          const { type, slug, targetKey, response: interactionResponse } = response.data;
+          const { type, slug, targetKey, response: interactionResponse, fullAuto, autoSelectDelay, stop } = response.data;
 
           if (type === 'interaction_response' && this.onInteractionResponse) {
             // Confirm receipt BEFORE processing - removes from Redis pending queue
-            // This ensures we don't lose the interaction if processing fails
             try {
               const confirmUrl = `${this.serverUrl}/api/ws/cli?token=${this.sessionToken}`;
               await makeRequest(confirmUrl, { method: 'DELETE' }, null, 10000);
             } catch (err) {
-              // Non-fatal - interaction will be re-delivered on next poll
               console.error(`${C.dim}Remote: Failed to confirm receipt: ${err.message}${C.reset}`);
             }
 
             this.onInteractionResponse(slug, targetKey, interactionResponse);
+          } else if (type === 'config_update') {
+            // Confirm receipt of config update
+            try {
+              const confirmUrl = `${this.serverUrl}/api/ws/cli?token=${this.sessionToken}&type=config`;
+              await makeRequest(confirmUrl, { method: 'DELETE' }, null, 10000);
+            } catch (err) {
+              console.error(`${C.dim}Remote: Failed to confirm config receipt: ${err.message}${C.reset}`);
+            }
+
+            // Call config update callback
+            this.onConfigUpdate({ fullAuto, autoSelectDelay, stop });
           }
         }
 

package/lib/runtime/agent.js

@@ -13,6 +13,8 @@ import { pathToFileURL } from 'url';
 import { getCurrentRuntime } from './runtime.js';
 import { formatInteractionPrompt } from './interaction.js';
 import { withChangeTracking } from './track-changes.js';
+import { resolveUnknownModel } from './model-resolution.js';
+import { detectAvailableCLIs } from '../llm.js';
 
 const require = createRequire(import.meta.url);
 
@@ -374,6 +376,23 @@ async function executeMDAgent(runtime, agentPath, name, params, options = {}) {
 
       const model = config.model || 'fast';
 
+      // Resolve model alias to actual model config for display
+      let resolvedModel = baseConfig.models?.[model];
+      if (!resolvedModel) {
+        // Auto-resolve unknown model (same logic as llm.js)
+        try {
+          resolvedModel = await resolveUnknownModel(model, baseConfig, runtime.workflowDir, {
+            availableCLIs: detectAvailableCLIs()
+          });
+          // Cache it for future use
+          if (!baseConfig.models) baseConfig.models = {};
+          baseConfig.models[model] = resolvedModel;
+          runtime.workflowConfig.models[model] = resolvedModel;
+        } catch {
+          resolvedModel = model; // Fallback to alias if resolution fails
+        }
+      }
+
       const fullPrompt = buildPrompt(context, {
         model,
         prompt: interpolatedPrompt,
@@ -381,7 +400,7 @@ async function executeMDAgent(runtime, agentPath, name, params, options = {}) {
         responseType: config.response
       });
 
-      await logAgentStart(runtime, name, fullPrompt);
+      await logAgentStart(runtime, name, fullPrompt, resolvedModel, model);
 
       console.log(`    Using model: ${model}`);
 
@@ -647,7 +666,7 @@ ${content}
   return response;
 }
 
-async function logAgentStart(runtime, name, prompt) {
+async function logAgentStart(runtime, name, prompt, model = null, modelAlias = null) {
   if (runtime._agentResumeFlags?.has(name)) {
     runtime._agentResumeFlags.delete(name);
     await runtime.prependHistory({
@@ -666,5 +685,13 @@ async function logAgentStart(runtime, name, prompt) {
     entry.prompt = prompt;
   }
 
+  if (model) {
+    entry.model = model;
+  }
+
+  if (modelAlias && modelAlias !== model) {
+    entry.modelAlias = modelAlias;
+  }
+
   await runtime.prependHistory(entry);
 }

package/lib/runtime/prompt.js

@@ -105,7 +105,7 @@ export async function askHuman(question, options = {}) {
     await runtime.prependHistory({
       event: 'PROMPT_ANSWERED',
       slug,
-      answer: normalizedAnswer.substring(0, 100) + (normalizedAnswer.length > 100 ? '...' : '')
+      answer: normalizedAnswer
     });
 
     return normalizedAnswer;

package/lib/runtime/runtime.js

@@ -87,7 +87,14 @@ export class WorkflowRuntime {
       // Full-auto mode (auto-select first option for choice interactions)
       fullAuto: false,
       maxQuickFixAttempts: 10,
-      autoSelectDelay: 20  // seconds before auto-selecting in full-auto mode
+      autoSelectDelay: 20,  // seconds before auto-selecting in full-auto mode
+      // CLI permission modes (configurable per tool)
+      cliPermissions: {
+        claude: 'acceptEdits',
+        gemini: 'auto_edit'
+      },
+      // Protected paths - prevents DELETION only (modifications allowed)
+      protectedPaths: []
     };
 
     // Load steering
@@ -384,6 +391,7 @@ export class WorkflowRuntime {
       const cfg = configModule.config || configModule.default || {};
       // Preserve CLI-set fullAuto (it takes precedence over config.js)
       const cliFullAuto = this.workflowConfig.fullAuto;
+      const defaultCliPermissions = { claude: 'acceptEdits', gemini: 'auto_edit' };
       this.workflowConfig = {
         models: cfg.models || {},
         apiKeys: cfg.apiKeys || {},
@@ -396,7 +404,11 @@ export class WorkflowRuntime {
         // 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
+        autoSelectDelay: cfg.autoSelectDelay ?? this.workflowConfig.autoSelectDelay,  // seconds before auto-selecting
+        // CLI permission modes (merge with defaults)
+        cliPermissions: { ...defaultCliPermissions, ...(cfg.cliPermissions || {}) },
+        // Protected paths - prevents DELETION only (modifications allowed)
+        protectedPaths: cfg.protectedPaths || []
       };
 
       // Import workflow module
@@ -585,6 +597,31 @@ export class WorkflowRuntime {
     }
   }
 
+  /**
+   * Handle config update from remote browser UI
+   * Called by RemoteClient when it receives a config_update message
+   */
+  handleRemoteConfigUpdate(config) {
+    if (config.fullAuto !== undefined) {
+      const wasFullAuto = this.workflowConfig.fullAuto;
+      this.workflowConfig.fullAuto = config.fullAuto;
+      if (wasFullAuto !== config.fullAuto) {
+        console.log(`${C.cyan}Remote: Full-auto mode ${config.fullAuto ? 'enabled' : 'disabled'}${C.reset}`);
+      }
+    }
+
+    if (config.autoSelectDelay !== undefined) {
+      this.workflowConfig.autoSelectDelay = config.autoSelectDelay;
+      console.log(`${C.dim}Remote: Auto-select delay set to ${config.autoSelectDelay}s${C.reset}`);
+    }
+
+    if (config.stop) {
+      console.log(`\n${C.yellow}${C.bold}Remote: Stop requested${C.reset}`);
+      // Trigger graceful shutdown
+      process.emit('SIGINT');
+    }
+  }
+
   /**
    * Read the user's response from an interaction file
    */
@@ -779,6 +816,9 @@ export class WorkflowRuntime {
       onInteractionResponse: (slug, targetKey, response) => {
         this.handleRemoteInteraction(slug, targetKey, response);
       },
+      onConfigUpdate: (config) => {
+        this.handleRemoteConfigUpdate(config);
+      },
       onStatusChange: (status) => {
         if (status === 'disconnected') {
           console.log(`${C.yellow}Remote: Connection lost, attempting to reconnect...${C.reset}`);
@@ -790,10 +830,14 @@ export class WorkflowRuntime {
 
     await this.remoteClient.connect();
 
-    // Send existing history if connected
+    // Send existing history if connected, including current config
     if (this.remoteClient.connected) {
       const history = this.loadHistory();
-      await this.remoteClient.sendSessionInit(history);
+      const config = {
+        fullAuto: this.workflowConfig.fullAuto || false,
+        autoSelectDelay: this.workflowConfig.autoSelectDelay ?? 20,
+      };
+      await this.remoteClient.sendSessionInit(history, config);
     }
 
     this.remoteEnabled = true;

package/lib/runtime/track-changes.js

@@ -7,6 +7,7 @@
  */
 
 import path from 'path';
+import { execSync } from 'child_process';
 import {
   captureBaseline,
   detectChanges,
@@ -38,9 +39,52 @@ export async function withChangeTracking(runtime, agentName, fn) {
   // Detect changes made during agent execution
   const changes = await detectChanges(projectRoot, baseline, ignorePatterns);
 
+  // Validate protected paths (only checks deletions)
+  const validation = validateProtectedPaths(runtime, changes);
+  if (!validation.valid) {
+    console.warn(`[protected-paths] Violations detected by agent '${agentName}':`);
+    validation.violations.forEach(v => console.warn(`  - ${v}`));
+    throw new Error(`Protected path violations: ${validation.violations.join(', ')}`);
+  }
+
   // Update fileTree with detected changes
   applyChangesToFileTree(runtime, changes, agentName);
 
+  // Log git diff to history when files change
+  if (changes.created.length || changes.modified.length || changes.deleted.length) {
+    try {
+      const diff = execSync('git diff HEAD', {
+        cwd: projectRoot,
+        encoding: 'utf-8',
+        maxBuffer: 1024 * 1024 // 1MB limit
+      }).trim();
+
+      if (diff) {
+        await runtime.prependHistory({
+          type: 'file_changes',
+          agent: agentName,
+          summary: {
+            created: changes.created.length,
+            modified: changes.modified.length,
+            deleted: changes.deleted.length
+          },
+          diff: diff.slice(0, 50000) // Truncate if too large
+        });
+      }
+    } catch (e) {
+      // Git diff failed, log summary only
+      await runtime.prependHistory({
+        type: 'file_changes',
+        agent: agentName,
+        summary: {
+          created: changes.created.length,
+          modified: changes.modified.length,
+          deleted: changes.deleted.length
+        }
+      });
+    }
+  }
+
   // Merge _files annotations if present (preserves existing data unless explicitly overwritten)
   if (result && typeof result === 'object' && Array.isArray(result._files)) {
     mergeAnnotations(runtime, result._files);
@@ -49,6 +93,46 @@ export async function withChangeTracking(runtime, agentName, fn) {
   return result;
 }
 
+/**
+ * Validate that protected paths were not deleted.
+ * Only checks for DELETIONS - modifications are allowed.
+ *
+ * @param {Object} runtime - The workflow runtime instance
+ * @param {Object} changes - Detected changes { created, modified, deleted, renamed }
+ * @returns {{ valid: boolean, violations: string[] }}
+ */
+export function validateProtectedPaths(runtime, changes) {
+  const protectedPaths = runtime.workflowConfig.protectedPaths || [];
+  const violations = [];
+
+  // Only check DELETED files - modifications are allowed
+  for (const deleted of changes.deleted || []) {
+    for (const pattern of protectedPaths) {
+      if (matchesPattern(deleted, pattern)) {
+        violations.push(`Cannot delete protected file: ${deleted}`);
+      }
+    }
+  }
+
+  return { valid: violations.length === 0, violations };
+}
+
+/**
+ * Simple pattern matching for protected paths.
+ * Supports exact match and prefix wildcards (e.g., '.env*' matches '.env', '.env.local')
+ */
+function matchesPattern(filePath, pattern) {
+  // Normalize both for comparison
+  const normalizedPath = filePath.replace(/\\/g, '/');
+  const normalizedPattern = pattern.replace(/\\/g, '/');
+
+  if (normalizedPattern.endsWith('*')) {
+    // Prefix wildcard: '.env*' matches '.env', '.env.local', etc.
+    return normalizedPath.startsWith(normalizedPattern.slice(0, -1));
+  }
+  return normalizedPath === normalizedPattern;
+}
+
 /**
  * Apply detected file changes to the runtime's fileTree.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-state-machine",
-  "version": "2.4.0",
+  "version": "2.6.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-writer.md → code-write.md}

@@ -1,6 +1,7 @@
 ---
 model: high
 format: json
+description: "Code phase: Implements the task by writing production code and tests"
 ---
 
 # Code Writer Agent
@@ -9,6 +10,11 @@ You are a senior software developer. Implement the task according to specificati
 
 ## Instructions
 
+**IMPORTANT: Use your file tools to create and write files directly to disk.** Do not embed code in JSON. Use your native file creation capabilities to:
+1. Create directories as needed
+2. Write each file with full production code
+3. Report what files you created
+
 Implement the task following these principles:
 
 **Code Quality:**
@@ -33,22 +39,14 @@ Implement the task following these principles:
 
 ## Output Format
 
-Return a valid JSON object:
+After writing all files to disk using your file tools, return a valid JSON object:
 
 {
   "implementation": {
     "summary": "Brief description of what was implemented",
-    "files": [
-      {
-        "path": "src/feature.js",
-        "purpose": "Main implementation",
-        "code": "// Full code content here\nfunction example() {\n  return 'hello';\n}"
-      },
-      {
-        "path": "src/feature.test.js",
-        "purpose": "Test file",
-        "code": "// Test code here\ndescribe('feature', () => {\n  it('works', () => {});\n});"
-      }
+    "filesWritten": [
+      {"path": "src/feature.js", "purpose": "Main implementation"},
+      {"path": "src/feature.test.js", "purpose": "Test file"}
     ],
     "dependencies": [
       {"name": "lodash", "version": "^4.17.21", "reason": "Utility functions"}
@@ -65,3 +63,11 @@ Return a valid JSON object:
 }
 
 Write production-quality code. This is not a prototype.
+
+## Safeguards
+
+**NEVER modify or remove:**
+- `.env` or `.env.*` files
+- The `agent-state-machine` dependency in `package.json`
+
+You may add new dependencies but must preserve existing critical ones.

package/templates/project-builder/agents/{assumptions-clarifier.md → intake-assumptions.md}

@@ -3,6 +3,7 @@ model: med
 format: json
 interaction: true
 response: choice
+description: "Intake phase: Validates technical and business assumptions before development"
 ---
 
 # Assumptions Clarifier Agent

package/templates/project-builder/agents/{requirements-clarifier.md → intake-requirements.md}

@@ -3,6 +3,7 @@ model: med
 format: json
 interaction: true
 response: choice
+description: "Intake phase: Gathers functional and non-functional requirements"
 ---
 
 # Requirements Clarifier Agent

package/templates/project-builder/agents/{scope-clarifier.md → intake-scope.md}

@@ -3,6 +3,7 @@ model: med
 format: json
 interaction: true
 response: choice
+description: "Intake phase: Clarifies project boundaries and scope before planning begins"
 ---
 
 # Scope Clarifier Agent

package/templates/project-builder/agents/{security-clarifier.md → intake-security.md}

@@ -3,6 +3,7 @@ model: med
 format: json
 interaction: true
 response: choice
+description: "Intake phase: Identifies security requirements and compliance needs upfront"
 ---
 
 # Security Clarifier Agent

package/templates/project-builder/agents/{roadmap-generator.md → plan-roadmap.md}

@@ -1,6 +1,7 @@
 ---
 model: high
 format: json
+description: "Planning phase: Generates phased development roadmap from gathered requirements"
 ---
 
 # Roadmap Generator Agent

package/templates/project-builder/agents/{task-planner.md → plan-tasks.md}

@@ -1,6 +1,7 @@
 ---
 model: high
 format: json
+description: "Planning phase: Breaks down a roadmap phase into actionable tasks"
 ---
 
 # Task Planner Agent

package/templates/project-builder/agents/post-code-fix.md

@@ -0,0 +1,59 @@
+---
+model: high
+format: json
+description: "Post-code phase: Fixes issues found during review or sanity checks"
+---
+
+# Code Fixer Agent
+
+You fix specific issues in existing code based on sanity check failures.
+
+## How to Fix
+
+**IMPORTANT: Use your file tools to read and write files directly.**
+
+1. Read the file(s) that need fixing using your file tools
+2. Analyze the error and identify the root cause
+3. Apply the fix by writing the corrected file back to disk
+4. Report what you fixed
+
+## 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
+- failedChecks: Failed checks with specific errors
+- filePaths: Paths to files that may need fixing
+
+## Output Format
+
+After fixing the files using your file tools, return:
+
+{
+  "analysis": {
+    "rootCauses": ["What caused each failure"],
+    "fixApproach": "Strategy for fixing"
+  },
+  "fixesApplied": [
+    {
+      "path": "src/feature.js",
+      "description": "Fixed the validation logic to handle edge case"
+    }
+  ],
+  "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-reviewer.md → post-code-review.md}

@@ -1,12 +1,17 @@
 ---
 model: high
 format: json
+description: "Post-code phase: Reviews implementation for quality and correctness"
 ---
 
 # Code Reviewer Agent
 
 You are a senior code reviewer. Review implementations for quality, correctness, and best practices.
 
+## How to Review
+
+**Use your file tools to read the files that need reviewing.** You will receive a list of file paths to review. Read each file's contents directly from disk to perform your review.
+
 ## Instructions
 
 Perform a thorough code review covering:
@@ -33,6 +38,11 @@ Perform a thorough code review covering:
 - Are tests meaningful (not just coverage padding)?
 - Are edge cases tested?
 
+## Input
+- task: Task definition with title and description
+- filesToReview: Array of file paths to review
+- implementationSummary: Brief description of what was implemented
+
 ## Output Format
 
 Return a valid JSON object: