agent-state-machine 2.1.9 → 2.2.1

package/README.md

@@ -4,6 +4,7 @@ A workflow runner for building **linear, stateful agent workflows** in plain Jav
 
 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
@@ -26,7 +27,7 @@ pnpm add -g agent-state-machine
 ```
 
 ### Local Library
-Required so your `workflow.js` can `import { agent, memory } from 'agent-state-machine'`.
+Required so your `workflow.js` can `import { agent, memory, fileTree } from 'agent-state-machine'`.
 
 ```bash
 # npm
@@ -163,12 +164,56 @@ Context is explicit: only `params` are provided to agents unless you pass additi
 A persisted object for your workflow.
 
 - Mutations auto-save to `workflows/<name>/state/current.json`.
-- Use it as your “long-lived state” between runs.
+- 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.
@@ -217,8 +262,13 @@ export default async function handler(context) {
   // context includes:
   // - params passed to agent(name, params)
   // - context._steering (global + optional additional steering content)
-  // - context._config (models/apiKeys/workflowDir)
-  return { ok: true };
+  // - context._config (models/apiKeys/workflowDir/projectRoot)
+
+  // Optionally return _files to annotate tracked files
+  return {
+    ok: true,
+    _files: [{ path: 'src/example.js', caption: 'Example module' }]
+  };
 }
 ```
 
@@ -308,7 +358,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/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)
 

package/bin/cli.js

@@ -3,6 +3,7 @@
 import path from 'path';
 import fs from 'fs';
 import readline from 'readline';
+import { spawn } from 'child_process';
 import { pathToFileURL, fileURLToPath } from 'url';
 import { WorkflowRuntime } from '../lib/index.js';
 import { setup } from '../lib/setup.js';
@@ -11,6 +12,41 @@ import { readRemotePathFromConfig, writeRemotePathToConfig } from '../lib/config
 
 import { startLocalServer } from '../vercel-server/local-server.js';
 
+/**
+ * Prevent system sleep on macOS using caffeinate
+ * Returns a function to stop caffeinate, or null if not available
+ */
+function preventSleep() {
+  // Only works on macOS
+  if (process.platform !== 'darwin') {
+    return null;
+  }
+
+  try {
+    // -i: prevent idle sleep (system stays awake)
+    // -s: prevent sleep when on AC power
+    // Display can still sleep (screen goes black, requires password)
+    const caffeinate = spawn('caffeinate', ['-is'], {
+      stdio: 'ignore',
+      detached: false,
+    });
+
+    caffeinate.on('error', () => {
+      // caffeinate not available, ignore
+    });
+
+    return () => {
+      try {
+        caffeinate.kill();
+      } catch {
+        // Already dead, ignore
+      }
+    };
+  } catch {
+    return null;
+  }
+}
+
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
@@ -258,9 +294,21 @@ async function runOrResume(
     await runtime.enableRemote(remoteUrl, { sessionToken, uiBaseUrl: useLocalServer });
   }
 
+  // Prevent system sleep while workflow runs (macOS only)
+  // Display can still sleep, but system stays awake for remote follow
+  const stopCaffeinate = preventSleep();
+  if (stopCaffeinate) {
+    console.log('☕ Preventing system sleep while workflow runs (display may still sleep)');
+  }
+
   try {
     await runtime.runWorkflow(workflowUrl);
   } finally {
+    // Allow sleep again
+    if (stopCaffeinate) {
+      stopCaffeinate();
+    }
+
     // Keep local server alive after run so the session remains accessible.
     if (!useLocalServer && remoteUrl) {
       await runtime.disableRemote();

package/lib/file-tree.js

@@ -0,0 +1,366 @@
+/**
+ * File: /lib/file-tree.js
+ *
+ * File tree tracking utilities for agent-state-machine.
+ * Provides Git-based and filesystem-based change detection.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { exec } from 'child_process';
+import { promisify } from 'util';
+
+const execAsync = promisify(exec);
+
+// Default ignore patterns (mainly for FS fallback, git respects .gitignore)
+export const DEFAULT_IGNORE = [
+  'node_modules/**',
+  '.git/**',
+  'dist/**',
+  'build/**',
+  'coverage/**',
+  '.next/**',
+  '.cache/**',
+  'workflows/**',
+  '*.log',
+  '.DS_Store'
+];
+
+/**
+ * Normalize a path for consistent storage.
+ * - Converts backslashes to forward slashes
+ * - Rejects absolute paths
+ * - Rejects traversal outside projectRoot
+ */
+export function normalizePath(relativePath, projectRoot) {
+  // Normalize slashes
+  const normalized = relativePath.replace(/\\/g, '/');
+
+  // Reject absolute paths
+  if (path.isAbsolute(normalized)) {
+    throw new Error(`Absolute path not allowed: ${normalized}`);
+  }
+
+  // Reject traversal outside projectRoot
+  const resolved = path.resolve(projectRoot, normalized);
+  const normalizedRoot = projectRoot.endsWith(path.sep) ? projectRoot : projectRoot + path.sep;
+  if (!resolved.startsWith(normalizedRoot) && resolved !== projectRoot.replace(/\/$/, '')) {
+    // Also allow exact match with projectRoot
+    if (resolved !== projectRoot) {
+      throw new Error(`Path traversal outside projectRoot: ${normalized}`);
+    }
+  }
+
+  return normalized;
+}
+
+/**
+ * Check if a path matches any of the ignore patterns.
+ */
+export function shouldIgnore(relativePath, ignorePatterns = DEFAULT_IGNORE) {
+  const normalized = relativePath.replace(/\\/g, '/');
+
+  for (const pattern of ignorePatterns) {
+    // Simple glob matching
+    if (pattern.endsWith('/**')) {
+      const prefix = pattern.slice(0, -3);
+      if (normalized.startsWith(prefix + '/') || normalized === prefix) {
+        return true;
+      }
+    } else if (pattern.startsWith('*.')) {
+      const ext = pattern.slice(1);
+      if (normalized.endsWith(ext)) {
+        return true;
+      }
+    } else if (normalized === pattern || normalized.startsWith(pattern + '/')) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+// ============================================================================
+// Git-based change detection
+// ============================================================================
+
+/**
+ * Parse git status --porcelain -z output into a Map.
+ * Format: XY PATH\0 (or XY ORIG\0PATH\0 for renames)
+ */
+function parseGitStatus(stdout) {
+  const files = new Map();
+  if (!stdout) return files;
+
+  const entries = stdout.split('\0').filter(Boolean);
+  let i = 0;
+
+  while (i < entries.length) {
+    const entry = entries[i];
+    if (entry.length < 3) {
+      i++;
+      continue;
+    }
+
+    const statusCode = entry.slice(0, 2);
+    const filePath = entry.slice(3);
+
+    // Handle renames (R) - next entry is the new path
+    if (statusCode.startsWith('R') || statusCode.startsWith('C')) {
+      i++;
+      const newPath = entries[i];
+      if (newPath) {
+        files.set(newPath, statusCode);
+      }
+    } else {
+      files.set(filePath, statusCode);
+    }
+
+    i++;
+  }
+
+  return files;
+}
+
+/**
+ * Capture current git status as a baseline.
+ * Returns Map of file paths to their status codes.
+ */
+export async function captureGitBaseline(projectRoot) {
+  try {
+    // Check if git repo
+    await execAsync('git rev-parse --git-dir', { cwd: projectRoot });
+
+    // Get status: untracked + staged + unstaged
+    const { stdout } = await execAsync(
+      'git status --porcelain -z',
+      { cwd: projectRoot, maxBuffer: 10 * 1024 * 1024 }
+    );
+
+    return { files: parseGitStatus(stdout), isGitRepo: true };
+  } catch {
+    return { files: new Map(), isGitRepo: false };
+  }
+}
+
+/**
+ * Detect changes between baseline and current state.
+ * Only attributes changes made since baseline capture.
+ */
+export async function detectGitChanges(projectRoot, baseline, ignorePatterns = DEFAULT_IGNORE) {
+  const after = await captureGitBaseline(projectRoot);
+
+  const created = [];
+  const modified = [];
+  const deleted = [];
+
+  // Find new and modified files
+  for (const [filePath, status] of after.files) {
+    if (shouldIgnore(filePath, ignorePatterns)) continue;
+
+    if (!baseline.files.has(filePath)) {
+      created.push(filePath);
+    } else if (baseline.files.get(filePath) !== status) {
+      modified.push(filePath);
+    }
+  }
+
+  // Find deleted files
+  for (const [filePath] of baseline.files) {
+    if (shouldIgnore(filePath, ignorePatterns)) continue;
+
+    if (!after.files.has(filePath)) {
+      deleted.push(filePath);
+    }
+  }
+
+  // MVP: Treat renames as delete+create
+  // Future: Use `git diff --name-status -z -M` for rename detection
+  return { created, modified, deleted, renamed: [] };
+}
+
+// ============================================================================
+// Filesystem-based change detection (fallback when no git)
+// ============================================================================
+
+/**
+ * Recursively walk a directory and collect file info.
+ */
+async function walkDirectory(dir, baseDir, ignorePatterns, result = new Map()) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return result;
+  }
+
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    const relativePath = path.relative(baseDir, fullPath).replace(/\\/g, '/');
+
+    if (shouldIgnore(relativePath, ignorePatterns)) continue;
+
+    if (entry.isDirectory()) {
+      await walkDirectory(fullPath, baseDir, ignorePatterns, result);
+    } else if (entry.isFile()) {
+      try {
+        const stats = fs.statSync(fullPath);
+        result.set(relativePath, {
+          mtime: stats.mtimeMs,
+          size: stats.size
+        });
+      } catch {
+        // File may have been deleted between readdir and stat
+      }
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Capture filesystem snapshot for change detection.
+ */
+export async function captureFilesystemSnapshot(projectRoot, ignorePatterns = DEFAULT_IGNORE) {
+  const files = await walkDirectory(projectRoot, projectRoot, ignorePatterns);
+  return { files, isGitRepo: false };
+}
+
+/**
+ * Detect filesystem changes between baseline and current state.
+ */
+export async function detectFilesystemChanges(projectRoot, baseline, ignorePatterns = DEFAULT_IGNORE) {
+  const after = await captureFilesystemSnapshot(projectRoot, ignorePatterns);
+
+  const created = [];
+  const modified = [];
+  const deleted = [];
+
+  // Find new and modified files
+  for (const [filePath, info] of after.files) {
+    const baselineInfo = baseline.files.get(filePath);
+
+    if (!baselineInfo) {
+      created.push(filePath);
+    } else if (baselineInfo.mtime !== info.mtime || baselineInfo.size !== info.size) {
+      modified.push(filePath);
+    }
+  }
+
+  // Find deleted files
+  for (const [filePath] of baseline.files) {
+    if (!after.files.has(filePath)) {
+      deleted.push(filePath);
+    }
+  }
+
+  return { created, modified, deleted, renamed: [] };
+}
+
+/**
+ * Unified baseline capture - uses Git if available, falls back to filesystem.
+ */
+export async function captureBaseline(projectRoot, ignorePatterns = DEFAULT_IGNORE) {
+  const gitBaseline = await captureGitBaseline(projectRoot);
+
+  if (gitBaseline.isGitRepo) {
+    return gitBaseline;
+  }
+
+  return captureFilesystemSnapshot(projectRoot, ignorePatterns);
+}
+
+/**
+ * Unified change detection - uses Git if available, falls back to filesystem.
+ */
+export async function detectChanges(projectRoot, baseline, ignorePatterns = DEFAULT_IGNORE) {
+  if (baseline.isGitRepo) {
+    return detectGitChanges(projectRoot, baseline, ignorePatterns);
+  }
+
+  return detectFilesystemChanges(projectRoot, baseline, ignorePatterns);
+}
+
+// ============================================================================
+// Export extraction (best-effort)
+// ============================================================================
+
+/**
+ * Extract exports from JavaScript/TypeScript file content using regex.
+ * This is a best-effort extraction, not a full parser.
+ */
+export function extractExportsFromContent(content) {
+  if (!content || typeof content !== 'string') return null;
+
+  const exports = new Set();
+
+  // export const/let/var/function/class Name
+  const namedExportPattern = /export\s+(?:const|let|var|function|class|async\s+function)\s+(\w+)/g;
+  let match;
+  while ((match = namedExportPattern.exec(content)) !== null) {
+    exports.add(match[1]);
+  }
+
+  // export { Name, Name2 as Alias }
+  const bracedExportPattern = /export\s*\{([^}]+)\}/g;
+  while ((match = bracedExportPattern.exec(content)) !== null) {
+    const items = match[1].split(',');
+    for (const item of items) {
+      const name = item.trim().split(/\s+as\s+/)[0].trim();
+      if (name && /^\w+$/.test(name)) {
+        exports.add(name);
+      }
+    }
+  }
+
+  // export default (tracked as 'default')
+  if (/export\s+default\s/.test(content)) {
+    exports.add('default');
+  }
+
+  // module.exports = { name: ... } (CommonJS)
+  const cjsPattern = /module\.exports\s*=\s*\{([^}]+)\}/;
+  const cjsMatch = content.match(cjsPattern);
+  if (cjsMatch) {
+    const items = cjsMatch[1].split(',');
+    for (const item of items) {
+      const name = item.split(':')[0].trim();
+      if (name && /^\w+$/.test(name)) {
+        exports.add(name);
+      }
+    }
+  }
+
+  // module.exports = Name (CommonJS default)
+  const cjsDefaultPattern = /module\.exports\s*=\s*(\w+)\s*[;\n]/;
+  const cjsDefaultMatch = content.match(cjsDefaultPattern);
+  if (cjsDefaultMatch && cjsDefaultMatch[1] !== '{') {
+    exports.add('default');
+  }
+
+  return exports.size > 0 ? Array.from(exports).sort() : null;
+}
+
+/**
+ * Extract exports from a file on disk.
+ */
+export function extractExportsFromFile(absolutePath) {
+  if (!fs.existsSync(absolutePath)) return null;
+
+  const ext = path.extname(absolutePath).toLowerCase();
+  if (!['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx'].includes(ext)) return null;
+
+  try {
+    const content = fs.readFileSync(absolutePath, 'utf-8');
+    return extractExportsFromContent(content);
+  } catch {
+    return null;
+  }
+}
+
+// ============================================================================
+// File tree management (for manual tracking)
+// ============================================================================
+
+// These functions require access to the runtime, so they're implemented
+// in track-changes.js and re-exported from index.js

package/lib/index.js

@@ -6,6 +6,12 @@
 
 import { setup } from './setup.js';
 import { llm, llmText, llmJSON, parseJSON, detectAvailableCLIs } from './llm.js';
+import { extractExportsFromContent, extractExportsFromFile } from './file-tree.js';
+import {
+  trackFile as trackFileInternal,
+  getFileTree as getFileTreeInternal,
+  untrackFile as untrackFileInternal
+} from './runtime/track-changes.js';
 
 import {
   WorkflowRuntime,
@@ -83,6 +89,97 @@ export const memory = new Proxy(
   }
 );
 
+/**
+ * Live fileTree proxy:
+ * - Reads/writes target the current workflow runtime's fileTree in memory
+ * - Indexed by relative file path from projectRoot
+ */
+export const fileTree = new Proxy(
+  {},
+  {
+    get(_target, prop) {
+      const runtime = getCurrentRuntime();
+      if (!runtime) return undefined;
+      return runtime._rawMemory.fileTree?.[prop];
+    },
+    set(_target, prop, value) {
+      const runtime = getCurrentRuntime();
+      if (!runtime) {
+        throw new Error('fileTree can only be mutated within a running workflow');
+      }
+      if (!runtime._rawMemory.fileTree) {
+        runtime._rawMemory.fileTree = {};
+      }
+      runtime._rawMemory.fileTree[prop] = value;
+      runtime.memory.fileTree = runtime._rawMemory.fileTree;
+      return true;
+    },
+    deleteProperty(_target, prop) {
+      const runtime = getCurrentRuntime();
+      if (!runtime) {
+        throw new Error('fileTree can only be mutated within a running workflow');
+      }
+      if (runtime._rawMemory.fileTree) {
+        delete runtime._rawMemory.fileTree[prop];
+        runtime.memory.fileTree = runtime._rawMemory.fileTree;
+      }
+      return true;
+    },
+    has(_target, prop) {
+      const runtime = getCurrentRuntime();
+      return runtime?._rawMemory.fileTree?.hasOwnProperty(prop) ?? false;
+    },
+    ownKeys() {
+      const runtime = getCurrentRuntime();
+      return Object.keys(runtime?._rawMemory.fileTree || {});
+    },
+    getOwnPropertyDescriptor(_target, prop) {
+      const runtime = getCurrentRuntime();
+      if (runtime?._rawMemory.fileTree?.hasOwnProperty(prop)) {
+        return {
+          configurable: true,
+          enumerable: true,
+          value: runtime._rawMemory.fileTree[prop]
+        };
+      }
+      return undefined;
+    }
+  }
+);
+
+/**
+ * Track a file in the fileTree.
+ * @param {string} relativePath - Path relative to projectRoot
+ * @param {object} options - Tracking options (caption, exports, extractExports, metadata, agentName)
+ */
+export function trackFile(relativePath, options = {}) {
+  const runtime = getCurrentRuntime();
+  if (!runtime) {
+    throw new Error('trackFile() must be called within a workflow context');
+  }
+  return trackFileInternal(runtime, relativePath, options);
+}
+
+/**
+ * Get all tracked files.
+ */
+export function getFileTree() {
+  const runtime = getCurrentRuntime();
+  if (!runtime) return {};
+  return getFileTreeInternal(runtime);
+}
+
+/**
+ * Remove a file from tracking.
+ */
+export function untrackFile(relativePath) {
+  const runtime = getCurrentRuntime();
+  if (!runtime) {
+    throw new Error('untrackFile() must be called within a workflow context');
+  }
+  return untrackFileInternal(runtime, relativePath);
+}
+
 export {
   setup,
   llm,
@@ -108,7 +205,10 @@ export {
   parallel,
   parallelLimit,
   getCurrentRuntime,
-  getMemory
+  getMemory,
+  // File tree utilities
+  extractExportsFromContent,
+  extractExportsFromFile
 };
 
 const api = {
@@ -137,7 +237,14 @@ const api = {
   parallelLimit,
   getCurrentRuntime,
   getMemory,
-  memory
+  memory,
+  // File tree
+  fileTree,
+  trackFile,
+  getFileTree,
+  untrackFile,
+  extractExportsFromContent,
+  extractExportsFromFile
 };
 
 export default api;

package/lib/llm.js

@@ -162,6 +162,18 @@ export function buildPrompt(context, options) {
     }
   }
 
+  // Add file tracking context if enabled
+  if (context._config?.fileTracking !== false && context._config?.projectRoot) {
+    parts.push('# File Context\n\n');
+    parts.push(`You are running from: ${context._config.workflowDir}\n`);
+    parts.push(`Project root (where to create files): ${context._config.projectRoot}\n\n`);
+    parts.push('When creating or modifying files, use paths relative to the project root.\n');
+    parts.push('To annotate files, include `_files` in your JSON response:\n');
+    parts.push('```json\n');
+    parts.push('{ "_files": [{ "path": "src/file.js", "caption": "Brief description" }] }\n');
+    parts.push('```\n---\n');
+  }
+
   return parts.join('\n');
 }