agent-state-machine 2.1.9 → 2.2.0

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/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');
 }
 

package/lib/runtime/agent.js

@@ -12,6 +12,7 @@ import { createRequire } from 'module';
 import { pathToFileURL } from 'url';
 import { getCurrentRuntime } from './runtime.js';
 import { formatInteractionPrompt } from './interaction.js';
+import { withChangeTracking } from './track-changes.js';
 
 const require = createRequire(import.meta.url);
 
@@ -164,25 +165,37 @@ async function executeJSAgent(runtime, agentPath, name, params, options = {}) {
     _config: {
       models: runtime.workflowConfig.models,
       apiKeys: runtime.workflowConfig.apiKeys,
-      workflowDir: runtime.workflowDir
+      workflowDir: runtime.workflowDir,
+      projectRoot: runtime.workflowConfig.projectRoot
     }
   };
 
-  let result = await handler(context);
-  let interactionDepth = 0;
-
-  // Handle interaction response from JS agent (support multiple rounds)
-  while (result && result._interaction) {
-    const interactionResponse = await handleInteraction(runtime, result._interaction, name);
-    const resumedContext = { ...context, userResponse: interactionResponse };
-    await logAgentStart(runtime, name);
-    result = await handler(resumedContext);
-    interactionDepth += 1;
-    if (interactionDepth > 5) {
-      throw new Error(`Agent ${name} exceeded maximum interaction depth`);
+  // Execute handler with optional file change tracking
+  const executeHandler = async () => {
+    let result = await handler(context);
+    let interactionDepth = 0;
+
+    // Handle interaction response from JS agent (support multiple rounds)
+    while (result && result._interaction) {
+      const interactionResponse = await handleInteraction(runtime, result._interaction, name);
+      const resumedContext = { ...context, userResponse: interactionResponse };
+      await logAgentStart(runtime, name);
+      result = await handler(resumedContext);
+      interactionDepth += 1;
+      if (interactionDepth > 5) {
+        throw new Error(`Agent ${name} exceeded maximum interaction depth`);
+      }
     }
-  }
 
+    return result;
+  };
+
+  let result;
+  if (runtime.workflowConfig.fileTracking !== false) {
+    result = await withChangeTracking(runtime, name, executeHandler);
+  } else {
+    result = await executeHandler();
+  }
 
   // Clean internal properties from result
   if (result && typeof result === 'object') {
@@ -191,6 +204,7 @@ async function executeJSAgent(runtime, agentPath, name, params, options = {}) {
     delete cleanResult._config;
     delete cleanResult._loop;
     delete cleanResult._interaction;
+    delete cleanResult._files;
 
     // If agent returned a context-like object, only return non-internal keys
     const meaningfulKeys = Object.keys(cleanResult).filter((k) => !k.startsWith('_'));
@@ -235,127 +249,141 @@ async function executeMDAgent(runtime, agentPath, name, params, options = {}) {
     ? runtime.loadSteeringFiles(steeringNames)
     : runtime.steering;
 
-  let response = null;
-  let output = null;
-  let interactionDepth = 0;
-  let currentParams = params;
-
-  while (true) {
-    // Build context - only spread params, NOT memory (explicit context passing)
-    const context = {
-      ...currentParams,
-      _steering: steeringContext,
-      _config: {
-        models: runtime.workflowConfig.models,
-        apiKeys: runtime.workflowConfig.apiKeys,
-        workflowDir: runtime.workflowDir
-      }
-    };
-
-    // Interpolate variables in prompt
-    const interpolatedPrompt = interpolatePrompt(prompt, context);
+  // Build base config (used for all iterations)
+  const baseConfig = {
+    models: runtime.workflowConfig.models,
+    apiKeys: runtime.workflowConfig.apiKeys,
+    workflowDir: runtime.workflowDir,
+    projectRoot: runtime.workflowConfig.projectRoot
+  };
 
-    const model = config.model || 'fast';
+  // Execute the MD agent core logic
+  const executeMDAgentCore = async () => {
+    let response = null;
+    let output = null;
+    let interactionDepth = 0;
+    let currentParams = params;
+
+    while (true) {
+      // Build context - only spread params, NOT memory (explicit context passing)
+      const context = {
+        ...currentParams,
+        _steering: steeringContext,
+        _config: baseConfig
+      };
+
+      // Interpolate variables in prompt
+      const interpolatedPrompt = interpolatePrompt(prompt, context);
+
+      const model = config.model || 'fast';
+
+      const fullPrompt = buildPrompt(context, {
+        model,
+        prompt: interpolatedPrompt,
+        includeContext: config.includeContext !== 'false',
+        responseType: config.response
+      });
 
-    const fullPrompt = buildPrompt(context, {
-      model,
-      prompt: interpolatedPrompt,
-      includeContext: config.includeContext !== 'false',
-      responseType: config.response
-    });
+      await logAgentStart(runtime, name, fullPrompt);
 
-    await logAgentStart(runtime, name, fullPrompt);
+      console.log(`    Using model: ${model}`);
 
-    console.log(`    Using model: ${model}`);
+      response = await llm(context, {
+        model: model,
+        prompt: interpolatedPrompt,
+        includeContext: config.includeContext !== 'false',
+        responseType: config.response
+      });
 
-    response = await llm(context, {
-      model: model,
-      prompt: interpolatedPrompt,
-      includeContext: config.includeContext !== 'false',
-      responseType: config.response
-    });
+      // Parse output based on format
+      output = response.text;
+      if (config.format === 'json') {
+        try {
+          output = parseJSON(response.text);
+        } catch {
+          console.warn(`    Warning: Failed to parse JSON output`);
+        }
+      }
 
-    // Parse output based on format
-    output = response.text;
-    if (config.format === 'json') {
-      try {
-        output = parseJSON(response.text);
-      } catch {
-        console.warn(`    Warning: Failed to parse JSON output`);
+      if (output && typeof output === 'object' && output._interaction) {
+        const interactionResponse = await handleInteraction(runtime, output._interaction, name);
+        currentParams = { ...params, userResponse: interactionResponse };
+        interactionDepth += 1;
+        if (interactionDepth > 5) {
+          throw new Error(`Agent ${name} exceeded maximum interaction depth`);
+        }
+        continue;
       }
+
+      break;
     }
 
-    if (output && typeof output === 'object' && output._interaction) {
-      const interactionResponse = await handleInteraction(runtime, output._interaction, name);
-      currentParams = { ...params, userResponse: interactionResponse };
-      interactionDepth += 1;
-      if (interactionDepth > 5) {
-        throw new Error(`Agent ${name} exceeded maximum interaction depth`);
+    // Check for interaction request
+    const parsedInteraction = parseInteractionRequest(response.text);
+    const structuredInteraction =
+      config.autoInteract !== 'false' && parsedInteraction.isInteraction;
+
+    // Check if agent returned an 'interact' object in its JSON response
+    const hasInteractKey = output && typeof output === 'object' && output.interact;
+
+    // Explicit interaction mode (format: interaction OR interaction: true)
+    // But only trigger if agent actually wants to interact (has interact key or parsed interaction)
+    const explicitInteraction =
+      config.format === 'interaction' ||
+      ((config.interaction === 'true' || (typeof config.interaction === 'string' && config.interaction.length > 0)) &&
+        (hasInteractKey || structuredInteraction));
+
+    if (explicitInteraction || structuredInteraction) {
+      // Use interact object if present, otherwise fall back to parsed/raw
+      const interactionData = hasInteractKey ? output.interact : (structuredInteraction ? parsedInteraction : null);
+
+      const slugRaw =
+        interactionData?.slug ||
+        (typeof config.interaction === 'string' && config.interaction !== 'true'
+          ? config.interaction
+          : null) ||
+        config.interactionSlug ||
+        config.interactionKey ||
+        name;
+
+      const slug = sanitizeSlug(slugRaw);
+      const targetKey = config.interactionKey || outputKey || slug;
+
+      // Build interaction object with full metadata
+      const interactionObj = hasInteractKey ? {
+        ...output.interact,
+        slug,
+        targetKey
+      } : {
+        slug,
+        targetKey,
+        content: structuredInteraction ? parsedInteraction.question : response.text
+      };
+
+      const userResponse = await handleInteraction(runtime, interactionObj, name);
+
+      // Return the user's response as the agent result
+      if (outputKey) {
+        return { [outputKey]: userResponse, _debug_prompt: response.fullPrompt };
       }
-      continue;
-    }
 
-    break;
-  }
+      return userResponse;
+    }
 
-  // Check for interaction request
-  const parsedInteraction = parseInteractionRequest(response.text);
-  const structuredInteraction =
-    config.autoInteract !== 'false' && parsedInteraction.isInteraction;
-
-  // Check if agent returned an 'interact' object in its JSON response
-  const hasInteractKey = output && typeof output === 'object' && output.interact;
-
-  // Explicit interaction mode (format: interaction OR interaction: true)
-  // But only trigger if agent actually wants to interact (has interact key or parsed interaction)
-  const explicitInteraction =
-    config.format === 'interaction' ||
-    ((config.interaction === 'true' || (typeof config.interaction === 'string' && config.interaction.length > 0)) &&
-      (hasInteractKey || structuredInteraction));
-
-  if (explicitInteraction || structuredInteraction) {
-    // Use interact object if present, otherwise fall back to parsed/raw
-    const interactionData = hasInteractKey ? output.interact : (structuredInteraction ? parsedInteraction : null);
-    
-    const slugRaw =
-      interactionData?.slug ||
-      (typeof config.interaction === 'string' && config.interaction !== 'true'
-        ? config.interaction
-        : null) ||
-      config.interactionSlug ||
-      config.interactionKey ||
-      name;
-
-    const slug = sanitizeSlug(slugRaw);
-    const targetKey = config.interactionKey || outputKey || slug;
-    
-    // Build interaction object with full metadata
-    const interactionObj = hasInteractKey ? {
-      ...output.interact,
-      slug,
-      targetKey
-    } : {
-      slug,
-      targetKey,
-      content: structuredInteraction ? parsedInteraction.question : response.text
-    };
-
-    const userResponse = await handleInteraction(runtime, interactionObj, name);
-
-    // Return the user's response as the agent result
+    // Return result object
     if (outputKey) {
-      return { [outputKey]: userResponse, _debug_prompt: response.fullPrompt };
+      return { [outputKey]: output, _debug_prompt: response.fullPrompt };
     }
 
-    return userResponse;
-  }
+    return output;
+  };
 
-  // Return result object
-  if (outputKey) {
-    return { [outputKey]: output, _debug_prompt: response.fullPrompt };
+  // Execute with optional file change tracking
+  if (runtime.workflowConfig.fileTracking !== false) {
+    return withChangeTracking(runtime, name, executeMDAgentCore);
+  } else {
+    return executeMDAgentCore();
   }
-
-  return output;
 }
 
 /**

package/lib/runtime/runtime.js

@@ -12,6 +12,7 @@ import readline from 'readline';
 import { pathToFileURL } from 'url';
 import { createMemoryProxy } from './memory.js';
 import { RemoteClient } from '../remote/client.js';
+import { DEFAULT_IGNORE } from '../file-tree.js';
 
 // Global runtime reference for agent() and memory access
 // stored on globalThis to ensure singleton access across different module instances (CLI vs local)
@@ -74,7 +75,12 @@ export class WorkflowRuntime {
     this.workflowConfig = {
       models: {},
       apiKeys: {},
-      description: ''
+      description: '',
+      // File tracking defaults
+      projectRoot: path.resolve(workflowDir, '../..'),
+      fileTracking: true,
+      fileTrackingIgnore: DEFAULT_IGNORE,
+      fileTrackingKeepDeleted: false
     };
 
     // Load steering
@@ -317,7 +323,12 @@ export class WorkflowRuntime {
       this.workflowConfig = {
         models: cfg.models || {},
         apiKeys: cfg.apiKeys || {},
-        description: cfg.description || ''
+        description: cfg.description || '',
+        // File tracking configuration
+        projectRoot: cfg.projectRoot || path.resolve(this.workflowDir, '../..'),
+        fileTracking: cfg.fileTracking ?? true,
+        fileTrackingIgnore: cfg.fileTrackingIgnore || DEFAULT_IGNORE,
+        fileTrackingKeepDeleted: cfg.fileTrackingKeepDeleted ?? false
       };
 
       // Import workflow module

package/lib/runtime/track-changes.js

@@ -0,0 +1,252 @@
+/**
+ * File: /lib/runtime/track-changes.js
+ *
+ * Wraps agent execution with file change tracking.
+ * Captures baseline before agent runs, detects changes after,
+ * and updates memory.fileTree with the results.
+ */
+
+import path from 'path';
+import {
+  captureBaseline,
+  detectChanges,
+  normalizePath,
+  extractExportsFromFile,
+  DEFAULT_IGNORE
+} from '../file-tree.js';
+
+/**
+ * Wrap an async function with file change tracking.
+ * Captures baseline before execution, detects changes after,
+ * and updates the runtime's fileTree.
+ *
+ * @param {Object} runtime - The workflow runtime instance
+ * @param {string} agentName - Name of the agent (for attribution)
+ * @param {Function} fn - Async function to execute
+ * @returns {Promise<any>} - Result of the function
+ */
+export async function withChangeTracking(runtime, agentName, fn) {
+  const projectRoot = runtime.workflowConfig.projectRoot;
+  const ignorePatterns = runtime.workflowConfig.fileTrackingIgnore || DEFAULT_IGNORE;
+
+  // Capture baseline before agent runs
+  const baseline = await captureBaseline(projectRoot, ignorePatterns);
+
+  // Run the agent
+  const result = await fn();
+
+  // Detect changes made during agent execution
+  const changes = await detectChanges(projectRoot, baseline, ignorePatterns);
+
+  // Update fileTree with detected changes
+  applyChangesToFileTree(runtime, changes, agentName);
+
+  // Merge _files annotations if present (preserves existing data unless explicitly overwritten)
+  if (result && typeof result === 'object' && Array.isArray(result._files)) {
+    mergeAnnotations(runtime, result._files);
+  }
+
+  return result;
+}
+
+/**
+ * Apply detected file changes to the runtime's fileTree.
+ */
+function applyChangesToFileTree(runtime, changes, agentName) {
+  const now = new Date().toISOString();
+  const projectRoot = runtime.workflowConfig.projectRoot;
+
+  // Initialize fileTree if needed
+  if (!runtime._rawMemory.fileTree) {
+    runtime._rawMemory.fileTree = {};
+  }
+
+  // Handle created files
+  for (const filePath of changes.created) {
+    try {
+      const normalized = normalizePath(filePath, projectRoot);
+      runtime._rawMemory.fileTree[normalized] = {
+        path: normalized,
+        status: 'created',
+        createdBy: agentName,
+        lastModifiedBy: agentName,
+        createdAt: now,
+        updatedAt: now
+      };
+    } catch (e) {
+      // Skip files with invalid paths
+      console.warn(`[file-tree] Skipping invalid path: ${filePath} - ${e.message}`);
+    }
+  }
+
+  // Handle modified files
+  for (const filePath of changes.modified) {
+    try {
+      const normalized = normalizePath(filePath, projectRoot);
+      const existing = runtime._rawMemory.fileTree[normalized] || {};
+      runtime._rawMemory.fileTree[normalized] = {
+        ...existing,
+        path: normalized,
+        status: 'modified',
+        lastModifiedBy: agentName,
+        updatedAt: now,
+        createdAt: existing.createdAt || now,
+        createdBy: existing.createdBy || agentName
+      };
+    } catch (e) {
+      console.warn(`[file-tree] Skipping invalid path: ${filePath} - ${e.message}`);
+    }
+  }
+
+  // Handle renamed files (MVP: from/to pairs)
+  for (const { from, to } of changes.renamed) {
+    try {
+      const normalizedFrom = normalizePath(from, projectRoot);
+      const normalizedTo = normalizePath(to, projectRoot);
+      const existing = runtime._rawMemory.fileTree[normalizedFrom] || {};
+      delete runtime._rawMemory.fileTree[normalizedFrom];
+      runtime._rawMemory.fileTree[normalizedTo] = {
+        ...existing,
+        path: normalizedTo,
+        status: 'renamed',
+        renamedFrom: normalizedFrom,
+        lastModifiedBy: agentName,
+        updatedAt: now
+      };
+    } catch (e) {
+      console.warn(`[file-tree] Skipping invalid rename: ${from} -> ${to} - ${e.message}`);
+    }
+  }
+
+  // Handle deleted files
+  for (const filePath of changes.deleted) {
+    try {
+      const normalized = normalizePath(filePath, projectRoot);
+      if (runtime.workflowConfig.fileTrackingKeepDeleted) {
+        runtime._rawMemory.fileTree[normalized] = {
+          ...runtime._rawMemory.fileTree[normalized],
+          status: 'deleted',
+          deletedBy: agentName,
+          deletedAt: now
+        };
+      } else {
+        delete runtime._rawMemory.fileTree[normalized];
+      }
+    } catch (e) {
+      console.warn(`[file-tree] Skipping invalid path: ${filePath} - ${e.message}`);
+    }
+  }
+
+  // Trigger persistence
+  runtime.memory.fileTree = runtime._rawMemory.fileTree;
+}
+
+/**
+ * Merge _files annotations from agent result into fileTree.
+ * Only annotates files that were actually detected by change tracking.
+ * Preserves existing values unless explicitly overwritten.
+ */
+function mergeAnnotations(runtime, files) {
+  const projectRoot = runtime.workflowConfig.projectRoot;
+
+  for (const file of files) {
+    if (!file.path) continue;
+
+    try {
+      const normalizedPath = normalizePath(file.path, projectRoot);
+      const existing = runtime._rawMemory.fileTree?.[normalizedPath];
+
+      if (!existing) continue; // Only annotate files that were actually detected
+
+      // Preserve existing values unless _files explicitly provides new ones
+      if (file.caption !== undefined) existing.caption = file.caption;
+      if (file.exports !== undefined) existing.exports = file.exports;
+      if (file.metadata !== undefined) {
+        existing.metadata = { ...existing.metadata, ...file.metadata };
+      }
+
+      // Trigger best-effort export extraction if requested
+      if (file.extractExports) {
+        const absolutePath = path.resolve(projectRoot, normalizedPath);
+        const exports = extractExportsFromFile(absolutePath);
+        if (exports) existing.exports = exports;
+      }
+    } catch (e) {
+      console.warn(`[file-tree] Skipping invalid annotation path: ${file.path} - ${e.message}`);
+    }
+  }
+
+  // Trigger persistence
+  runtime.memory.fileTree = runtime._rawMemory.fileTree;
+}
+
+/**
+ * Manually track a file in the fileTree.
+ * Used for files created outside of agent execution.
+ */
+export function trackFile(runtime, relativePath, options = {}) {
+  const projectRoot = runtime.workflowConfig.projectRoot;
+  const normalized = normalizePath(relativePath, projectRoot);
+  const now = new Date().toISOString();
+  const agentName = options.agentName || 'manual';
+
+  // Initialize fileTree if needed
+  if (!runtime._rawMemory.fileTree) {
+    runtime._rawMemory.fileTree = {};
+  }
+
+  const existing = runtime._rawMemory.fileTree[normalized];
+
+  const entry = {
+    path: normalized,
+    status: existing?.status || 'created',
+    createdBy: existing?.createdBy || agentName,
+    lastModifiedBy: agentName,
+    createdAt: existing?.createdAt || now,
+    updatedAt: now
+  };
+
+  // Apply options
+  if (options.caption !== undefined) entry.caption = options.caption;
+  if (options.exports !== undefined) entry.exports = options.exports;
+  if (options.metadata !== undefined) {
+    entry.metadata = { ...existing?.metadata, ...options.metadata };
+  }
+
+  // Extract exports if requested
+  if (options.extractExports) {
+    const absolutePath = path.resolve(projectRoot, normalized);
+    const exports = extractExportsFromFile(absolutePath);
+    if (exports) entry.exports = exports;
+  }
+
+  runtime._rawMemory.fileTree[normalized] = entry;
+
+  // Trigger persistence
+  runtime.memory.fileTree = runtime._rawMemory.fileTree;
+
+  return entry;
+}
+
+/**
+ * Get the current fileTree.
+ */
+export function getFileTree(runtime) {
+  return runtime._rawMemory.fileTree || {};
+}
+
+/**
+ * Remove a file from tracking.
+ */
+export function untrackFile(runtime, relativePath) {
+  const projectRoot = runtime.workflowConfig.projectRoot;
+  const normalized = normalizePath(relativePath, projectRoot);
+
+  if (runtime._rawMemory.fileTree?.[normalized]) {
+    delete runtime._rawMemory.fileTree[normalized];
+    runtime.memory.fileTree = runtime._rawMemory.fileTree;
+    return true;
+  }
+
+  return false;
+}

package/package.json

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

package/templates/project-builder/config.js

@@ -9,5 +9,16 @@ export const config = {
     gemini: process.env.GEMINI_API_KEY,
     anthropic: process.env.ANTHROPIC_API_KEY,
     openai: process.env.OPENAI_API_KEY,
-  }
+  },
+
+  // File tracking (all optional - shown with defaults)
+  // projectRoot: process.env.PROJECT_ROOT,  // Defaults to ../.. from workflow
+  // fileTracking: true,                     // Enable/disable file tracking
+  // fileTrackingIgnore: [                   // Glob patterns to ignore
+  //   'node_modules/**',
+  //   '.git/**',
+  //   'dist/**',
+  //   'workflows/**'
+  // ],
+  // fileTrackingKeepDeleted: false          // Keep deleted files in tree
 };

package/templates/starter/config.js

@@ -8,5 +8,16 @@ export const config = {
     gemini: process.env.GEMINI_API_KEY,
     anthropic: process.env.ANTHROPIC_API_KEY,
     openai: process.env.OPENAI_API_KEY,
-  }
+  },
+
+  // File tracking (all optional - shown with defaults)
+  // projectRoot: process.env.PROJECT_ROOT,  // Defaults to ../.. from workflow
+  // fileTracking: true,                     // Enable/disable file tracking
+  // fileTrackingIgnore: [                   // Glob patterns to ignore
+  //   'node_modules/**',
+  //   '.git/**',
+  //   'dist/**',
+  //   'workflows/**'
+  // ],
+  // fileTrackingKeepDeleted: false          // Keep deleted files in tree
 };