agent-state-machine 2.2.0 → 2.2.2

package/templates/project-builder/workflow.js

@@ -8,11 +8,12 @@
  * 4. Task lifecycle with optimal agent sequencing
  */
 
-import { agent, memory, askHuman } from 'agent-state-machine';
+import { agent, memory, askHuman, getCurrentRuntime } from 'agent-state-machine';
 import path from 'path';
 import { fileURLToPath } from 'url';
 import {
   writeMarkdownFile,
+  writeImplementationFiles,
   isApproval,
   renderRoadmapMarkdown,
   renderTasksMarkdown,
@@ -20,7 +21,12 @@ import {
   getTaskStage,
   setTaskStage,
   getTaskData,
-  setTaskData
+  setTaskData,
+  clearPartialTaskData,
+  getQuickFixAttempts,
+  incrementQuickFixAttempts,
+  resetQuickFixAttempts,
+  detectTestFramework
 } from './scripts/workflow-helpers.js';
 import {
   createInteraction,
@@ -34,6 +40,57 @@ const __dirname = path.dirname(__filename);
 const WORKFLOW_DIR = __dirname;
 const STATE_DIR = path.join(WORKFLOW_DIR, 'state');
 
+// ANSI Colors for console output
+const C = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  cyan: '\x1b[36m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m'
+};
+
+function applyFixesToImplementation(originalImplementation, fixes) {
+  if (!originalImplementation || !Array.isArray(fixes) || fixes.length === 0) {
+    return originalImplementation;
+  }
+
+  const updated = { ...originalImplementation };
+  const container = updated.implementation ? { ...updated.implementation } : updated;
+  const files = Array.isArray(container.files) ? [...container.files] : [];
+
+  for (const fix of fixes) {
+    if (!fix?.path || !fix?.code) {
+      console.warn(`  [Fix] Skipping invalid fix entry: ${JSON.stringify(fix)}`);
+      continue;
+    }
+    if (fix.operation && fix.operation !== 'replace') {
+      console.warn(`  [Fix] Unsupported operation "${fix.operation}" for ${fix.path}`);
+      continue;
+    }
+
+    const existingIndex = files.findIndex((file) => file.path === fix.path);
+    const nextFile = {
+      ...(existingIndex >= 0 ? files[existingIndex] : {}),
+      path: fix.path,
+      code: fix.code,
+      purpose: fix.purpose || (existingIndex >= 0 ? files[existingIndex].purpose : 'Updated by code-fixer')
+    };
+
+    if (existingIndex >= 0) {
+      files[existingIndex] = nextFile;
+    } else {
+      files.push(nextFile);
+    }
+  }
+
+  if (updated.implementation) {
+    updated.implementation = { ...container, files };
+    return updated;
+  }
+
+  return { ...updated, files };
+}
+
 // ============================================
 // MAIN WORKFLOW
 // ============================================
@@ -334,6 +391,14 @@ export default async function () {
             });
             setTaskData(i, taskId, 'code', implementation);
           }
+
+          // Write implementation files to disk
+          const implementation = getTaskData(i, taskId, 'code');
+          if (implementation) {
+            console.log('    > Writing files to disk...');
+            writeImplementationFiles(implementation);
+          }
+
           setTaskStage(i, taskId, TASK_STAGES.CODE_REVIEW);
           stage = TASK_STAGES.CODE_REVIEW;
         }
@@ -373,10 +438,12 @@ export default async function () {
 
         // 6. Sanity check generation & execution
         if (stage === TASK_STAGES.SANITY_CHECK) {
+          const testFramework = detectTestFramework();
           const executableChecks = await agent('sanity-checker', {
             task: task,
             implementation: getTaskData(i, taskId, 'code'),
-            testPlan: getTaskData(i, taskId, 'tests')
+            testPlan: getTaskData(i, taskId, 'tests'),
+            testFramework
           });
           setTaskData(i, taskId, 'sanity_checks', executableChecks);
 
@@ -387,8 +454,8 @@ export default async function () {
           const sanityChoice = createInteraction('choice', `phase-${i + 1}-task-${taskId}-sanity-choice`, {
             prompt: `Sanity checks for "${task.title}":\n\n${checksDisplay}\n\nHow would you like to proceed?`,
             options: [
-              { key: 'manual', label: 'Run checks manually', description: 'You run the commands and confirm results' },
               { key: 'auto', label: 'Run automatically', description: 'Agent executes checks and reports results' },
+              { key: 'manual', label: 'Run checks manually', description: 'You run the commands and confirm results' },
               { key: 'skip', label: 'Skip verification', description: 'Approve without running checks' }
             ],
             allowCustom: true
@@ -402,6 +469,7 @@ export default async function () {
 
           if (sanityResponse.isCustom) {
             setTaskData(i, taskId, 'feedback', sanityResponse.customText || sanityResponse.raw || sanityRaw);
+            resetQuickFixAttempts(i, taskId);
             setTaskStage(i, taskId, TASK_STAGES.PENDING);
             t--;
             continue;
@@ -423,12 +491,26 @@ export default async function () {
                 .map((r) => `  - Check ${r.id}: ${r.error}`)
                 .join('\n');
 
+              const quickFixAttempts = getQuickFixAttempts(i, taskId);
+              const runtime = getCurrentRuntime();
+              const maxAttempts = runtime?.workflowConfig?.maxQuickFixAttempts ?? 10;
+              const failOptions = [];
+              if (quickFixAttempts < maxAttempts) {
+                failOptions.push({
+                  key: 'quickfix',
+                  label: 'Quick fix',
+                  description: `Run targeted fixes (attempt ${quickFixAttempts + 1} of ${maxAttempts})`
+                });
+              }
+              failOptions.push(
+                { key: 'partial', label: 'Partial reimplement', description: 'Keep security review and test plan, redo implementation' },
+                { key: 'reimplement', label: 'Full reimplement', description: 'Restart task from scratch' },
+                { key: 'ignore', label: 'Ignore failures and approve anyway' }
+              );
+
               const failChoice = createInteraction('choice', `phase-${i + 1}-task-${taskId}-sanity-fail`, {
                 prompt: `${results.summary.failed} sanity check(s) failed:\n\n${failedChecks}\n\nHow would you like to proceed?`,
-                options: [
-                  { key: 'reimplement', label: 'Re-implement task with this feedback' },
-                  { key: 'ignore', label: 'Ignore failures and approve anyway' }
-                ],
+                options: failOptions,
                 allowCustom: true
               });
 
@@ -438,19 +520,71 @@ export default async function () {
               });
               const failResponse = await parseResponse(failChoice, failRaw);
 
-              if (failResponse.selectedKey === 'reimplement' || failResponse.isCustom) {
+              if (failResponse.isCustom) {
+                const customFeedback = failResponse.customText || failResponse.text || failResponse.raw || failRaw;
+                const combinedFeedback = `${customFeedback}\n\nSanity check failures:\n${failedChecks}`;
+                setTaskData(i, taskId, 'feedback', combinedFeedback);
+                clearPartialTaskData(i, taskId);
+                resetQuickFixAttempts(i, taskId);
+                setTaskStage(i, taskId, TASK_STAGES.PENDING);
+                t--;
+                continue;
+              }
+
+              if (failResponse.selectedKey === 'quickfix') {
+                console.log('    > Running quick fix...');
+                const fixerResult = await agent('code-fixer', {
+                  task: task,
+                  originalImplementation: getTaskData(i, taskId, 'code'),
+                  sanityCheckResults: {
+                    summary: results.summary,
+                    results: results.results,
+                    checks: executableChecks.checks
+                  },
+                  testPlan: getTaskData(i, taskId, 'tests'),
+                  previousAttempts: quickFixAttempts
+                });
+
+                const fixes = fixerResult?.fixes || [];
+                const fixFiles = fixes
+                  .filter((fix) => fix?.path && fix?.code && (!fix.operation || fix.operation === 'replace'))
+                  .map((fix) => ({ path: fix.path, code: fix.code }));
+
+                if (fixFiles.length > 0) {
+                  console.log('    > Applying fixes to disk...');
+                  writeImplementationFiles({ files: fixFiles });
+                }
+
+                const updatedImplementation = applyFixesToImplementation(getTaskData(i, taskId, 'code'), fixes);
+                setTaskData(i, taskId, 'code', updatedImplementation);
+                incrementQuickFixAttempts(i, taskId);
+                setTaskData(i, taskId, 'sanity_checks', null);
+                setTaskData(i, taskId, 'sanity_results', null);
+                setTaskStage(i, taskId, TASK_STAGES.SANITY_CHECK);
+                t--;
+                continue;
+              }
+
+              if (failResponse.selectedKey === 'partial') {
+                setTaskData(i, taskId, 'feedback', `Sanity check failures:\n${failedChecks}`);
+                clearPartialTaskData(i, taskId, ['security_pre', 'tests']);
+                resetQuickFixAttempts(i, taskId);
+                setTaskStage(i, taskId, TASK_STAGES.IMPLEMENTING);
+                t--;
+                continue;
+              }
+
+              if (failResponse.selectedKey === 'reimplement') {
                 setTaskData(i, taskId, 'feedback', `Sanity check failures:\n${failedChecks}`);
-                setTaskData(i, taskId, 'security_pre', null);
-                setTaskData(i, taskId, 'tests', null);
-                setTaskData(i, taskId, 'code', null);
-                setTaskData(i, taskId, 'review', null);
-                setTaskData(i, taskId, 'security_post', null);
+                clearPartialTaskData(i, taskId);
+                resetQuickFixAttempts(i, taskId);
                 setTaskStage(i, taskId, TASK_STAGES.PENDING);
                 t--;
                 continue;
               }
             }
 
+            resetQuickFixAttempts(i, taskId);
             setTaskStage(i, taskId, TASK_STAGES.COMPLETED);
             stage = TASK_STAGES.COMPLETED;
             task.stage = 'completed';
@@ -458,6 +592,7 @@ export default async function () {
             writeMarkdownFile(STATE_DIR, `phase-${i + 1}-tasks.md`, renderTasksMarkdown(i + 1, phase.title, tasks));
             console.log(`    Task ${t + 1} confirmed complete!\n`);
           } else if (action === 'skip') {
+            resetQuickFixAttempts(i, taskId);
             setTaskStage(i, taskId, TASK_STAGES.COMPLETED);
             stage = TASK_STAGES.COMPLETED;
             task.stage = 'completed';
@@ -489,6 +624,7 @@ export default async function () {
 
           if (approvalResponse.selectedKey === 'approve' || isApproval(approvalResponse.raw || approvalRaw)) {
             setTaskStage(i, taskId, TASK_STAGES.COMPLETED);
+            resetQuickFixAttempts(i, taskId);
             task.stage = 'completed';
             memory[tasksKey] = tasks;
             writeMarkdownFile(STATE_DIR, `phase-${i + 1}-tasks.md`, renderTasksMarkdown(i + 1, phase.title, tasks));
@@ -505,6 +641,7 @@ export default async function () {
             setTaskData(i, taskId, 'security_post', null);
             setTaskData(i, taskId, 'sanity_checks', null);
             setTaskData(i, taskId, 'sanity_results', null);
+            resetQuickFixAttempts(i, taskId);
 
             setTaskStage(i, taskId, TASK_STAGES.PENDING);
             t--;

package/templates/starter/README.md

@@ -1,62 +1,100 @@
-# __WORKFLOW_NAME__
+# 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
 
-```
-__WORKFLOW_NAME__/
-├── workflow.js      # Native JS workflow (async/await)
-├── config.js        # Model/API key configuration
-├── 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
+## Install
 
-Edit `config.js` to set models and API keys for this workflow.
+You need to install the package **globally** to get the CLI, and **locally** in your project so your workflow can import the library.
 
-Run the workflow (or resume if interrupted):
-```bash
-state-machine run __WORKFLOW_NAME__
-```
+### Global CLI
+Provides the `state-machine` command.
 
-Check status:
 ```bash
-state-machine status __WORKFLOW_NAME__
-```
+# npm
+npm i -g agent-state-machine
 
-View history:
-```bash
-state-machine history __WORKFLOW_NAME__
+# pnpm
+pnpm add -g agent-state-machine
 ```
 
-View trace logs in browser with live updates:
+### Local Library
+Required so your `workflow.js` can `import { agent, memory, fileTree } from 'agent-state-machine'`.
+
 ```bash
-state-machine follow __WORKFLOW_NAME__
+# npm
+npm i agent-state-machine
+
+# pnpm (for monorepos/turbo, install in root)
+pnpm add agent-state-machine -w
 ```
 
-Reset state (clears memory/state):
+Requirements: Node.js >= 16.
+
+---
+
+## CLI
+
 ```bash
-state-machine reset __WORKFLOW_NAME__
+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]
 ```
 
-Hard reset (clears everything: history/interactions/memory):
-```bash
-state-machine reset-hard __WORKFLOW_NAME__
+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
+---
 
-Edit `workflow.js` - write normal async JavaScript:
+## 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
+ */
+
 import { agent, memory, askHuman, parallel } from 'agent-state-machine';
+import { notify } from './scripts/mac-notification.js';
 
 export default async function() {
-  console.log('Starting __WORKFLOW_NAME__ workflow...');
+  console.log('Starting project-builder workflow...');
 
   // Example: Get user input (saved to memory)
   const userLocation = await askHuman('Where do you live?');
@@ -88,31 +126,242 @@ export default async function() {
   // console.log('b: ' + JSON.stringify(b))
   // console.log('c: ' + JSON.stringify(c))
 
-  notify(['__WORKFLOW_NAME__', userInfo.name || userInfo + ' has been greeted!']);
+  notify(['project-builder', userInfo.name || userInfo + ' has been greeted!']);
 
   console.log('Workflow completed!');
 }
 ```
 
-## Creating Agents
+### 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');
+```
+
+### `askHuman(question, options?)`
+
+Gets user input.
+
+- 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)`
 
-**JavaScript agent** (`agents/my-agent.js`):
+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 };
 }
+
+module.exports = handler;
+module.exports.handler = handler;
 ```
 
-**Markdown agent** (`agents/greeter.md`):
+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`)
+
+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;
+```
+
 ---
-Generate a greeting for {{name}}.
+
+## 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.
+
+---
+
+## 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/starter/config.js

@@ -1,6 +1,6 @@
 export const config = {
   models: {
-    low: "gemini",
+    low: "gemini -m gemini-2.5-flash-lite",
     med: "codex --model gpt-5.2",
     high: "claude -m claude-opus-4-20250514 -p",
   },

package/vercel-server/api/submit/[token].js

@@ -6,7 +6,6 @@
 
 import {
   getSession,
-  addEvent,
   redis,
   KEYS,
 } from '../../lib/redis.js';
@@ -66,18 +65,8 @@ export default async function handler(req, res) {
       response,
     }));
 
-    // Set TTL on pending list
-    await redis.expire(pendingKey, 300); // 5 minutes
-
-    // Log event to events list (single source of truth for UI)
-    await addEvent(token, {
-      timestamp: new Date().toISOString(),
-      event: 'INTERACTION_SUBMITTED',
-      slug,
-      targetKey: targetKey || `_interaction_${slug}`,
-      answer: responseString.substring(0, 200) + (responseString.length > 200 ? '...' : ''),
-      source: 'remote',
-    });
+    // Set TTL on pending list (24 hours - same as session, allows laptop sleep)
+    await redis.expire(pendingKey, 24 * 60 * 60);
 
     return res.status(200).json({ success: true });
   } catch (err) {