agent-state-machine 2.0.15 → 2.1.1

package/bin/cli.js

@@ -394,7 +394,7 @@ async function runOrResume(
   // Enable remote follow mode if we have a URL
   if (remoteUrl) {
     const sessionToken = ensureRemotePath(configFile, { forceNew: forceNewRemotePath });
-    await runtime.enableRemote(remoteUrl, { sessionToken });
+    await runtime.enableRemote(remoteUrl, { sessionToken, uiBaseUrl: useLocalServer });
   }
 
   try {

package/lib/index.js

@@ -12,6 +12,17 @@ import {
   agent,
   executeAgent,
   askHuman,
+  InteractionSchema,
+  InteractionResponseSchema,
+  normalizeInteraction,
+  validateInteraction,
+  normalizeInteractionResponse,
+  validateInteractionResponse,
+  createInteraction,
+  formatInteractionPrompt,
+  matchSingleSelect,
+  matchMultiSelect,
+  parseInteractionResponse,
   parallel,
   parallelLimit,
   getMemory,
@@ -83,6 +94,17 @@ export {
   agent,
   executeAgent,
   askHuman,
+  InteractionSchema,
+  InteractionResponseSchema,
+  normalizeInteraction,
+  validateInteraction,
+  normalizeInteractionResponse,
+  validateInteractionResponse,
+  createInteraction,
+  formatInteractionPrompt,
+  matchSingleSelect,
+  matchMultiSelect,
+  parseInteractionResponse,
   parallel,
   parallelLimit,
   getCurrentRuntime,
@@ -100,6 +122,17 @@ const api = {
   agent,
   executeAgent,
   askHuman,
+  InteractionSchema,
+  InteractionResponseSchema,
+  normalizeInteraction,
+  validateInteraction,
+  normalizeInteractionResponse,
+  validateInteractionResponse,
+  createInteraction,
+  formatInteractionPrompt,
+  matchSingleSelect,
+  matchMultiSelect,
+  parseInteractionResponse,
   parallel,
   parallelLimit,
   getCurrentRuntime,

package/lib/remote/client.js

@@ -81,12 +81,14 @@ export class RemoteClient {
    * @param {function} options.onInteractionResponse - Callback when interaction response received
    * @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}
    */
   constructor(options) {
     this.serverUrl = options.serverUrl.replace(/\/$/, ''); // Remove trailing slash
     this.workflowName = options.workflowName;
     this.onInteractionResponse = options.onInteractionResponse;
     this.onStatusChange = options.onStatusChange || (() => {});
+    this.uiBaseUrl = Boolean(options.uiBaseUrl);
 
     this.sessionToken = options.sessionToken || generateSessionToken();
     this.connected = false;
@@ -99,6 +101,9 @@ export class RemoteClient {
    * Get the full remote URL for browser access
    */
   getRemoteUrl() {
+    if (this.uiBaseUrl) {
+      return this.serverUrl;
+    }
     return `${this.serverUrl}/s/${this.sessionToken}`;
   }
 
@@ -187,9 +192,9 @@ export class RemoteClient {
     }
 
     await this.send({
-      type: 'event',
-      sessionToken: this.sessionToken,
       ...event,
+      type: 'event',  // Must come after spread to not be overwritten by event.type
+      sessionToken: this.sessionToken,
     });
   }
 

package/lib/runtime/agent.js

@@ -11,6 +11,7 @@ import path from 'path';
 import { createRequire } from 'module';
 import { pathToFileURL } from 'url';
 import { getCurrentRuntime } from './runtime.js';
+import { formatInteractionPrompt } from './interaction.js';
 
 const require = createRequire(import.meta.url);
 
@@ -48,12 +49,7 @@ export async function agent(name, params = {}, options = {}) {
       }
 
       console.log(`  [Agent: ${name}] Completed`);
-      if (runtime._agentSuppressCompletion?.has(name)) {
-        runtime._agentSuppressCompletion.delete(name);
-        return result;
-      }
-
-      runtime.prependHistory({
+      await runtime.prependHistory({
         event: 'AGENT_COMPLETED',
         agent: name,
         output: result,
@@ -66,7 +62,7 @@ export async function agent(name, params = {}, options = {}) {
 
       if (attempt < retryCount) {
         console.error(`  [Agent: ${name}] Error (attempt ${attempt + 1}/${retryCount + 1}): ${error.message}`);
-        runtime.prependHistory({
+        await runtime.prependHistory({
           event: 'AGENT_RETRY',
           agent: name,
           attempt: attempt + 1,
@@ -77,7 +73,7 @@ export async function agent(name, params = {}, options = {}) {
   }
 
   // All retries exhausted - record failure
-  runtime.prependHistory({
+  await runtime.prependHistory({
     event: 'AGENT_FAILED',
     agent: name,
     error: lastError.message,
@@ -154,7 +150,7 @@ async function executeJSAgent(runtime, agentPath, name, params, options = {}) {
     throw new Error(`Agent ${name} does not export a function`);
   }
 
-  logAgentStart(runtime, name);
+  await logAgentStart(runtime, name);
 
   // Build steering context (global + any additional files from options)
   const steeringContext = options.steering
@@ -172,25 +168,22 @@ async function executeJSAgent(runtime, agentPath, name, params, options = {}) {
     }
   };
 
-  const result = await handler(context);
+  let result = await handler(context);
+  let interactionDepth = 0;
 
-  // Handle interaction response from JS agent
-  if (result && result._interaction) {
+  // Handle interaction response from JS agent (support multiple rounds)
+  while (result && result._interaction) {
     const interactionResponse = await handleInteraction(runtime, result._interaction, name);
-    
-    // Use the interaction response as the primary output if it exists
-    // This allows the workflow to receive the user's input directly
-    if (typeof result === 'object') {
-       // Merge response into result or replace? 
-       // For consistency with MDAgent, we might want to return { result: response }
-       // but JS agents are more flexible. 
-       // Let's assume the agent wants the response mixed in or as the return.
-       // A safe bet is to return the response if the agent explicitly asked for interaction.
-       return { ...result, result: interactionResponse };
+    const resumedContext = { ...context, userResponse: interactionResponse };
+    await logAgentStart(runtime, name);
+    result = await handler(resumedContext);
+    interactionDepth += 1;
+    if (interactionDepth > 5) {
+      throw new Error(`Agent ${name} exceeded maximum interaction depth`);
     }
-    return interactionResponse;
   }
 
+
   // Clean internal properties from result
   if (result && typeof result === 'object') {
     const cleanResult = { ...result };
@@ -222,8 +215,7 @@ async function executeMDAgent(runtime, agentPath, name, params, options = {}) {
   const content = fs.readFileSync(agentPath, 'utf-8');
   const { config, prompt } = parseMarkdownAgent(content);
 
-  const outputKey = config.output || 'result';
-  const targetKey = config.interactionKey || outputKey;
+  const outputKey = config.output;
 
   // Combine steering from options (runtime call) and frontmatter (static)
   let steeringNames = [];
@@ -243,46 +235,65 @@ async function executeMDAgent(runtime, agentPath, name, params, options = {}) {
     ? runtime.loadSteeringFiles(steeringNames)
     : runtime.steering;
 
-  // Build context - only spread params, NOT memory (explicit context passing)
-  const context = {
-    ...params,
-    _steering: steeringContext,
-    _config: {
-      models: runtime.workflowConfig.models,
-      apiKeys: runtime.workflowConfig.apiKeys,
-      workflowDir: runtime.workflowDir
-    }
-  };
+  let response = null;
+  let output = null;
+  let interactionDepth = 0;
+  let currentParams = params;
+
+  while (true) {
+    // Build context - only spread params, NOT memory (explicit context passing)
+    const context = {
+      ...currentParams,
+      _steering: steeringContext,
+      _config: {
+        models: runtime.workflowConfig.models,
+        apiKeys: runtime.workflowConfig.apiKeys,
+        workflowDir: runtime.workflowDir
+      }
+    };
 
-  // Interpolate variables in prompt
-  const interpolatedPrompt = interpolatePrompt(prompt, context);
+    // Interpolate variables in prompt
+    const interpolatedPrompt = interpolatePrompt(prompt, context);
 
-  const model = config.model || 'fast';
+    const model = config.model || 'fast';
 
-  const fullPrompt = buildPrompt(context, {
-    model,
-    prompt: interpolatedPrompt,
-    includeContext: config.includeContext !== 'false'
-  });
+    const fullPrompt = buildPrompt(context, {
+      model,
+      prompt: interpolatedPrompt,
+      includeContext: config.includeContext !== 'false'
+    });
 
-  logAgentStart(runtime, name, fullPrompt);
+    await logAgentStart(runtime, name, fullPrompt);
 
-  console.log(`    Using model: ${model}`);
+    console.log(`    Using model: ${model}`);
 
-  const response = await llm(context, {
-    model: model,
-    prompt: interpolatedPrompt,
-    includeContext: config.includeContext !== 'false'
-  });
+    response = await llm(context, {
+      model: model,
+      prompt: interpolatedPrompt,
+      includeContext: config.includeContext !== 'false'
+    });
 
-  // Parse output based on format
-  let output = response.text;
-  if (config.format === 'json') {
-    try {
-      output = parseJSON(response.text);
-    } catch {
-      console.warn(`    Warning: Failed to parse JSON output`);
+    // Parse output based on format
+    output = response.text;
+    if (config.format === 'json') {
+      try {
+        output = parseJSON(response.text);
+      } catch {
+        console.warn(`    Warning: Failed to parse JSON output`);
+      }
+    }
+
+    if (output && typeof output === 'object' && output._interaction) {
+      const interactionResponse = await handleInteraction(runtime, output._interaction, name);
+      currentParams = { ...params, userResponse: interactionResponse };
+      interactionDepth += 1;
+      if (interactionDepth > 5) {
+        throw new Error(`Agent ${name} exceeded maximum interaction depth`);
+      }
+      continue;
     }
+
+    break;
   }
 
   // Check for interaction request
@@ -302,7 +313,6 @@ async function executeMDAgent(runtime, agentPath, name, params, options = {}) {
         : null) ||
       config.interactionSlug ||
       config.interactionKey ||
-      outputKey ||
       name;
 
     const slug = sanitizeSlug(slugRaw);
@@ -316,11 +326,19 @@ async function executeMDAgent(runtime, agentPath, name, params, options = {}) {
     }, name);
 
     // Return the user's response as the agent result
-    return { [outputKey]: userResponse, _debug_prompt: response.fullPrompt };
+    if (outputKey) {
+      return { [outputKey]: userResponse, _debug_prompt: response.fullPrompt };
+    }
+
+    return userResponse;
   }
 
   // Return result object
-  return { [outputKey]: output, _debug_prompt: response.fullPrompt };
+  if (outputKey) {
+    return { [outputKey]: output, _debug_prompt: response.fullPrompt };
+  }
+
+  return output;
 }
 
 /**
@@ -435,7 +453,16 @@ async function handleInteraction(runtime, interaction, agentName) {
 
   const slug = sanitizeSlug(interaction.slug);
   const targetKey = String(interaction.targetKey || slug);
-  const content = String(interaction.content || '').trim();
+  const prompt = String(
+    interaction.prompt ??
+    interaction.content ??
+    interaction.question ??
+    ''
+  ).trim();
+  const content = formatInteractionPrompt({
+    ...interaction,
+    prompt
+  });
 
   const filePath = path.join(runtime.interactionsDir, `${slug}.md`);
 
@@ -448,15 +475,23 @@ ${content}
 
   fs.writeFileSync(filePath, fileContent);
 
-  runtime.prependHistory({
+  await runtime.prependHistory({
     event: 'INTERACTION_REQUESTED',
     slug,
     targetKey,
-    question: content
+    question: prompt || content,
+    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
   });
 
   if (effectiveAgentName) {
-    runtime._agentSuppressCompletion?.add(effectiveAgentName);
     runtime._agentResumeFlags?.add(effectiveAgentName);
   }
 
@@ -466,10 +501,10 @@ ${content}
   return response;
 }
 
-function logAgentStart(runtime, name, prompt) {
+async function logAgentStart(runtime, name, prompt) {
   if (runtime._agentResumeFlags?.has(name)) {
     runtime._agentResumeFlags.delete(name);
-    runtime.prependHistory({
+    await runtime.prependHistory({
       event: 'AGENT_RESUMED',
       agent: name
     });
@@ -485,5 +520,5 @@ function logAgentStart(runtime, name, prompt) {
     entry.prompt = prompt;
   }
 
-  runtime.prependHistory(entry);
+  await runtime.prependHistory(entry);
 }

package/lib/runtime/index.js

@@ -15,6 +15,19 @@ export {
 
 export { agent, executeAgent } from './agent.js';
 export { askHuman } from './prompt.js';
+export {
+  InteractionSchema,
+  InteractionResponseSchema,
+  normalizeInteraction,
+  validateInteraction,
+  normalizeInteractionResponse,
+  validateInteractionResponse,
+  createInteraction,
+  formatInteractionPrompt,
+  matchSingleSelect,
+  matchMultiSelect,
+  parseInteractionResponse
+} from './interaction.js';
 export { parallel, parallelLimit } from './parallel.js';
 export { createMemoryProxy } from './memory.js';