agent-state-machine 2.0.12 → 2.0.14

package/README.md

@@ -6,6 +6,7 @@ You write normal `async/await` code. The runtime handles:
 - **Auto-persisted** `memory` (saved to disk on mutation)
 - **Human-in-the-loop** blocking via `askHuman()` or agent-driven interactions
 - Local **JS agents** + **Markdown agents** (LLM-powered)
+- **Agent retries** with history logging for failures
 
 ---
 
@@ -43,14 +44,19 @@ Requirements: Node.js >= 16.
 
 ```bash
 state-machine --setup <workflow-name>
+state-machine --setup <workflow-name> --template <template-name>
 state-machine run <workflow-name>
 state-machine run <workflow-name> -reset
 state-machine run <workflow-name> -reset-hard
 
+state-machine -reset <workflow-name>
+state-machine -reset-hard <workflow-name>
 
 state-machine history <workflow-name> [limit]
 ```
 
+Templates live in `templates/` and `starter` is used by default.
+
 Workflows live in:
 
 ```text
@@ -101,8 +107,8 @@ export default async function() {
 
   console.log('Example agent memory.userInfo:', memory.userInfo || userInfo);
 
-  // Context is provided automatically
-  const { greeting } = await agent('yoda-greeter', { userLocation });
+  // Context is explicit: pass what the agent needs
+  const { greeting } = await agent('yoda-greeter', { userLocation, memory });
   console.log('Example agent greeting:', greeting);
 
   // Or you can provide context manually
@@ -137,7 +143,7 @@ If the process is interrupted, running `state-machine run <workflow-name>` again
 
 ## Core API
 
-### `agent(name, params?)`
+### `agent(name, params?, options?)`
 
 Runs `workflows/<name>/agents/<agent>.(js|mjs|cjs)` or `<agent>.md`.
 
@@ -146,6 +152,12 @@ const out = await agent('review', { file: 'src/app.js' });
 memory.lastReview = out;
 ```
 
+Options:
+- `retry` (number | false): default `2` (3 total attempts). Use `false` to disable retries.
+- `steering` (string | string[]): extra steering files to load from `workflows/<name>/steering/`.
+
+Context is explicit: only `params` are provided to agents unless you pass additional data.
+
 ### `memory`
 
 A persisted object for your workflow.
@@ -203,9 +215,8 @@ import { llm } from 'agent-state-machine';
 
 export default async function handler(context) {
   // context includes:
-  // - persisted memory (spread into the object)
   // - params passed to agent(name, params)
-  // - context._steering (global steering prompt/config)
+  // - context._steering (global + optional additional steering content)
   // - context._config (models/apiKeys/workflowDir)
   return { ok: true };
 }
@@ -240,11 +251,13 @@ The runtime will block execution and wait for your response in the terminal.
 ### Markdown agents (`.md`)
 
 Markdown agents are LLM-backed prompt templates with optional frontmatter.
+Frontmatter can include `steering` to load additional files from `workflows/<name>/steering/`.
 
 ```md
 ---
 model: smart
 output: greeting
+steering: tone, product
 ---
 Generate a friendly greeting for {{name}}.
 ```
@@ -296,7 +309,7 @@ The runtime captures the fully-built prompt in `state/history.jsonl`, viewable i
 Native JS workflows persist to:
 
 - `workflows/<name>/state/current.json` — status, memory, pending interaction
-- `workflows/<name>/state/history.jsonl` — event log (newest entries first)
+- `workflows/<name>/state/history.jsonl` — event log (newest entries first, includes agent retry/failure entries)
 - `workflows/<name>/interactions/*.md` — human input files (when paused)
 
 ## License

package/bin/cli.js

@@ -13,8 +13,13 @@ import { startLocalServer } from '../vercel-server/local-server.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
-const args = process.argv.slice(2);
-const command = args[0];
+let args = process.argv.slice(2);
+let command = args[0];
+const legacyResetCommand = command === '-reset' || command === '-reset-hard';
+if (legacyResetCommand) {
+  command = command.slice(1);
+  args = [command, ...args.slice(1)];
+}
 
 function getVersion() {
   try {
@@ -34,13 +39,15 @@ function printHelp() {
 Agent State Machine CLI (Native JS Workflows Only) v${getVersion()}
 
 Usage:
-  state-machine --setup <workflow-name>    Create a new workflow project
+  state-machine --setup <workflow-name> [--template <template-name>]    Create a new workflow project
   state-machine run <workflow-name>        Run a workflow (remote follow enabled by default)
   state-machine run <workflow-name> -l  Run with local server (localhost:3000)
   state-machine run <workflow-name> -n  Generate a new remote follow path
   state-machine run <workflow-name> -reset  Reset workflow state before running
   state-machine run <workflow-name> -reset-hard  Hard reset workflow before running
 
+  state-machine -reset <workflow-name>     Reset workflow state (legacy alias)
+  state-machine -reset-hard <workflow-name> Hard reset workflow (legacy alias)
   state-machine status [workflow-name]     Show current state (or list all)
   state-machine history <workflow-name> [limit]  Show execution history logs
   state-machine reset <workflow-name>      Reset workflow state (clears memory/state)
@@ -50,6 +57,7 @@ Usage:
 
 Options:
   --setup, -s     Initialize a new workflow with directory structure
+  --template, -t  Template name for --setup (default: starter)
   --local, -l     Use local server instead of remote (starts on localhost:3000)
   --new, -n       Generate a new remote follow path
   -reset          Reset workflow state before running
@@ -421,10 +429,20 @@ async function main() {
     const workflowName = args[1];
     if (!workflowName) {
       console.error('Error: Workflow name required');
-      console.error('Usage: state-machine --setup <workflow-name>');
+      console.error('Usage: state-machine --setup <workflow-name> [--template <template-name>]');
       process.exit(1);
     }
-    await setup(workflowName);
+    const templateFlagIndex = args.findIndex((arg) => arg === '--template' || arg === '-t');
+    let templateName = null;
+    if (templateFlagIndex !== -1) {
+      templateName = args[templateFlagIndex + 1];
+      if (!templateName || templateName.startsWith('-')) {
+        console.error('Error: Template name required');
+        console.error('Usage: state-machine --setup <workflow-name> [--template <template-name>]');
+        process.exit(1);
+      }
+    }
+    await setup(workflowName, { template: templateName || undefined });
     process.exit(0);
   }
 

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

@@ -4,13 +4,75 @@
 
 import fs from 'fs';
 import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const DEFAULT_TEMPLATE = 'starter';
+
+function getTemplatesDir() {
+  return path.join(__dirname, '..', 'templates');
+}
+
+function listTemplates(templatesDir) {
+  if (!fs.existsSync(templatesDir)) return [];
+  return fs.readdirSync(templatesDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort();
+}
+
+function applyReplacements(content, replacements) {
+  let output = content;
+  for (const [token, value] of Object.entries(replacements)) {
+    output = output.split(token).join(value);
+  }
+  return output;
+}
+
+function copyTemplateDir(srcDir, destDir, replacements, createdPaths) {
+  fs.mkdirSync(destDir, { recursive: true });
+
+  const entries = fs.readdirSync(srcDir, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(srcDir, entry.name);
+    const destPath = path.join(destDir, entry.name);
+
+    if (entry.isDirectory()) {
+      copyTemplateDir(srcPath, destPath, replacements, createdPaths);
+      continue;
+    }
+
+    if (!entry.isFile()) {
+      continue;
+    }
+
+    let written = false;
+    try {
+      const content = fs.readFileSync(srcPath, 'utf-8');
+      const replaced = applyReplacements(content, replacements);
+      fs.writeFileSync(destPath, replaced);
+      written = true;
+    } catch {
+      // Fallback for non-text files
+    }
+
+    if (!written) {
+      fs.copyFileSync(srcPath, destPath);
+    }
+
+    createdPaths.push(destPath);
+  }
+}
 
 /**
  * Setup a new workflow with directory structure
  */
-async function setup(workflowName) {
+async function setup(workflowName, options = {}) {
   const workflowsDir = path.join(process.cwd(), 'workflows');
   const workflowDir = path.join(workflowsDir, workflowName);
+  const templateName = options.template || DEFAULT_TEMPLATE;
 
   // Check if workflow already exists
   if (fs.existsSync(workflowDir)) {
@@ -18,401 +80,33 @@ async function setup(workflowName) {
     process.exit(1);
   }
 
-  console.log(`\nCreating workflow: ${workflowName}`);
-  console.log('─'.repeat(40));
-
-  // Create directory structure (native JS workflow only)
-  const dirs = [
-    workflowDir,
-    path.join(workflowDir, 'agents'),
-    path.join(workflowDir, 'interactions'),
-    path.join(workflowDir, 'state'),
-    path.join(workflowDir, 'steering'),
-    path.join(workflowDir, 'scripts')
-  ];
-
-  dirs.forEach((dir) => {
-    fs.mkdirSync(dir, { recursive: true });
-    console.log(`  Created: ${path.relative(process.cwd(), dir)}/`);
-  });
-
-  // Ensure this workflow folder is ESM (so workflow.js + agents/*.js can use import/export)
-  // const workflowPkg = {
-  //   name: `workflow-${workflowName}`,
-  //   private: true,
-  //   type: 'module'
-  // };
-  // const workflowPkgFile = path.join(workflowDir, 'package.json');
-  // fs.writeFileSync(workflowPkgFile, JSON.stringify(workflowPkg, null, 2));
-  // console.log(`  Created: ${path.relative(process.cwd(), workflowPkgFile)}`);
-
-  // Create workflow.js (native JS format)
-  const workflowJs = `/**
-/**
- * ${workflowName} Workflow
- *
- * Native JavaScript workflow - write normal async/await code!
- *
- * Features:
- * - memory object auto-persists to disk (use memory guards for idempotency)
- * - Use standard JS control flow (if, for, etc.)
- * - Interactive prompts pause and wait for user input
- */
-
-import { agent, memory, askHuman, parallel } from 'agent-state-machine';
-import { notify } from './scripts/mac-notification.js';
-
-export default async function() {
-  console.log('Starting ${workflowName} 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' })
-  // ]);
+  const templatesDir = getTemplatesDir();
+  const templateDir = path.join(templatesDir, templateName);
 
-  // console.log('a: ' + JSON.stringify(a))
-  // console.log('b: ' + JSON.stringify(b))
-  // console.log('c: ' + JSON.stringify(c))
-
-  notify(['${workflowName}', userInfo.name || userInfo + ' has been greeted!']);
-
-  console.log('Workflow completed!');
-}
-`;
-
-  const workflowFile = path.join(workflowDir, 'workflow.js');
-  fs.writeFileSync(workflowFile, workflowJs);
-  console.log(`  Created: ${path.relative(process.cwd(), workflowFile)}`);
-
-  const configJs = `export const config = {
-  models: {
-    low: "gemini",
-    med: "codex --model gpt-5.2",
-    high: "claude -m claude-opus-4-20250514 -p",
-  },
-  apiKeys: {
-    gemini: process.env.GEMINI_API_KEY,
-    anthropic: process.env.ANTHROPIC_API_KEY,
-    openai: process.env.OPENAI_API_KEY,
-  }
-};
-`;
-
-  const configFile = path.join(workflowDir, 'config.js');
-  fs.writeFileSync(configFile, configJs);
-  console.log(`  Created: ${path.relative(process.cwd(), configFile)}`);
-
-  // Create example JS agent (ESM)
-  // Create example JS agent (ESM)
-  const exampleAgent = `/**
- * Example Agent for ${workflowName}
- *
- * Agents are async functions that receive a context object and return a result.
- * - Context includes: persisted memory (spread), params, _steering, _config
- */
-
-import { llm } from 'agent-state-machine';
-
-export default async function handler(context) {
-  console.log('[Agent: example] Processing...');
-
-  // Access global steering prompt if available
-  if (context._steering?.global) {
-    console.log('[Agent: example] Steering loaded (' + context._steering.global.length + ' chars)');
+  if (!fs.existsSync(templateDir)) {
+    const available = listTemplates(templatesDir);
+    console.error(`Error: Template '${templateName}' not found.`);
+    if (available.length > 0) {
+      console.error(`Available templates: ${available.join(', ')}`);
+    }
+    process.exit(1);
   }
 
-  // Example: Call an LLM (configure models in config.js)
-  // const response = await llm(context, {
-  //   model: 'smart',
-  //   prompt: 'Say hello and describe what you can help with.'
-  // });
-  // console.log('[Agent: example] LLM response:', response.text);
-
-  return {
-    ok: true,
-    received: Object.keys(context).filter((k) => !String(k).startsWith('_')),
-    processedAt: new Date().toISOString()
-  };
-}
-
-export const meta = {
-  name: 'example',
-  description: 'An example agent to get you started',
-  version: '1.0.0'
-};
-`;
-
-  const agentFile = path.join(workflowDir, 'agents', 'example.js');
-  fs.writeFileSync(agentFile, exampleAgent);
-  console.log(`  Created: ${path.relative(process.cwd(), agentFile)}`);
-
-  // Create example markdown agent
-  const yodaGreeterAgent = `---
-model: low
-output: greeting
----
-
-# Greeting Task
-
-Generate a friendly greeting for {{name}} from {{location}} in a yoda style. Prompt user for their actual {{name}} if you dont have it.
-
-Once you have it create a yoda-greeting.md file in root dir with the greeting.
-
-You are a fast, direct worker. Do NOT investigate the codebase or read files unless strictly necessary. Perform the requested action immediately using the provided context. Avoid "thinking" steps or creating plans if the task is simple.
-`;
-
-  const yodaNameCollectorAgent = `---
-model: low
-output: name
----
-
-# Name Collection Task
-
-Ask for users name in a yoda style. Unless you have it already.
-
-Keep it brief and warm.
-
-You are a fast, direct worker. Do NOT investigate the codebase or read files unless strictly necessary. Perform the requested action immediately using the provided context. Avoid "thinking" steps or creating plans if the task is simple.
-`;
-
-  const yodaNameCollectorAgentFile = path.join(workflowDir, 'agents', 'yoda-name-collector.md');
-  fs.writeFileSync(yodaNameCollectorAgentFile, yodaNameCollectorAgent);
-
-  const yodaGreeterFile = path.join(workflowDir, 'agents', 'yoda-greeter.md');
-  fs.writeFileSync(yodaGreeterFile, yodaGreeterAgent);
-
-  console.log(`  Created: ${path.relative(process.cwd(), yodaGreeterFile)}`);
-  console.log(`  Created: ${path.relative(process.cwd(), yodaNameCollectorAgentFile)}`);
-
-  // Create initial state (native format)
-  const initialState = {
-    format: 'native',
-    status: 'IDLE',
-    memory: {},
-    _pendingInteraction: null,
-    _error: null,
-    startedAt: null,
-    lastUpdatedAt: new Date().toISOString()
-  };
-  const stateFile = path.join(workflowDir, 'state', 'current.json');
-  fs.writeFileSync(stateFile, JSON.stringify(initialState, null, 2));
-  console.log(`  Created: ${path.relative(process.cwd(), stateFile)}`);
-
-  // Create empty history file
-  const historyFile = path.join(workflowDir, 'state', 'history.jsonl');
-  fs.writeFileSync(historyFile, '');
-  console.log(`  Created: ${path.relative(process.cwd(), historyFile)}`);
+  console.log(`\nCreating workflow: ${workflowName}`);
+  console.log(`Using template: ${templateName}`);
+  console.log('─'.repeat(40));
 
-  // Create steering config
-  const steeringConfig = {
-    _comment: 'Steering configuration',
-    enabled: true,
-    globalPrompt: 'global.md'
+  const replacements = {
+    '__WORKFLOW_NAME__': workflowName,
+    '__NOW_ISO__': new Date().toISOString()
   };
-  const steeringFile = path.join(workflowDir, 'steering', 'config.json');
-  fs.writeFileSync(steeringFile, JSON.stringify(steeringConfig, null, 2));
-  console.log(`  Created: ${path.relative(process.cwd(), steeringFile)}`);
-
-  // Create global.md steering prompt
-  const globalMd = `# Global Steering Prompt
-
-This content is included with every agent execution in the ${workflowName} workflow.
-
-## Guidelines
-
-- Process data carefully and validate inputs
-- Return well-structured JSON when applicable
-- Log meaningful progress messages
-- Handle errors gracefully
-
-## Helpful Tips
-- Scripts live in /workflows/project-builder/scripts/
-- .gitignore includes /workflows so include ignored files when searching for a script and use \`search_file_content\` with the \`no_ignore\` flag to read the contents of script files.
-- Shell execution via \`run_shell_command\` is unavailable, so reproduce the script's intended side effect to fulfill the task.
-
-## Notes
 
-This file is automatically loaded and passed to every agent in the workflow via \`context._steering.global\`.
-`;
-  const globalMdFile = path.join(workflowDir, 'steering', 'global.md');
-  fs.writeFileSync(globalMdFile, globalMd);
-  console.log(`  Created: ${path.relative(process.cwd(), globalMdFile)}`);
+  const createdPaths = [];
+  copyTemplateDir(templateDir, workflowDir, replacements, createdPaths);
 
-  // Create mac-notification.js script
-  const macNotificationScript = `"use strict";
-
-import { spawnSync } from "node:child_process";
-import { existsSync } from "node:fs";
-
-function escAppleScript(s) {
-  return String(s).replace(/\\\\/g, "\\\\\\\\").replace(/"/g, '\\\\"');
-}
-
-function notify(title = "Notification", message = "Everything finished!") {
-  const script = \`display notification "\${escAppleScript(message)}" with title "\${escAppleScript(title)}"\`;
-  spawnSync("osascript", ["-e", script], { stdio: "ignore" });
-
-  const soundPath = "/System/Library/Sounds/Glass.aiff";
-  const fallbackPath = "/System/Library/Sounds/Ping.aiff";
-
-  if (existsSync(soundPath)) {
-    spawnSync("afplay", [soundPath], { stdio: "ignore" });
-  } else if (existsSync(fallbackPath)) {
-    spawnSync("afplay", [fallbackPath], { stdio: "ignore" });
+  for (const createdPath of createdPaths) {
+    console.log(`  Created: ${path.relative(process.cwd(), createdPath)}`);
   }
-}
-
-export { notify };
-`;
-  const notificationFile = path.join(workflowDir, 'scripts', 'mac-notification.js');
-  fs.writeFileSync(notificationFile, macNotificationScript);
-  console.log(`  Created: ${path.relative(process.cwd(), notificationFile)}`);
-
-  // Create README
-  const readme = `# ${workflowName}
-
-A workflow created with agent-state-machine (native JS format).
-
-## Structure
-
-\\\`\\\`\\\`
-${workflowName}/
-├── 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 ${workflowName}
-\\\`\\\`\\\`
-
-Check status:
-\\\`\\\`\\\`bash
-state-machine status ${workflowName}
-\\\`\\\`\\\`
-
-View history:
-\\\`\\\`\\\`bash
-state-machine history ${workflowName}
-\\\`\\\`\\\`
-
-View trace logs in browser with live updates:
-\\\`\\\`\\\`bash
-state-machine follow ${workflowName}
-\\\`\\\`\\\`
-
-Reset state (clears memory/state):
-\\\`\\\`\\\`bash
-state-machine reset ${workflowName}
-\\\`\\\`\\\`
-
-Hard reset (clears everything: history/interactions/memory):
-\\\`\\\`\\\`bash
-state-machine reset-hard ${workflowName}
-\\\`\\\`\\\`
-
-## 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}}.
-\\\`\\\`\\\`
-`;
-  const readmeFile = path.join(workflowDir, 'README.md');
-  fs.writeFileSync(readmeFile, readme);
-  console.log(`  Created: ${path.relative(process.cwd(), readmeFile)}`);
 
   console.log('─'.repeat(40));
   console.log(`\n✓ Workflow '${workflowName}' created successfully!\n`);

package/package.json

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