agent-state-machine 2.0.13 → 2.0.15

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/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.13",
+  "version": "2.0.15",
   "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",