agent-state-machine 2.0.14 → 2.1.0

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.14",
+  "version": "2.1.0",
   "type": "module",
   "description": "A workflow orchestrator for running agents and scripts in sequence with state management",
   "main": "lib/index.js",
@@ -28,6 +28,7 @@
   "files": [
     "bin",
     "lib",
+    "templates",
     "vercel-server/local-server.js",
     "vercel-server/public",
     "vercel-server/ui",

package/templates/project-builder/README.md

@@ -0,0 +1,119 @@
+# project-builder
+
+A workflow created with agent-state-machine (native JS format).
+
+## Structure
+
+\`\`\`
+project-builder/
+├── workflow.js      # Native JS workflow (async/await)
+├── config.js        # Model/API key configuration
+├── package.json     # Sets "type": "module" for this workflow folder
+├── agents/          # Custom agents (.js/.mjs/.cjs or .md)
+├── interactions/    # Human-in-the-loop inputs (created at runtime)
+├── state/           # Runtime state (current.json, history.jsonl)
+└── steering/        # Steering configuration
+\`\`\`
+
+## Usage
+
+Edit `config.js` to set models and API keys for this workflow.
+
+Run the workflow (or resume if interrupted):
+\`\`\`bash
+state-machine run project-builder
+\`\`\`
+
+Check status:
+\`\`\`bash
+state-machine status project-builder
+\`\`\`
+
+View history:
+\`\`\`bash
+state-machine history project-builder
+\`\`\`
+
+View trace logs in browser with live updates:
+\`\`\`bash
+state-machine follow project-builder
+\`\`\`
+
+Reset state (clears memory/state):
+\`\`\`bash
+state-machine reset project-builder
+\`\`\`
+
+Hard reset (clears everything: history/interactions/memory):
+\`\`\`bash
+state-machine reset-hard project-builder
+\`\`\`
+
+## Writing Workflows
+
+Edit `workflow.js` - write normal async JavaScript:
+
+\`\`\`js
+import { agent, memory, askHuman, parallel } from 'agent-state-machine';
+
+export default async function() {
+  console.log('Starting project-builder workflow...');
+
+  // Example: Get user input (saved to memory)
+  const userLocation = await askHuman('Where do you live?');
+  console.log('Example prompt answer:', userLocation);
+
+  const userInfo = await agent('yoda-name-collector');
+  memory.userInfo = userInfo;
+
+  // Provide context
+  // const userInfo = await agent('yoda-name-collector', { name: 'Luke' });
+
+  console.log('Example agent memory.userInfo:', memory.userInfo || userInfo);
+
+  // Context is provided automatically
+  const { greeting } = await agent('yoda-greeter', { userLocation });
+  console.log('Example agent greeting:', greeting);
+
+  // Or you can provide context manually
+  // await agent('yoda-greeter', userInfo);
+
+  // Example: Parallel execution
+  // const [a, b, c] = await parallel([
+  //   agent('yoda-greeter', { name: 'the names augustus but friends call me gus' }),
+  //   agent('yoda-greeter', { name: 'uriah' }),
+  //   agent('yoda-greeter', { name: 'lucas' })
+  // ]);
+
+  // console.log('a: ' + JSON.stringify(a))
+  // console.log('b: ' + JSON.stringify(b))
+  // console.log('c: ' + JSON.stringify(c))
+
+  notify(['project-builder', userInfo.name || userInfo + ' has been greeted!']);
+
+  console.log('Workflow completed!');
+}
+\`\`\`
+
+## Creating Agents
+
+**JavaScript agent** (`agents/my-agent.js`):
+
+\`\`\`js
+import { llm } from 'agent-state-machine';
+
+export default async function handler(context) {
+  const response = await llm(context, { model: 'smart', prompt: 'Hello!' });
+  return { greeting: response.text };
+}
+\`\`\`
+
+**Markdown agent** (`agents/greeter.md`):
+
+\`\`\`md
+---
+model: fast
+output: greeting
+---
+Generate a greeting for {{name}}.
+\`\`\`

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

@@ -0,0 +1,65 @@
+---
+model: med
+format: json
+interaction: true
+---
+
+# Assumptions Clarifier Agent
+
+You are an assumptions and constraints analyst. Your job is to identify and validate assumptions before development.
+
+## Context
+Project Description: {{projectDescription}}
+Scope: {{scope}}
+Requirements: {{requirements}}
+{{#if previousResponse}}
+User's Previous Response: {{previousResponse}}
+{{/if}}
+
+## Instructions
+
+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 are clear, return:
+
+{
+  "assumptions": {
+    "technical": [
+      {"assumption": "...", "validated": true, "impact": "high"}
+    ],
+    "business": [
+      {"assumption": "...", "validated": true, "impact": "medium"}
+    ],
+    "domain": [
+      {"assumption": "...", "validated": true, "impact": "low"}
+    ]
+  },
+  "risks": [
+    {"description": "...", "likelihood": "medium", "mitigation": "..."}
+  ]
+}
+
+Flag high-risk assumptions that could derail the project if incorrect.