agent-state-machine 2.1.2 → 2.1.4

package/lib/llm.js

@@ -39,6 +39,81 @@ export function detectAvailableCLIs() {
   return available;
 }
 
+/**
+ * Get response format instructions based on response type
+ * Used by buildPrompt to inject appropriate interaction format instructions
+ */
+function getResponseFormatInstructions(responseType) {
+  if (responseType === 'choice') {
+    return `# Response Format
+
+When you need user input, respond with a structured choice:
+
+{
+  "interact": {
+    "type": "choice",
+    "slug": "unique-slug",
+    "prompt": "Your question here?",
+    "options": [
+      { "key": "key1", "label": "Display Label", "description": "Help text" }
+    ],
+    "multiSelect": false,
+    "allowCustom": true
+  }
+}
+
+Rules:
+- slug: unique identifier (e.g., "scope-platform")
+- options: 2-5 choices with key, label, and optional description
+- multiSelect: true allows selecting multiple options
+- allowCustom: true shows "Other" for free-text input
+- Ask ONE question at a time
+`;
+  }
+
+  if (responseType === 'confirm') {
+    return `# Response Format
+
+When you need user confirmation, respond with:
+
+{
+  "interact": {
+    "type": "confirm",
+    "slug": "unique-slug",
+    "prompt": "Are you sure about X?",
+    "confirmLabel": "Yes, proceed",
+    "cancelLabel": "No, cancel"
+  }
+}
+`;
+  }
+
+  if (responseType === 'text') {
+    return `# Response Format
+
+When you need text input, respond with:
+
+{
+  "interact": {
+    "type": "text",
+    "slug": "unique-slug",
+    "prompt": "Please describe X:",
+    "placeholder": "Enter details...",
+    "validation": { "minLength": 10 }
+  }
+}
+`;
+  }
+
+  // Default: basic interact format
+  return `# Interaction Format
+IF YOU NEED TO ASK THE USER A QUESTION OR REQUEST INPUT, RESPOND WITH EXACTLY:
+{ "interact": "your question here" }
+
+Only use this format when you genuinely need user input to proceed.
+`;
+}
+
 /**
  * Build the full prompt with steering and context
  */
@@ -65,11 +140,9 @@ export function buildPrompt(context, options) {
     }
   }
 
-  // Add interaction format instruction
-  parts.push('# Interaction Format\n');
-  parts.push('IF YOU NEED TO ASK THE USER A QUESTION OR REQUEST INPUT, RESPOND WITH EXACTLY:\n');
-  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 response format instructions (based on responseType option)
+  parts.push(getResponseFormatInstructions(options.responseType));
+  parts.push('\n---\n');
 
   // Add global steering if available (always first)
   if (context._steering?.global) {

package/lib/remote/client.js

@@ -193,7 +193,7 @@ export class RemoteClient {
 
     await this.send({
       ...event,
-      type: 'event',  // Must come after spread to not be overwritten by event.type
+      _action: 'event',  // Use _action for message routing to preserve event.type (interaction type)
       sessionToken: this.sessionToken,
     });
   }

package/lib/runtime/agent.js

@@ -260,7 +260,8 @@ async function executeMDAgent(runtime, agentPath, name, params, options = {}) {
     const fullPrompt = buildPrompt(context, {
       model,
       prompt: interpolatedPrompt,
-      includeContext: config.includeContext !== 'false'
+      includeContext: config.includeContext !== 'false',
+      responseType: config.response
     });
 
     await logAgentStart(runtime, name, fullPrompt);
@@ -270,7 +271,8 @@ async function executeMDAgent(runtime, agentPath, name, params, options = {}) {
     response = await llm(context, {
       model: model,
       prompt: interpolatedPrompt,
-      includeContext: config.includeContext !== 'false'
+      includeContext: config.includeContext !== 'false',
+      responseType: config.response
     });
 
     // Parse output based on format
@@ -297,17 +299,26 @@ async function executeMDAgent(runtime, agentPath, name, params, options = {}) {
   }
 
   // Check for interaction request
-  const explicitInteraction =
-    config.format === 'interaction' ||
-    config.interaction === 'true' ||
-    (typeof config.interaction === 'string' && config.interaction.length > 0);
-
   const parsedInteraction = parseInteractionRequest(response.text);
   const structuredInteraction =
     config.autoInteract !== 'false' && parsedInteraction.isInteraction;
 
+  // Check if agent returned an 'interact' object in its JSON response
+  const hasInteractKey = output && typeof output === 'object' && output.interact;
+
+  // Explicit interaction mode (format: interaction OR interaction: true)
+  // But only trigger if agent actually wants to interact (has interact key or parsed interaction)
+  const explicitInteraction =
+    config.format === 'interaction' ||
+    ((config.interaction === 'true' || (typeof config.interaction === 'string' && config.interaction.length > 0)) &&
+      (hasInteractKey || structuredInteraction));
+
   if (explicitInteraction || structuredInteraction) {
+    // Use interact object if present, otherwise fall back to parsed/raw
+    const interactionData = hasInteractKey ? output.interact : (structuredInteraction ? parsedInteraction : null);
+    
     const slugRaw =
+      interactionData?.slug ||
       (typeof config.interaction === 'string' && config.interaction !== 'true'
         ? config.interaction
         : null) ||
@@ -317,13 +328,19 @@ async function executeMDAgent(runtime, agentPath, name, params, options = {}) {
 
     const slug = sanitizeSlug(slugRaw);
     const targetKey = config.interactionKey || outputKey || slug;
-    const interactionContent = structuredInteraction ? parsedInteraction.question : response.text;
-
-    const userResponse = await handleInteraction(runtime, {
+    
+    // Build interaction object with full metadata
+    const interactionObj = hasInteractKey ? {
+      ...output.interact,
+      slug,
+      targetKey
+    } : {
       slug,
       targetKey,
-      content: interactionContent
-    }, name);
+      content: structuredInteraction ? parsedInteraction.question : response.text
+    };
+
+    const userResponse = await handleInteraction(runtime, interactionObj, name);
 
     // Return the user's response as the agent result
     if (outputKey) {
@@ -479,12 +496,12 @@ ${content}
     event: 'INTERACTION_REQUESTED',
     slug,
     targetKey,
-    question: prompt || content,
     type: interaction.type || 'text',
-    prompt,
+    prompt: prompt || content,
     options: interaction.options,
     allowCustom: interaction.allowCustom,
     multiSelect: interaction.multiSelect,
+    placeholder: interaction.placeholder,
     validation: interaction.validation,
     confirmLabel: interaction.confirmLabel,
     cancelLabel: interaction.cancelLabel,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-state-machine",
-  "version": "2.1.2",
+  "version": "2.1.4",
   "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/assumptions-clarifier.md

@@ -2,6 +2,7 @@
 model: med
 format: json
 interaction: true
+response: choice
 ---
 
 # Assumptions Clarifier Agent
@@ -22,26 +23,22 @@ Identify implicit assumptions that could impact the project. Consider:
 
 **Technical Assumptions:**
 - Technology stack preferences
-- Development environment
 - Existing infrastructure
 - Third-party dependencies
 
 **Business Assumptions:**
 - Timeline expectations
-- Budget constraints
 - Team composition/skills
-- Stakeholder availability
 
 **Domain Assumptions:**
 - Industry regulations
 - Compliance requirements
-- Domain-specific constraints
 
-If assumptions need validation, ask using the interact format:
-
-{
-  "interact": "Please confirm or clarify these assumptions:\n\n1. Technology Stack:\n   - A: I have a preferred stack (specify below)\n   - B: Use best practices for the project type\n   - C: Must integrate with existing system\n\n2. Development Timeline:\n   - A: Prototype/MVP focus (speed over polish)\n   - B: Production-ready from start\n   - C: Iterative releases planned\n\n3. Existing Codebase:\n   - A: Starting from scratch\n   - B: Building on existing code\n   - C: Migrating from legacy system\n\nPlease respond with your choices and details:"
-}
+If assumptions need validation, ask ONE question. Example slugs:
+- "assume-stack": Technology stack preference
+- "assume-timeline": Development approach (MVP, production-ready, iterative)
+- "assume-codebase": Starting point (greenfield, existing code, migration)
+- "assume-infra": Infrastructure constraints
 
 If assumptions are clear, return:
 

package/templates/project-builder/agents/requirements-clarifier.md

@@ -2,6 +2,7 @@
 model: med
 format: json
 interaction: true
+response: choice
 ---
 
 # Requirements Clarifier Agent
@@ -23,19 +24,16 @@ Based on the project description and scope, identify requirements that need clar
 - Core features and user stories
 - Data models and relationships
 - User workflows and interactions
-- Input/output specifications
 
 **Non-Functional Requirements:**
 - Performance expectations
-- Scalability needs
-- Reliability/uptime requirements
-- Accessibility requirements
+- Scalability and reliability needs
 
-If requirements need clarification, ask using the interact format:
-
-{
-  "interact": "Please clarify the following requirements:\n\n1. Data Storage:\n   - A: Local storage only\n   - B: Cloud database required\n   - C: Hybrid (local + cloud sync)\n\n2. Authentication:\n   - A: No authentication needed\n   - B: Simple username/password\n   - C: OAuth/SSO integration\n   - D: Multi-factor authentication\n\n[Add more questions as needed]\n\nPlease respond with your choices and details:"
-}
+If requirements need clarification, ask ONE question. Example slugs:
+- "req-storage": Data storage approach (local, cloud, hybrid)
+- "req-auth": Authentication method (none, basic, OAuth, MFA)
+- "req-offline": Offline capability needs
+- "req-realtime": Real-time features needed
 
 If requirements are clear, return:
 

package/templates/project-builder/agents/scope-clarifier.md

@@ -2,6 +2,7 @@
 model: med
 format: json
 interaction: true
+response: choice
 ---
 
 # Scope Clarifier Agent
@@ -23,11 +24,10 @@ Analyze the project description and determine if the scope is clear. Consider:
 - Platform/environment constraints
 - Integration requirements
 
-If the scope is unclear or ambiguous, ask clarifying questions using the interact format:
-
-{
-  "interact": "Please clarify the following scope questions:\n\n1. Target Platform:\n   - A: Web application\n   - B: Mobile app\n   - C: Desktop application\n   - D: API/Backend service\n\n2. User Scale:\n   - A: Single user / personal project\n   - B: Small team (< 10 users)\n   - C: Medium scale (10-1000 users)\n   - D: Large scale (1000+ users)\n\n[Add more questions as needed]\n\nPlease respond with your choices (e.g., '1A, 2C') and any additional details:"
-}
+If the scope is unclear, ask ONE clarifying question. Example slugs:
+- "scope-platform": Target platform (web, mobile, desktop, API)
+- "scope-scale": User scale (personal, team, enterprise)
+- "scope-integrations": External integrations needed
 
 If the scope is sufficiently clear, return the scope summary:
 

package/templates/project-builder/agents/security-clarifier.md

@@ -2,6 +2,7 @@
 model: med
 format: json
 interaction: true
+response: choice
 ---
 
 # Security Clarifier Agent
@@ -24,28 +25,20 @@ Analyze the project for security implications. Consider:
 **Data Security:**
 - Sensitive data handling (PII, financial, health)
 - Data encryption requirements
-- Data retention policies
 
 **Access Control:**
 - Authentication requirements
 - Authorization model
-- Role-based access needs
 
 **Compliance:**
 - Regulatory requirements (GDPR, HIPAA, PCI-DSS)
-- Industry standards
 - Audit requirements
 
-**Infrastructure:**
-- Network security
-- API security
-- Deployment security
-
-If security requirements need clarification, ask using the interact format:
-
-{
-  "interact": "Please clarify security requirements:\n\n1. Sensitive Data:\n   - A: No sensitive data handled\n   - B: Personal information (names, emails)\n   - C: Financial data (payments, transactions)\n   - D: Health/medical data\n   - E: Other regulated data\n\n2. Compliance Requirements:\n   - A: No specific compliance needed\n   - B: GDPR (EU data protection)\n   - C: HIPAA (healthcare)\n   - D: PCI-DSS (payment cards)\n   - E: SOC2 / enterprise security\n\n3. Authentication Level:\n   - A: Basic (username/password)\n   - B: Enhanced (MFA, SSO)\n   - C: Enterprise (LDAP, SAML)\n\nPlease respond with your choices and details:"
-}
+If security requirements need clarification, ask ONE question. Example slugs:
+- "sec-data": Sensitive data types handled (none, PII, financial, health)
+- "sec-compliance": Compliance requirements (GDPR, HIPAA, PCI-DSS, SOC2)
+- "sec-auth": Authentication level (basic, MFA, SSO, enterprise)
+- "sec-audit": Audit/logging requirements
 
 If security requirements are clear, return:
 

package/templates/project-builder/config.js

@@ -8,6 +8,5 @@ export const config = {
     gemini: process.env.GEMINI_API_KEY,
     anthropic: process.env.ANTHROPIC_API_KEY,
     openai: process.env.OPENAI_API_KEY,
-  },
-  remotePath: "TczrLmUecnqZPpPhBTrvU374CGlfzDfINrr0eN0nMgQ",
+  }
 };

package/vercel-server/api/events/[token].js

@@ -57,13 +57,13 @@ export default async function handler(req, res) {
 
     // Track current position for polling new events
     let lastEventIndex = await getEventsLength(token);
+    let pollCount = 0;
 
     const pollInterval = setInterval(async () => {
       try {
-        // Refresh session TTL
-        await refreshSession(token);
+        pollCount++;
 
-        // Check for new events
+        // Check for new events (most important, do this every poll)
         const newLength = await getEventsLength(token);
 
         if (newLength > lastEventIndex) {
@@ -82,18 +82,23 @@ export default async function handler(req, res) {
           lastEventIndex = newLength;
         }
 
-        // Check CLI status
-        const updatedSession = await getSession(token);
-        if (updatedSession && updatedSession.cliConnected !== session.cliConnected) {
-          session.cliConnected = updatedSession.cliConnected;
-          res.write(`data: ${JSON.stringify({
-            type: updatedSession.cliConnected ? 'cli_reconnected' : 'cli_disconnected',
-          })}\n\n`);
+        // Only check CLI status and refresh session every 5th poll (~15 seconds)
+        // This reduces Redis calls significantly
+        if (pollCount % 5 === 0) {
+          await refreshSession(token);
+
+          const updatedSession = await getSession(token);
+          if (updatedSession && updatedSession.cliConnected !== session.cliConnected) {
+            session.cliConnected = updatedSession.cliConnected;
+            res.write(`data: ${JSON.stringify({
+              type: updatedSession.cliConnected ? 'cli_reconnected' : 'cli_disconnected',
+            })}\n\n`);
+          }
         }
       } catch (err) {
         console.error('Error polling events:', err);
       }
-    }, 1000); // Poll every 1 second for faster updates
+    }, 3000); // Poll every 3 seconds (was 1 second) - 3x reduction
 
     // Clean up on client disconnect
     req.on('close', () => {

package/vercel-server/api/ws/cli.js

@@ -44,14 +44,16 @@ export default async function handler(req, res) {
  */
 async function handlePost(req, res) {
   const body = typeof req.body === 'string' ? JSON.parse(req.body) : req.body;
-  const { type, sessionToken } = body;
+  const { sessionToken } = body;
+  // Support both _action (new) and type (legacy) for message routing
+  const action = body._action || body.type;
 
   if (!sessionToken) {
     return res.status(400).json({ error: 'Missing sessionToken' });
   }
 
   try {
-    switch (type) {
+    switch (action) {
       case 'session_init': {
         const { workflowName, history } = body;
 
@@ -89,9 +91,9 @@ async function handlePost(req, res) {
           ...eventData,
         };
 
-        // Remove sessionToken and type from event data
+        // Remove routing fields, preserve type (interaction type like 'choice')
         delete historyEvent.sessionToken;
-        delete historyEvent.type;
+        delete historyEvent._action;
 
         // Add to events list (single source of truth)
         await addEvent(sessionToken, historyEvent);
@@ -125,7 +127,7 @@ async function handlePost(req, res) {
       }
 
       default:
-        return res.status(400).json({ error: `Unknown message type: ${type}` });
+        return res.status(400).json({ error: `Unknown action: ${action}` });
     }
   } catch (err) {
     console.error('Error handling CLI message:', err);
@@ -135,6 +137,7 @@ async function handlePost(req, res) {
 
 /**
  * Handle GET requests - long-poll for interaction responses
+ * Uses efficient polling with 5-second intervals (Upstash doesn't support BLPOP)
  */
 async function handleGet(req, res) {
   const { token, timeout = '30000' } = req.query;
@@ -148,16 +151,15 @@ async function handleGet(req, res) {
     return res.status(404).json({ error: 'Session not found' });
   }
 
-  const timeoutMs = Math.min(parseInt(timeout, 10), 55000); // Max 55s for Vercel
+  // Max 50s for Vercel (leave buffer for response)
+  const timeoutMs = Math.min(parseInt(timeout, 10), 50000);
   const channel = KEYS.interactions(token);
-
-  // Check for pending interactions using a list
   const pendingKey = `${channel}:pending`;
 
   try {
-    // Try to get a pending interaction
     const startTime = Date.now();
 
+    // Poll every 5 seconds (10 calls per 50s timeout vs 50 calls before)
     while (Date.now() - startTime < timeoutMs) {
       const pending = await redis.lpop(pendingKey);
 
@@ -169,8 +171,8 @@ async function handleGet(req, res) {
         });
       }
 
-      // Wait before checking again
-      await new Promise((resolve) => setTimeout(resolve, 1000));
+      // Wait 5 seconds before checking again (was 1 second)
+      await new Promise((resolve) => setTimeout(resolve, 5000));
     }
 
     // Timeout - no interaction received

package/vercel-server/local-server.js

@@ -112,13 +112,15 @@ function sendJson(res, status, data) {
  */
 async function handleCliPost(req, res) {
   const body = await parseBody(req);
-  const { type, sessionToken } = body;
+  const { sessionToken } = body;
+  // Support both _action (new) and type (legacy) for message routing
+  const action = body._action || body.type;
 
   if (!sessionToken) {
     return sendJson(res, 400, { error: 'Missing sessionToken' });
   }
 
-  switch (type) {
+  switch (action) {
     case 'session_init': {
       const { workflowName, history } = body;
       createSession(sessionToken, { workflowName, history });
@@ -152,7 +154,7 @@ async function handleCliPost(req, res) {
         ...eventData,
       };
       delete historyEvent.sessionToken;
-      delete historyEvent.type;
+      delete historyEvent._action;  // Remove routing field, preserve type (interaction type)
 
       // Add to history
       session.history.unshift(historyEvent);
@@ -179,7 +181,7 @@ async function handleCliPost(req, res) {
     }
 
     default:
-      return sendJson(res, 400, { error: `Unknown type: ${type}` });
+      return sendJson(res, 400, { error: `Unknown action: ${action}` });
   }
 }