agent-state-machine 2.2.0 → 2.2.2

package/templates/project-builder/README.md

@@ -1,60 +1,97 @@
-# project-builder
+# agent-state-machine
 
-A workflow created with agent-state-machine (native JS format).
+A workflow runner for building **linear, stateful agent workflows** in plain JavaScript.
 
-## Structure
+You write normal `async/await` code. The runtime handles:
+- **Auto-persisted** `memory` (saved to disk on mutation)
+- **Auto-tracked** `fileTree` (detects file changes made by agents via Git)
+- **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
 
-\`\`\`
-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
-\`\`\`
+---
+
+## Install
+
+You need to install the package **globally** to get the CLI, and **locally** in your project so your workflow can import the library.
 
-## Usage
+### Global CLI
+Provides the `state-machine` command.
 
-Edit `config.js` to set models and API keys for this workflow.
+```bash
+# npm
+npm i -g agent-state-machine
 
-Run the workflow (or resume if interrupted):
-\`\`\`bash
-state-machine run project-builder
-\`\`\`
+# pnpm
+pnpm add -g agent-state-machine
+```
 
-Check status:
-\`\`\`bash
-state-machine status project-builder
-\`\`\`
+### Local Library
+Required so your `workflow.js` can `import { agent, memory, fileTree } from 'agent-state-machine'`.
 
-View history:
-\`\`\`bash
-state-machine history project-builder
-\`\`\`
+```bash
+# npm
+npm i agent-state-machine
 
-View trace logs in browser with live updates:
-\`\`\`bash
-state-machine follow project-builder
-\`\`\`
+# pnpm (for monorepos/turbo, install in root)
+pnpm add agent-state-machine -w
+```
+
+Requirements: Node.js >= 16.
+
+---
 
-Reset state (clears memory/state):
-\`\`\`bash
-state-machine reset project-builder
-\`\`\`
+## CLI
 
-Hard reset (clears everything: history/interactions/memory):
-\`\`\`bash
-state-machine reset-hard project-builder
-\`\`\`
+```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
 
-## Writing Workflows
+state-machine -reset <workflow-name>
+state-machine -reset-hard <workflow-name>
 
-Edit `workflow.js` - write normal async JavaScript:
+state-machine history <workflow-name> [limit]
+```
+
+Templates live in `templates/` and `starter` is used by default.
+
+Workflows live in:
+
+```text
+workflows/<name>/
+├── 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 files (auto-created)
+├── state/             # current.json, history.jsonl
+└── steering/          # global.md + config.json
+```
+
+---
+
+## Writing workflows (native JS)
+
+Edit `config.js` to set models and API keys for the workflow.
+
+```js
+/**
+/**
+ * project-builder 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
+ */
 
-\`\`\`js
 import { agent, memory, askHuman, parallel } from 'agent-state-machine';
+import { notify } from './scripts/mac-notification.js';
 
 export default async function() {
   console.log('Starting project-builder workflow...');
@@ -71,8 +108,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
@@ -93,27 +130,238 @@ export default async function() {
 
   console.log('Workflow completed!');
 }
-\`\`\`
+```
+
+### Resuming workflows
+
+`state-machine run` restarts your workflow from the top, loading the persisted state.
+
+If the workflow needs human input, it will **block inline** in the terminal. You can answer in the terminal, edit `interactions/<slug>.md`, or respond in the browser.
+
+If the process is interrupted, running `state-machine run <workflow-name>` again will continue execution (assuming your workflow uses `memory` to skip completed steps).
+
+---
+
+## Core API
+
+### `agent(name, params?, options?)`
+
+Runs `workflows/<name>/agents/<agent>.(js|mjs|cjs)` or `<agent>.md`.
+
+```js
+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.
+
+- Mutations auto-save to `workflows/<name>/state/current.json`.
+- Use it as your "long-lived state" between runs.
+
+```js
+memory.count = (memory.count || 0) + 1;
+```
+
+### `fileTree`
+
+Auto-tracked file changes made by agents.
+
+- Before each `await agent(...)`, the runtime captures a Git baseline
+- After the agent completes, it detects created/modified/deleted files
+- Changes are stored in `memory.fileTree` and persisted to `current.json`
+
+```js
+// Files are auto-tracked when agents create them
+await agent('code-writer', { task: 'Create auth module' });
+
+// Access tracked files
+console.log(memory.fileTree);
+// { "src/auth.js": { status: "created", createdBy: "code-writer", ... } }
+
+// Pass file context to other agents
+await agent('code-reviewer', { fileTree: memory.fileTree });
+```
+
+Configuration in `config.js`:
+
+```js
+export const config = {
+  // ... models and apiKeys ...
+  projectRoot: process.env.PROJECT_ROOT,  // defaults to ../.. from workflow
+  fileTracking: true,                     // enable/disable (default: true)
+  fileTrackingIgnore: ['node_modules/**', '.git/**', 'dist/**'],
+  fileTrackingKeepDeleted: false          // keep deleted files in tree
+};
+```
+
+### `trackFile(path, options?)` / `untrackFile(path)`
+
+Manual file tracking utilities:
+
+```js
+import { trackFile, getFileTree, untrackFile } from 'agent-state-machine';
+
+trackFile('README.md', { caption: 'Project docs' });
+const tree = getFileTree();
+untrackFile('old-file.js');
+```
 
-## Creating Agents
+### `askHuman(question, options?)`
 
-**JavaScript agent** (`agents/my-agent.js`):
+Gets user input.
 
-\`\`\`js
+- In a TTY, it prompts in the terminal (or via the browser when remote follow is enabled).
+- Otherwise it creates `interactions/<slug>.md` and blocks until you confirm in the terminal (or respond in the browser).
+
+```js
+const repo = await askHuman('What repo should I work on?', { slug: 'repo' });
+memory.repo = repo;
+```
+
+### `parallel([...])` / `parallelLimit([...], limit)`
+
+Run multiple `agent()` calls concurrently:
+
+```js
+import { agent, parallel, parallelLimit } from 'agent-state-machine';
+
+const [a, b] = await parallel([
+  agent('review', { file: 'src/a.js' }),
+  agent('review', { file: 'src/b.js' }),
+]);
+
+const results = await parallelLimit(
+  ['a.js', 'b.js', 'c.js'].map(f => agent('review', { file: f })),
+  2
+);
+```
+
+---
+
+## Agents
+
+Agents live in `workflows/<workflow>/agents/`.
+
+### JavaScript agents
+
+**ESM (`.js` / `.mjs`)**:
+
+```js
+// workflows/<name>/agents/example.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 };
+  // context includes:
+  // - params passed to agent(name, params)
+  // - context._steering (global + optional additional steering content)
+  // - context._config (models/apiKeys/workflowDir/projectRoot)
+
+  // Optionally return _files to annotate tracked files
+  return {
+    ok: true,
+    _files: [{ path: 'src/example.js', caption: 'Example module' }]
+  };
+}
+```
+
+**CommonJS (`.cjs`)** (only if you prefer CJS):
+
+```js
+// workflows/<name>/agents/example.cjs
+async function handler(context) {
+  return { ok: true };
 }
-\`\`\`
 
-**Markdown agent** (`agents/greeter.md`):
+module.exports = handler;
+module.exports.handler = handler;
+```
+
+If you need to request human input from a JS agent, return an `_interaction` payload:
+
+```js
+return {
+  _interaction: {
+    slug: 'approval',
+    targetKey: 'approval',
+    content: 'Please approve this change (yes/no).'
+  }
+};
+```
+
+The runtime will block execution and wait for your response in the terminal.
+
+### Markdown agents (`.md`)
 
-\`\`\`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: fast
+model: smart
 output: greeting
+steering: tone, product
+---
+Generate a friendly greeting for {{name}}.
+```
+
+Calling it:
+
+```js
+const { greeting } = await agent('greeter', { name: 'Sam' });
+memory.greeting = greeting;
+```
+
+---
+
+## Models & LLM execution
+
+In your workflow’s `export const config = { models: { ... } }`, each model value can be:
+
+### CLI command
+
+```js
+export const config = {
+  models: {
+    smart: "claude -m claude-sonnet-4-20250514 -p"
+  }
+};
+```
+
+### API target
+
+Format: `api:<provider>:<model>`
+
+```js
+export const config = {
+  models: {
+    smart: "api:openai:gpt-4.1-mini"
+  },
+  apiKeys: {
+    openai: process.env.OPENAI_API_KEY
+  }
+};
+```
+
+The runtime captures the fully-built prompt in `state/history.jsonl`, viewable in the browser with live updates when running with the `--local` flag or via the remote URL. Remote follow links persist across runs (stored in `config.js`) unless you pass `-n`/`--new` to regenerate.
+
 ---
-Generate a greeting for {{name}}.
-\`\`\`
+
+## State & persistence
+
+Native JS workflows persist to:
+
+- `workflows/<name>/state/current.json` — status, memory (includes fileTree), pending interaction
+- `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
+
+MIT

package/templates/project-builder/agents/code-fixer.md

@@ -0,0 +1,50 @@
+---
+model: high
+format: json
+---
+
+# Code Fixer Agent
+
+You fix specific issues in existing code based on sanity check failures.
+
+## Critical Guidelines
+
+**DO NOT** disable, skip, or remove failing tests to make them pass.
+Your fixes must address the actual underlying code issues that cause tests to fail.
+
+- ❌ Never add `.skip()`, `.todo()`, or comment out tests
+- ❌ Never modify test expectations to match broken behavior
+- ❌ Never delete test files or test cases
+- ❌ Never wrap tests in `try/catch` to swallow errors
+- ✅ Fix the implementation code to pass existing tests
+- ✅ Fix test setup/teardown issues if the tests themselves are misconfigured
+- ✅ Update tests ONLY if the original requirements were misunderstood
+
+If the issue truly cannot be fixed within the current architecture, set `"confidence": "low"` and explain why in the analysis.
+
+## Input
+- task: Task definition
+- originalImplementation: Current code-writer output
+- sanityCheckResults: Failed checks with specific errors
+- testPlan: Test plan for context
+- previousAttempts: Number of quick-fix attempts so far
+
+## Output Format
+
+{
+  "analysis": {
+    "rootCauses": ["What caused each failure"],
+    "fixApproach": "Strategy for fixing"
+  },
+  "fixes": [
+    {
+      "path": "src/feature.js",
+      "operation": "replace",
+      "code": "// Full corrected file content"
+    }
+  ],
+  "expectedResolutions": ["Which checks should now pass"],
+  "confidence": "high|medium|low"
+}
+
+Focus on minimal, targeted fixes. Don't rewrite entire files unless necessary.

package/templates/project-builder/agents/code-writer.md

@@ -27,6 +27,9 @@ Implement the task following these principles:
 - Implement to satisfy the test plan
 - Ensure all test cases can pass
 - Consider edge cases identified in testing
+- Write runnable test files, not just descriptions
+- Use appropriate test locations (e.g. *.test.js, *.spec.js, __tests__/)
+- Tests must import and exercise real implementation functions
 
 ## Output Format
 

package/templates/project-builder/agents/sanity-checker.md

@@ -9,6 +9,7 @@ Input:
 - task: { title, description, doneDefinition, sanityCheck }
 - implementation: code-writer output
 - testPlan: test-planner output
+- testFramework: { framework, command }
 
 Return JSON only in this shape:
 {
@@ -34,6 +35,8 @@ Guidelines:
 - If the task describes a server endpoint, include a curl check.
 - Keep checks short, clear, and runnable.
 - Include at least one file_exists or file_contains check when files are created/modified.
+- If tests exist (from testPlan or implementation), include a type "test_suite" check.
+- Use testFramework.command for running tests (optionally target specific files when possible).
 
 Task:
 {{task}}
@@ -43,3 +46,6 @@ Implementation:
 
 Test Plan:
 {{testPlan}}
+
+Test Framework:
+{{testFramework}}

package/templates/project-builder/agents/sanity-runner.js

@@ -6,7 +6,9 @@ const DEFAULT_TIMEOUT_MS = 30000;
 
 export default async function sanityRunner(context) {
   const { checks = [], setup, teardown } = context;
-  const cwd = context?._config?.workflowDir || process.cwd();
+  const workflowDir = context?._config?.workflowDir || process.cwd();
+  const projectRoot = context?._config?.projectRoot || workflowDir;
+  const cwd = projectRoot;
   const results = [];
 
   let setupError = null;

package/templates/project-builder/agents/test-planner.md

@@ -22,6 +22,7 @@ Create a comprehensive test plan for the task. Include:
 - Cover happy path and error cases
 - Include tests for security concerns flagged in review
 - Prioritize tests by risk and importance
+- Provide expected test file paths for planned tests
 
 ## Output Format
 
@@ -59,7 +60,8 @@ Return a valid JSON object:
         "scenario": "Empty input handling",
         "expectedBehavior": "Return validation error"
       }
-    ]
+    ],
+    "testFilePaths": ["src/feature.test.js"]
   },
   "testingNotes": "Any special considerations or setup needed"
 }

package/templates/project-builder/config.js

@@ -1,9 +1,9 @@
 export const config = {
   models: {
-    fast: "gemini",
-    low: "gemini",
-    med: "gemini",
-    high: "gemini",
+    fast: "gemini -m gemini-2.5-flash-lite",
+    low: "gemini -m gemini-2.5-flash-lite",
+    med: "gemini -m gemini-2.5-flash-lite",
+    high: "gemini -m gemini-2.5-flash-lite",
   },
   apiKeys: {
     gemini: process.env.GEMINI_API_KEY,

package/templates/project-builder/scripts/workflow-helpers.js

@@ -1,6 +1,39 @@
 import fs from 'fs';
 import path from 'path';
-import { memory } from 'agent-state-machine';
+import { memory, getCurrentRuntime } from 'agent-state-machine';
+
+// Write implementation files from code-writer agent output
+function writeImplementationFiles(implementation) {
+  const runtime = getCurrentRuntime();
+  if (!runtime) {
+    throw new Error('writeImplementationFiles must be called within a workflow context');
+  }
+
+  const projectRoot = runtime.workflowConfig.projectRoot;
+  const files = implementation?.implementation?.files || implementation?.files || [];
+  const written = [];
+
+  for (const file of files) {
+    if (!file.path || !file.code) {
+      console.warn(`  [File] Skipping invalid file entry: ${JSON.stringify(file)}`);
+      continue;
+    }
+
+    const fullPath = path.resolve(projectRoot, file.path);
+
+    // Ensure directory exists
+    const dir = path.dirname(fullPath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+
+    fs.writeFileSync(fullPath, file.code);
+    written.push(file.path);
+    console.log(`  [File] Created: ${file.path}`);
+  }
+
+  return written;
+}
 
 // Write markdown file to workflow state directory
 function writeMarkdownFile(stateDir, filename, content) {
@@ -109,8 +142,72 @@ function setTaskData(phaseIndex, taskId, dataKey, value) {
   memory[key] = value;
 }
 
+function clearPartialTaskData(phaseIndex, taskId, keepKeys = []) {
+  const allKeys = [
+    'security_pre',
+    'tests',
+    'code',
+    'review',
+    'security_post',
+    'sanity_checks',
+    'sanity_results'
+  ];
+  for (const key of allKeys) {
+    if (!keepKeys.includes(key)) {
+      setTaskData(phaseIndex, taskId, key, null);
+    }
+  }
+}
+
+function getQuickFixAttempts(phaseIndex, taskId) {
+  return getTaskData(phaseIndex, taskId, 'quick_fix_attempts') || 0;
+}
+
+function incrementQuickFixAttempts(phaseIndex, taskId) {
+  const current = getQuickFixAttempts(phaseIndex, taskId);
+  setTaskData(phaseIndex, taskId, 'quick_fix_attempts', current + 1);
+}
+
+function resetQuickFixAttempts(phaseIndex, taskId) {
+  setTaskData(phaseIndex, taskId, 'quick_fix_attempts', 0);
+}
+
+function detectTestFramework() {
+  const runtime = getCurrentRuntime();
+  const projectRoot = runtime?.workflowConfig?.projectRoot || process.cwd();
+  const pkgPath = path.join(projectRoot, 'package.json');
+
+  if (!fs.existsSync(pkgPath)) {
+    return { framework: 'vitest', command: 'npx vitest run', isDefault: true };
+  }
+
+  let pkg;
+  try {
+    pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+  } catch (error) {
+    console.warn(`  [Test] Failed to parse package.json: ${error.message}`);
+    return { framework: 'vitest', command: 'npx vitest run', isDefault: true };
+  }
+
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+  const testScript = pkg.scripts?.test || '';
+
+  if (testScript.includes('vitest') || deps.vitest) {
+    return { framework: 'vitest', command: 'npm test' };
+  }
+  if (testScript.includes('jest') || deps.jest) {
+    return { framework: 'jest', command: 'npm test' };
+  }
+  if (testScript.includes('mocha') || deps.mocha) {
+    return { framework: 'mocha', command: 'npm test' };
+  }
+
+  return { framework: 'vitest', command: 'npx vitest run', isDefault: true };
+}
+
 export {
   writeMarkdownFile,
+  writeImplementationFiles,
   isApproval,
   renderRoadmapMarkdown,
   renderTasksMarkdown,
@@ -118,5 +215,10 @@ export {
   getTaskStage,
   setTaskStage,
   getTaskData,
-  setTaskData
+  setTaskData,
+  clearPartialTaskData,
+  getQuickFixAttempts,
+  incrementQuickFixAttempts,
+  resetQuickFixAttempts,
+  detectTestFramework
 };