agent-state-machine 2.0.12 → 2.0.13

package/lib/llm.js

@@ -51,6 +51,7 @@ export function buildPrompt(context, options) {
     delete cleanContext._steering;
     delete cleanContext._loop;
     delete cleanContext._config;
+    delete cleanContext._memory;
 
     // Add the actual prompt
     parts.push('# Task\n\n');
@@ -70,13 +71,22 @@ export function buildPrompt(context, options) {
   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 global steering if available
+  // Add global steering if available (always first)
   if (context._steering?.global) {
     parts.push('# System Instructions\n');
     parts.push(context._steering.global);
     parts.push('\n---\n');
   }
 
+  // Add additional steering files if available
+  if (context._steering?.additional && context._steering.additional.length > 0) {
+    parts.push('# Additional Guidelines\n');
+    for (const content of context._steering.additional) {
+      parts.push(content);
+      parts.push('\n---\n');
+    }
+  }
+
   return parts.join('\n');
 }
 

package/lib/runtime/agent.js

@@ -17,50 +17,87 @@ const require = createRequire(import.meta.url);
 /**
  * Run an agent with context
  * @param {string} name - Agent name (file basename)
- * @param {object} params - Parameters passed to agent
+ * @param {object} params - Parameters passed to agent (default: {})
+ * @param {object} options - Agent execution options (default: {})
+ * @param {number|false} options.retry - Number of retries (default: 2, meaning 3 total attempts). Set to false to disable.
+ * @param {string|string[]} options.steering - Additional steering files to load from steering/ folder
  */
-export async function agent(name, params = {}) {
+export async function agent(name, params = {}, options = {}) {
   const runtime = getCurrentRuntime();
   if (!runtime) {
     throw new Error('agent() must be called within a workflow context');
   }
 
-  console.log(`  [Agent: ${name}] Starting...`);
+  // Parse retry option: default is 2 retries (3 total attempts)
+  const retryCount = options.retry === false ? 0 : (options.retry ?? 2);
 
-  try {
-    const result = await executeAgent(runtime, name, params);
+  let lastError;
 
-    if (result && typeof result === 'object' && result._debug_prompt) {
-      delete result._debug_prompt;
-    }
+  for (let attempt = 0; attempt <= retryCount; attempt++) {
+    try {
+      if (attempt > 0) {
+        console.log(`  [Agent: ${name}] Retry attempt ${attempt}/${retryCount}...`);
+      } else {
+        console.log(`  [Agent: ${name}] Starting...`);
+      }
+
+      const result = await executeAgent(runtime, name, params, options);
+
+      if (result && typeof result === 'object' && result._debug_prompt) {
+        delete result._debug_prompt;
+      }
+
+      console.log(`  [Agent: ${name}] Completed`);
+      if (runtime._agentSuppressCompletion?.has(name)) {
+        runtime._agentSuppressCompletion.delete(name);
+        return result;
+      }
+
+      runtime.prependHistory({
+        event: 'AGENT_COMPLETED',
+        agent: name,
+        output: result,
+        attempts: attempt + 1
+      });
 
-    console.log(`  [Agent: ${name}] Completed`);
-    if (runtime._agentSuppressCompletion?.has(name)) {
-      runtime._agentSuppressCompletion.delete(name);
       return result;
+    } catch (error) {
+      lastError = error;
+
+      if (attempt < retryCount) {
+        console.error(`  [Agent: ${name}] Error (attempt ${attempt + 1}/${retryCount + 1}): ${error.message}`);
+        runtime.prependHistory({
+          event: 'AGENT_RETRY',
+          agent: name,
+          attempt: attempt + 1,
+          error: error.message
+        });
+      }
     }
+  }
 
-    runtime.prependHistory({
-      event: 'AGENT_COMPLETED',
-      agent: name,
-      output: result
-    });
+  // All retries exhausted - record failure
+  runtime.prependHistory({
+    event: 'AGENT_FAILED',
+    agent: name,
+    error: lastError.message,
+    attempts: retryCount + 1
+  });
 
-    return result;
-  } catch (error) {
-    runtime.prependHistory({
-      event: 'AGENT_FAILED',
-      agent: name,
-      error: error.message
-    });
-    throw error;
-  }
+  // Store error in accessible location (not auto-spread to context)
+  runtime._agentErrors.push({
+    agent: name,
+    error: lastError.message,
+    timestamp: new Date().toISOString()
+  });
+
+  throw lastError;
 }
 
 /**
  * Execute an agent (load and run)
  */
-export async function executeAgent(runtime, name, params) {
+export async function executeAgent(runtime, name, params, options = {}) {
   const agentsDir = runtime.agentsDir;
 
   // Try JS agents (.js/.mjs/.cjs)
@@ -72,14 +109,14 @@ export async function executeAgent(runtime, name, params) {
 
   for (const p of jsCandidates) {
     if (fs.existsSync(p)) {
-      return executeJSAgent(runtime, p, name, params);
+      return executeJSAgent(runtime, p, name, params, options);
     }
   }
 
   // Try Markdown agent
   const mdPath = path.join(agentsDir, `${name}.md`);
   if (fs.existsSync(mdPath)) {
-    return executeMDAgent(runtime, mdPath, name, params);
+    return executeMDAgent(runtime, mdPath, name, params, options);
   }
 
   throw new Error(
@@ -94,7 +131,7 @@ export async function executeAgent(runtime, name, params) {
  * - ESM (.js/.mjs): loaded via dynamic import with cache-bust for hot reload
  * - CJS (.cjs): loaded via require() with cache clear
  */
-async function executeJSAgent(runtime, agentPath, name, params) {
+async function executeJSAgent(runtime, agentPath, name, params, options = {}) {
   const ext = path.extname(agentPath).toLowerCase();
 
   let agentModule;
@@ -119,11 +156,15 @@ async function executeJSAgent(runtime, agentPath, name, params) {
 
   logAgentStart(runtime, name);
 
-  // Build context
+  // Build steering context (global + any additional files from options)
+  const steeringContext = options.steering
+    ? runtime.loadSteeringFiles(options.steering)
+    : runtime.steering;
+
+  // Build context - only spread params, NOT memory (explicit context passing)
   const context = {
-    ...runtime._rawMemory,
     ...params,
-    _steering: runtime.steering,
+    _steering: steeringContext,
     _config: {
       models: runtime.workflowConfig.models,
       apiKeys: runtime.workflowConfig.apiKeys,
@@ -175,7 +216,7 @@ async function executeJSAgent(runtime, agentPath, name, params) {
 /**
  * Execute a Markdown agent (prompt-based)
  */
-async function executeMDAgent(runtime, agentPath, name, params) {
+async function executeMDAgent(runtime, agentPath, name, params, options = {}) {
   const { llm, buildPrompt, parseJSON, parseInteractionRequest } = await import('../llm.js');
 
   const content = fs.readFileSync(agentPath, 'utf-8');
@@ -184,11 +225,28 @@ async function executeMDAgent(runtime, agentPath, name, params) {
   const outputKey = config.output || 'result';
   const targetKey = config.interactionKey || outputKey;
 
-  // Build context
+  // Combine steering from options (runtime call) and frontmatter (static)
+  let steeringNames = [];
+
+  if (options.steering) {
+    const optSteering = Array.isArray(options.steering) ? options.steering : [options.steering];
+    steeringNames.push(...optSteering);
+  }
+
+  if (config.steering) {
+    const fmSteering = parseSteeringFrontmatter(config.steering);
+    steeringNames.push(...fmSteering);
+  }
+
+  // Build steering context (global + any additional files)
+  const steeringContext = steeringNames.length > 0
+    ? runtime.loadSteeringFiles(steeringNames)
+    : runtime.steering;
+
+  // Build context - only spread params, NOT memory (explicit context passing)
   const context = {
-    ...runtime._rawMemory,
     ...params,
-    _steering: runtime.steering,
+    _steering: steeringContext,
     _config: {
       models: runtime.workflowConfig.models,
       apiKeys: runtime.workflowConfig.apiKeys,
@@ -296,6 +354,36 @@ function parseMarkdownAgent(content) {
   return { config: {}, prompt: content.trim() };
 }
 
+/**
+ * Parse steering value from frontmatter
+ * Supports: "name", "name1, name2", "[name1, name2]", "['name1', 'name2']"
+ * @param {string} value - Frontmatter steering value
+ * @returns {string[]} Array of steering file names
+ */
+function parseSteeringFrontmatter(value) {
+  if (!value) return [];
+
+  const trimmed = value.trim();
+
+  // Handle array format: [a, b, c] or ["a", "b", "c"]
+  if (trimmed.startsWith('[') && trimmed.endsWith(']')) {
+    const inner = trimmed.slice(1, -1);
+    return inner.split(',')
+      .map(s => s.trim().replace(/^["']|["']$/g, ''))
+      .filter(Boolean);
+  }
+
+  // Handle comma-separated: a, b, c
+  if (trimmed.includes(',')) {
+    return trimmed.split(',')
+      .map(s => s.trim())
+      .filter(Boolean);
+  }
+
+  // Single value
+  return [trimmed];
+}
+
 /**
  * Interpolate {{variables}} in prompt template
  */

package/lib/runtime/runtime.js

@@ -89,6 +89,9 @@ 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 = [];
   }
 
   ensureDirectories() {
@@ -142,6 +145,39 @@ export class WorkflowRuntime {
     return steering;
   }
 
+  /**
+   * Load a specific steering file by name
+   * @param {string} name - Name of the steering file (without .md extension)
+   * @returns {string} Content of the steering file, or empty string if not found
+   */
+  loadSteeringFile(name) {
+    const filePath = path.join(this.steeringDir, `${name}.md`);
+
+    if (fs.existsSync(filePath)) {
+      return fs.readFileSync(filePath, 'utf-8');
+    }
+
+    console.warn(`${C.yellow}Warning: Steering file not found: ${name}.md${C.reset}`);
+    return '';
+  }
+
+  /**
+   * Load multiple steering files and combine with global
+   * @param {string|string[]} steeringNames - Names of steering files to load
+   * @returns {{ enabled: boolean, global: string, additional: string[] }}
+   */
+  loadSteeringFiles(steeringNames) {
+    const names = Array.isArray(steeringNames) ? steeringNames : [steeringNames];
+    const additional = names
+      .map(name => this.loadSteeringFile(name))
+      .filter(content => content.length > 0);
+
+    return {
+      ...this.steering,
+      additional
+    };
+  }
+
   /**
    * Persist state to disk
    */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-state-machine",
-  "version": "2.0.12",
+  "version": "2.0.13",
   "type": "module",
   "description": "A workflow orchestrator for running agents and scripts in sequence with state management",
   "main": "lib/index.js",