agent-state-machine 2.0.15 → 2.1.1

package/lib/runtime/interaction.js

@@ -0,0 +1,304 @@
+/**
+ * Interaction Schema and Helpers
+ *
+ * Provides structured interaction types (choice, text, confirm) for human-in-the-loop workflows.
+ */
+
+// Default schema for interactions
+export const InteractionSchema = {
+  type: 'text',
+  slug: '',
+  prompt: '',
+  options: [],
+  allowCustom: true,
+  multiSelect: false,
+  placeholder: '',
+  validation: {
+    minLength: 0,
+    maxLength: 0,
+    pattern: ''
+  },
+  confirmLabel: 'Confirm',
+  cancelLabel: 'Cancel',
+  default: '',
+  context: {}
+};
+
+// Default schema for interaction responses
+export const InteractionResponseSchema = {
+  slug: '',
+  selectedKey: '',
+  selectedKeys: [],
+  text: '',
+  confirmed: false,
+  raw: '',
+  interpreted: false,
+  isCustom: false,
+  customText: ''
+};
+
+/**
+ * Normalize an interaction object by merging with defaults
+ */
+export function normalizeInteraction(interaction) {
+  if (!interaction || typeof interaction !== 'object') return null;
+  return {
+    ...InteractionSchema,
+    ...interaction,
+    validation: {
+      ...InteractionSchema.validation,
+      ...(interaction.validation || {})
+    }
+  };
+}
+
+/**
+ * Validate an interaction object
+ */
+export function validateInteraction(interaction) {
+  const errors = [];
+  if (!interaction || typeof interaction !== 'object') {
+    return { valid: false, errors: ['Interaction must be an object'] };
+  }
+  if (!interaction.type) errors.push('Missing type');
+  if (!interaction.slug) errors.push('Missing slug');
+  if (!interaction.prompt) errors.push('Missing prompt');
+  if (interaction.type === 'choice' && (!Array.isArray(interaction.options) || interaction.options.length === 0)) {
+    errors.push('Choice interaction must include options');
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Normalize an interaction response object
+ */
+export function normalizeInteractionResponse(response) {
+  if (!response || typeof response !== 'object') return null;
+  return {
+    ...InteractionResponseSchema,
+    ...response
+  };
+}
+
+/**
+ * Validate an interaction response
+ */
+export function validateInteractionResponse(response) {
+  const errors = [];
+  if (!response || typeof response !== 'object') {
+    return { valid: false, errors: ['Response must be an object'] };
+  }
+  if (!('raw' in response)) errors.push('Missing raw response');
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Create an interaction object with defaults
+ */
+export function createInteraction(type, slug, options = {}) {
+  return normalizeInteraction({
+    type,
+    slug,
+    ...options
+  });
+}
+
+/**
+ * Format an interaction as a human-readable prompt string
+ */
+export function formatInteractionPrompt(interaction) {
+  const prompt = String(interaction?.prompt || interaction?.question || interaction?.content || '').trim();
+  const lines = [];
+
+  if (prompt) lines.push(prompt);
+
+  if (interaction?.type === 'choice' && Array.isArray(interaction.options)) {
+    lines.push('', 'Options:');
+    interaction.options.forEach((opt, index) => {
+      const letter = String.fromCharCode(65 + index);
+      const label = opt.label || opt.key || `Option ${index + 1}`;
+      const desc = opt.description ? ` - ${opt.description}` : '';
+      lines.push(`- ${letter}: ${label}${desc}`);
+    });
+    if (interaction.allowCustom) {
+      lines.push('- Other: Provide a custom response');
+    }
+  }
+
+  if (interaction?.type === 'confirm') {
+    const confirmLabel = interaction.confirmLabel || 'Confirm';
+    const cancelLabel = interaction.cancelLabel || 'Cancel';
+    lines.push('', 'Options:');
+    lines.push(`- A: ${confirmLabel}`);
+    lines.push(`- B: ${cancelLabel}`);
+  }
+
+  return lines.join('\n').trim();
+}
+
+/**
+ * Match a single-select response against options
+ * Returns the matched option key/label, or null if no match
+ */
+export function matchSingleSelect(options, input) {
+  const lower = String(input || '').toLowerCase().trim();
+
+  for (let i = 0; i < options.length; i += 1) {
+    const opt = options[i];
+    const letter = String.fromCharCode(65 + i).toLowerCase();
+    const key = String(opt.key || '').toLowerCase();
+    const label = String(opt.label || '').toLowerCase();
+    const letterRegex = new RegExp(`^${letter}(\\s|[-:.)\\]])`, 'i');
+
+    if (
+      lower === letter ||
+      letterRegex.test(lower) ||
+      lower === key ||
+      lower === label ||
+      lower.startsWith(`${label}:`) ||
+      lower.startsWith(`${label} -`)
+    ) {
+      return opt.key || opt.label || letter.toUpperCase();
+    }
+  }
+  return null;
+}
+
+/**
+ * Match a multi-select response against options
+ * Returns array of matched option keys/labels
+ */
+export function matchMultiSelect(options, input) {
+  const lower = String(input || '').toLowerCase().trim();
+  const tokens = lower.split(/[,\s]+/).filter(Boolean);
+  const selections = new Set();
+
+  // Match letter patterns like "a:", "b)", "c -"
+  const letterMatches = lower.matchAll(/(^|[\s,])([a-z])\s*[-:.)\]]/g);
+  for (const match of letterMatches) {
+    const letter = match[2];
+    const index = letter.charCodeAt(0) - 97;
+    if (index >= 0 && index < options.length) {
+      const opt = options[index];
+      selections.add(opt.key || opt.label || letter.toUpperCase());
+    }
+  }
+
+  // Match tokens against keys/labels
+  tokens.forEach((token) => {
+    for (let i = 0; i < options.length; i += 1) {
+      const opt = options[i];
+      const letter = String.fromCharCode(65 + i).toLowerCase();
+      const key = String(opt.key || '').toLowerCase();
+      const label = String(opt.label || '').toLowerCase();
+      if (token === letter || token === key || token === label) {
+        selections.add(opt.key || opt.label || letter.toUpperCase());
+      }
+    }
+  });
+
+  return Array.from(selections);
+}
+
+/**
+ * Parse a raw response string into a structured response object
+ *
+ * @param {object} interaction - The interaction schema
+ * @param {string|object} rawResponse - The raw user response
+ * @param {function} [interpreter] - Optional async function to interpret ambiguous responses
+ * @returns {object} Structured response object
+ */
+export async function parseInteractionResponse(interaction, rawResponse, interpreter = null) {
+  const normalized = normalizeInteraction(interaction);
+  if (!normalized) return { raw: String(rawResponse ?? '') };
+
+  // If already an object, normalize it
+  if (rawResponse && typeof rawResponse === 'object') {
+    return normalizeInteractionResponse({
+      ...rawResponse,
+      raw: rawResponse.raw ?? rawResponse.text ?? ''
+    });
+  }
+
+  const raw = String(rawResponse ?? '').trim();
+
+  // Text type - just return the text
+  if (normalized.type === 'text') {
+    return { text: raw, raw };
+  }
+
+  // Confirm type - check for yes/no patterns
+  if (normalized.type === 'confirm') {
+    const lower = raw.toLowerCase();
+    const confirmLabel = (normalized.confirmLabel || 'confirm').toLowerCase();
+    const cancelLabel = (normalized.cancelLabel || 'cancel').toLowerCase();
+
+    const confirmed = lower.startsWith('y') || lower.startsWith('a') ||
+                      lower.startsWith('confirm') || lower === confirmLabel;
+    const cancelled = lower.startsWith('n') || lower.startsWith('b') ||
+                      lower.startsWith('cancel') || lower === cancelLabel;
+
+    if (confirmed || cancelled) {
+      return { confirmed, raw };
+    }
+
+    // Try interpreter if provided
+    if (interpreter) {
+      const interpreted = await tryInterpreter(interpreter, normalized, raw);
+      if (interpreted) return interpreted;
+    }
+
+    // Default to not confirmed for ambiguous responses
+    return { confirmed: false, raw };
+  }
+
+  // Choice type - match against options
+  if (normalized.type === 'choice') {
+    const options = normalized.options || [];
+
+    if (normalized.multiSelect) {
+      const selectedKeys = matchMultiSelect(options, raw);
+      if (selectedKeys.length > 0) {
+        return { selectedKeys, raw };
+      }
+    } else {
+      const selectedKey = matchSingleSelect(options, raw);
+      if (selectedKey) {
+        return { selectedKey, raw };
+      }
+    }
+
+    // Try interpreter if provided
+    if (interpreter) {
+      const interpreted = await tryInterpreter(interpreter, normalized, raw);
+      if (interpreted) return interpreted;
+    }
+
+    // Treat as custom response if allowed
+    if (normalized.allowCustom !== false) {
+      return { isCustom: true, customText: raw, raw };
+    }
+  }
+
+  return { raw };
+}
+
+/**
+ * Helper to safely call the interpreter function
+ */
+async function tryInterpreter(interpreter, interaction, raw) {
+  try {
+    const result = await interpreter(interaction, raw);
+    if (result && typeof result === 'object') {
+      if (result.selectedKey || result.selectedKeys?.length || result.confirmed !== undefined) {
+        return { ...result, raw, interpreted: true };
+      }
+      if (result.isCustom && interaction.allowCustom !== false) {
+        return { ...result, raw, interpreted: true };
+      }
+    }
+  } catch (error) {
+    // Silently fail - caller can handle uninterpreted responses
+  }
+  return null;
+}

package/lib/runtime/prompt.js

@@ -35,12 +35,23 @@ export async function askHuman(question, options = {}) {
 
   const slug = options.slug || generateSlug(question);
   const memoryKey = `_interaction_${slug}`;
+  const interaction = options.interaction || null;
+  const prompt = interaction?.prompt || question;
 
-  runtime.prependHistory({
+  await runtime.prependHistory({
     event: 'PROMPT_REQUESTED',
     slug,
     targetKey: memoryKey,
-    question
+    question: prompt,
+    type: interaction?.type || 'text',
+    prompt,
+    options: interaction?.options,
+    allowCustom: interaction?.allowCustom,
+    multiSelect: interaction?.multiSelect,
+    validation: interaction?.validation,
+    confirmLabel: interaction?.confirmLabel,
+    cancelLabel: interaction?.cancelLabel,
+    context: interaction?.context
   });
 
   // Check if we're in TTY mode (interactive terminal)
@@ -49,17 +60,19 @@ export async function askHuman(question, options = {}) {
     const answer = await askQuestionWithRemote(runtime, question, slug, memoryKey);
     console.log('');
 
+    const normalizedAnswer = normalizePromptAnswer(answer);
+
     // Save the response to memory
-    runtime._rawMemory[memoryKey] = answer;
+    runtime._rawMemory[memoryKey] = normalizedAnswer;
     runtime.persist();
 
-    runtime.prependHistory({
+    await runtime.prependHistory({
       event: 'PROMPT_ANSWERED',
       slug,
-      answer: answer.substring(0, 100) + (answer.length > 100 ? '...' : '')
+      answer: normalizedAnswer.substring(0, 100) + (normalizedAnswer.length > 100 ? '...' : '')
     });
 
-    return answer;
+    return normalizedAnswer;
   }
 
   // Non-TTY mode - create interaction file and wait inline
@@ -73,7 +86,7 @@ ${question}
 
   fs.writeFileSync(interactionFile, fileContent);
 
-  runtime.prependHistory({
+  await runtime.prependHistory({
     event: 'INTERACTION_REQUESTED',
     slug,
     targetKey: memoryKey,
@@ -84,16 +97,18 @@ ${question}
   // Block and wait for user input (instead of throwing)
   const answer = await runtime.waitForInteraction(interactionFile, slug, memoryKey);
 
-  runtime._rawMemory[memoryKey] = answer;
+  const normalizedAnswer = normalizePromptAnswer(answer);
+
+  runtime._rawMemory[memoryKey] = normalizedAnswer;
   runtime.persist();
 
-  runtime.prependHistory({
+  await runtime.prependHistory({
     event: 'PROMPT_ANSWERED',
     slug,
-    answer: answer.substring(0, 100) + (answer.length > 100 ? '...' : '')
+    answer: normalizedAnswer.substring(0, 100) + (normalizedAnswer.length > 100 ? '...' : '')
   });
 
-  return answer;
+  return normalizedAnswer;
 }
 
 /**
@@ -173,4 +188,16 @@ function generateSlug(question) {
     .replace(/[^a-z0-9]+/g, '-')
     .replace(/^-+|-+$/g, '')
     .substring(0, 30);
-}
+}
+
+function normalizePromptAnswer(answer) {
+  if (typeof answer === 'string') return answer;
+  if (answer && typeof answer === 'object') {
+    if (typeof answer.raw === 'string') return answer.raw;
+    if (typeof answer.text === 'string') return answer.text;
+    if (typeof answer.selectedKey === 'string') return answer.selectedKey;
+    if (Array.isArray(answer.selectedKeys)) return answer.selectedKeys.join(', ');
+    if (typeof answer.confirmed === 'boolean') return answer.confirmed ? 'confirm' : 'cancel';
+  }
+  return String(answer ?? '');
+}

package/lib/runtime/runtime.js

@@ -88,7 +88,6 @@ 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 = [];
@@ -197,7 +196,7 @@ export class WorkflowRuntime {
   /**
    * Prepend an event to history.jsonl (newest first)
    */
-  prependHistory(event) {
+  async prependHistory(event) {
     const entry = {
       timestamp: new Date().toISOString(),
       ...event
@@ -217,7 +216,7 @@ export class WorkflowRuntime {
 
     // Forward to remote if connected
     if (this.remoteClient && this.remoteEnabled) {
-      this.remoteClient.sendEvent(entry);
+      await this.remoteClient.sendEvent(entry);
     }
   }
 
@@ -305,7 +304,7 @@ export class WorkflowRuntime {
       if (!this.startedAt) this.startedAt = new Date().toISOString();
       this.persist();
 
-      this.prependHistory({ event: 'WORKFLOW_STARTED' });
+      await this.prependHistory({ event: 'WORKFLOW_STARTED' });
 
       const configPath = path.join(this.workflowDir, 'config.js');
       if (!fs.existsSync(configPath)) {
@@ -334,7 +333,7 @@ export class WorkflowRuntime {
 
       this.status = 'COMPLETED';
       this.persist();
-      this.prependHistory({ event: 'WORKFLOW_COMPLETED' });
+      await this.prependHistory({ event: 'WORKFLOW_COMPLETED' });
 
       console.log(`\n${C.green}✓ Workflow '${this.workflowName}' completed successfully!${C.reset}`);
     } catch (err) {
@@ -342,7 +341,7 @@ export class WorkflowRuntime {
       this._error = err.message;
       this.persist();
 
-      this.prependHistory({
+      await this.prependHistory({
         event: 'WORKFLOW_FAILED',
         error: err.message
       });
@@ -419,7 +418,7 @@ export class WorkflowRuntime {
       const ask = () => {
         if (resolved) return;
 
-        rl.question(`${C.dim}> ${C.reset}`, (answer) => {
+        rl.question(`${C.dim}> ${C.reset}`, async (answer) => {
           if (resolved) return;
 
           const a = answer.trim().toLowerCase();
@@ -427,7 +426,7 @@ export class WorkflowRuntime {
             cleanup();
             // Read and return the response from file
             try {
-              const response = this.readInteractionResponse(filePath, slug, targetKey);
+              const response = await this.readInteractionResponse(filePath, slug, targetKey);
               resolve(response);
             } catch (err) {
               reject(err);
@@ -458,7 +457,7 @@ export class WorkflowRuntime {
   /**
    * Read the user's response from an interaction file
    */
-  readInteractionResponse(filePath, slug, targetKey) {
+  async readInteractionResponse(filePath, slug, targetKey) {
     if (!fs.existsSync(filePath)) {
       throw new Error(`Interaction file not found: ${filePath}`);
     }
@@ -474,7 +473,7 @@ export class WorkflowRuntime {
     this._rawMemory[targetKey] = response;
     this.persist();
 
-    this.prependHistory({
+    await this.prependHistory({
       event: 'INTERACTION_RESOLVED',
       slug,
       targetKey
@@ -605,6 +604,7 @@ export class WorkflowRuntime {
    * @param {string} serverUrl - Base URL of the remote server
    * @param {object} [options]
    * @param {string} [options.sessionToken] - Optional session token to reuse
+   * @param {boolean} [options.uiBaseUrl] - If true, return base URL for UI instead of /s/{token}
    * @returns {Promise<string>} The remote URL for browser access
    */
   async enableRemote(serverUrl, options = {}) {
@@ -612,6 +612,7 @@ export class WorkflowRuntime {
       serverUrl,
       workflowName: this.workflowName,
       sessionToken: options.sessionToken,
+      uiBaseUrl: options.uiBaseUrl,
       onInteractionResponse: (slug, targetKey, response) => {
         this.handleRemoteInteraction(slug, targetKey, response);
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-state-machine",
-  "version": "2.0.15",
+  "version": "2.1.1",
   "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

@@ -1,6 +1,5 @@
 ---
 model: med
-output: result
 format: json
 interaction: true
 ---

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

@@ -1,6 +1,5 @@
 ---
 model: high
-output: result
 format: json
 ---
 

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

@@ -1,6 +1,5 @@
 ---
 model: high
-output: result
 format: json
 ---
 

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

@@ -1,6 +1,5 @@
 ---
 model: med
-output: result
 format: json
 interaction: true
 ---

package/templates/project-builder/agents/response-interpreter.md

@@ -0,0 +1,25 @@
+---
+model: fast
+format: json
+---
+
+You are interpreting a user's natural language response against a structured interaction schema.
+
+Return JSON only with:
+- selectedKey (string or null)
+- selectedKeys (array, optional)
+- isCustom (boolean)
+- customText (string, optional)
+- confidence ("low" | "medium" | "high")
+- reasoning (short string)
+
+Rules:
+- Prefer matching to interaction.options by key or label.
+- If no clear match and allowCustom is true, set isCustom=true and include customText.
+- If ambiguous, set confidence="low" and selectedKey=null.
+
+Input:
+{{userResponse}}
+
+Schema:
+{{interaction}}

package/templates/project-builder/agents/roadmap-generator.md

@@ -1,6 +1,5 @@
 ---
 model: high
-output: result
 format: json
 ---
 

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

@@ -0,0 +1,45 @@
+---
+model: fast
+format: json
+---
+
+You generate executable sanity checks for the implemented task.
+
+Input:
+- task: { title, description, doneDefinition, sanityCheck }
+- implementation: code-writer output
+- testPlan: test-planner output
+
+Return JSON only in this shape:
+{
+  "checks": [
+    {
+      "id": 1,
+      "description": "What this verifies",
+      "type": "shell" | "file_exists" | "file_contains" | "test_suite",
+      "command": "shell command if type=shell/test_suite",
+      "expected": "expected output (optional)",
+      "comparison": "equals" | "contains" | "not_empty",
+      "path": "file path for file checks",
+      "pattern": "string or regex source for file_contains"
+    }
+  ],
+  "setup": "optional setup command",
+  "teardown": "optional teardown command"
+}
+
+Guidelines:
+- Use actual file paths and commands implied by the implementation.
+- Prefer simple, local commands (curl, node, npm, cat, rg).
+- 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.
+
+Task:
+{{task}}
+
+Implementation:
+{{implementation}}
+
+Test Plan:
+{{testPlan}}