agent-state-machine 2.1.1 → 2.1.3

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/lib/runtime/prompt.js

@@ -42,12 +42,12 @@ export async function askHuman(question, options = {}) {
     event: 'PROMPT_REQUESTED',
     slug,
     targetKey: memoryKey,
-    question: prompt,
     type: interaction?.type || 'text',
     prompt,
     options: interaction?.options,
     allowCustom: interaction?.allowCustom,
     multiSelect: interaction?.multiSelect,
+    placeholder: interaction?.placeholder,
     validation: interaction?.validation,
     confirmLabel: interaction?.confirmLabel,
     cancelLabel: interaction?.cancelLabel,
@@ -57,7 +57,7 @@ export async function askHuman(question, options = {}) {
   // Check if we're in TTY mode (interactive terminal)
   if (process.stdin.isTTY && process.stdout.isTTY) {
     // Interactive mode - prompt directly, with remote support
-    const answer = await askQuestionWithRemote(runtime, question, slug, memoryKey);
+    const answer = await askQuestionWithRemote(runtime, question, slug, memoryKey, interaction);
     console.log('');
 
     const normalizedAnswer = normalizePromptAnswer(answer);
@@ -115,7 +115,7 @@ ${question}
  * Interactive terminal question with remote support
  * Allows both local TTY input and remote browser responses
  */
-function askQuestionWithRemote(runtime, question, slug, memoryKey) {
+function askQuestionWithRemote(runtime, question, slug, memoryKey, interaction = null) {
   return new Promise((resolve) => {
     let resolved = false;
 
@@ -146,13 +146,33 @@ function askQuestionWithRemote(runtime, question, slug, memoryKey) {
     });
 
     // Show remote URL if available
-    let prompt = `\n${C.cyan}${C.bold}${question}${C.reset}`;
+    let promptText = `\n${C.cyan}${C.bold}${question}${C.reset}`;
+    
+    // Show placeholder if provided
+    if (interaction?.placeholder) {
+      promptText += `\n${C.dim}(e.g., ${interaction.placeholder})${C.reset}`;
+    }
+    
+    // Show validation hints if provided
+    if (interaction?.validation) {
+      const hints = [];
+      if (interaction.validation.minLength) {
+        hints.push(`min ${interaction.validation.minLength} chars`);
+      }
+      if (interaction.validation.maxLength) {
+        hints.push(`max ${interaction.validation.maxLength} chars`);
+      }
+      if (hints.length > 0) {
+        promptText += `\n${C.dim}[${hints.join(', ')}]${C.reset}`;
+      }
+    }
+    
     if (runtime.remoteEnabled && runtime.remoteUrl) {
-      prompt += `\n${C.dim}(Remote: ${runtime.remoteUrl})${C.reset}`;
+      promptText += `\n${C.dim}(Remote: ${runtime.remoteUrl})${C.reset}`;
     }
-    prompt += `\n${C.yellow}> ${C.reset}`;
+    promptText += `\n${C.yellow}> ${C.reset}`;
 
-    rl.question(prompt, (answer) => {
+    rl.question(promptText, (answer) => {
       if (resolved) return;
       cleanup();
       rl.close();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-state-machine",
-  "version": "2.1.1",
+  "version": "2.1.3",
   "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/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}` });
   }
 }