agent-state-machine 1.0.0

package/lib/runtime/agent.js

@@ -0,0 +1,359 @@
+/**
+ * File: /lib/runtime/agent.js
+ */
+
+/**
+ * Agent execution module for native JS workflows
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { createRequire } from 'module';
+import { pathToFileURL } from 'url';
+import { getCurrentRuntime } from './runtime.js';
+
+const require = createRequire(import.meta.url);
+
+/**
+ * Run an agent with context
+ * @param {string} name - Agent name (file basename)
+ * @param {object} params - Parameters passed to agent
+ */
+export async function agent(name, params = {}) {
+  const runtime = getCurrentRuntime();
+  if (!runtime) {
+    throw new Error('agent() must be called within a workflow context');
+  }
+
+  console.log(`  [Agent: ${name}] Starting...`);
+  runtime.prependHistory({
+    event: 'AGENT_STARTED',
+    agent: name
+  });
+
+  try {
+    const result = await executeAgent(runtime, name, params);
+
+    console.log(`  [Agent: ${name}] Completed`);
+    runtime.prependHistory({
+      event: 'AGENT_COMPLETED',
+      agent: name,
+      output: result
+    });
+
+    return result;
+  } catch (error) {
+    runtime.prependHistory({
+      event: 'AGENT_FAILED',
+      agent: name,
+      error: error.message
+    });
+    throw error;
+  }
+}
+
+/**
+ * Execute an agent (load and run)
+ */
+export async function executeAgent(runtime, name, params) {
+  const agentsDir = runtime.agentsDir;
+
+  // Try JS agents (.js/.mjs/.cjs)
+  const jsCandidates = [
+    path.join(agentsDir, `${name}.js`),
+    path.join(agentsDir, `${name}.mjs`),
+    path.join(agentsDir, `${name}.cjs`)
+  ];
+
+  for (const p of jsCandidates) {
+    if (fs.existsSync(p)) {
+      return executeJSAgent(runtime, p, name, params);
+    }
+  }
+
+  // Try Markdown agent
+  const mdPath = path.join(agentsDir, `${name}.md`);
+  if (fs.existsSync(mdPath)) {
+    return executeMDAgent(runtime, mdPath, name, params);
+  }
+
+  throw new Error(
+    `Agent not found: ${name} (looked for ${jsCandidates
+      .map((p) => path.basename(p))
+      .join(', ')} or ${name}.md in ${agentsDir})`
+  );
+}
+
+/**
+ * Execute a JavaScript agent
+ * - ESM (.js/.mjs): loaded via dynamic import with cache-bust for hot reload
+ * - CJS (.cjs): loaded via require() with cache clear
+ */
+async function executeJSAgent(runtime, agentPath, name, params) {
+  const ext = path.extname(agentPath).toLowerCase();
+
+  let agentModule;
+  if (ext === '.cjs') {
+    // Clear require cache for hot reloading
+    delete require.cache[require.resolve(agentPath)];
+    agentModule = require(agentPath);
+  } else {
+    // Cache-busted import for hot reload behavior
+    const url = pathToFileURL(agentPath).href;
+    agentModule = await import(`${url}?t=${Date.now()}`);
+  }
+
+  const handler =
+    agentModule?.handler ||
+    agentModule?.default ||
+    agentModule;
+
+  if (typeof handler !== 'function') {
+    throw new Error(`Agent ${name} does not export a function`);
+  }
+
+  // Build context
+  const context = {
+    ...runtime._rawMemory,
+    ...params,
+    _steering: runtime.steering,
+    _config: {
+      models: runtime.workflowConfig.models,
+      apiKeys: runtime.workflowConfig.apiKeys,
+      workflowDir: runtime.workflowDir
+    }
+  };
+
+  const result = await handler(context);
+
+  // Handle interaction response from JS agent
+  if (result && result._interaction) {
+    const interactionResponse = await handleInteraction(runtime, result._interaction);
+    
+    // Use the interaction response as the primary output if it exists
+    // This allows the workflow to receive the user's input directly
+    if (typeof result === 'object') {
+       // Merge response into result or replace? 
+       // For consistency with MDAgent, we might want to return { result: response }
+       // but JS agents are more flexible. 
+       // Let's assume the agent wants the response mixed in or as the return.
+       // A safe bet is to return the response if the agent explicitly asked for interaction.
+       return { ...result, result: interactionResponse };
+    }
+    return interactionResponse;
+  }
+
+  // Clean internal properties from result
+  if (result && typeof result === 'object') {
+    const cleanResult = { ...result };
+    delete cleanResult._steering;
+    delete cleanResult._config;
+    delete cleanResult._loop;
+    delete cleanResult._interaction;
+
+    // If agent returned a context-like object, only return non-internal keys
+    const meaningfulKeys = Object.keys(cleanResult).filter((k) => !k.startsWith('_'));
+    if (meaningfulKeys.length > 0) {
+      const output = {};
+      for (const key of meaningfulKeys) output[key] = cleanResult[key];
+      return output;
+    }
+
+    return cleanResult;
+  }
+
+  return result;
+}
+
+/**
+ * Execute a Markdown agent (prompt-based)
+ */
+async function executeMDAgent(runtime, agentPath, name, params) {
+  const { llm, parseJSON, parseInteractionRequest } = await import('../llm.js');
+
+  const content = fs.readFileSync(agentPath, 'utf-8');
+  const { config, prompt } = parseMarkdownAgent(content);
+
+  const outputKey = config.output || 'result';
+  const targetKey = config.interactionKey || outputKey;
+
+  // Build context
+  const context = {
+    ...runtime._rawMemory,
+    ...params,
+    _steering: runtime.steering,
+    _config: {
+      models: runtime.workflowConfig.models,
+      apiKeys: runtime.workflowConfig.apiKeys,
+      workflowDir: runtime.workflowDir
+    }
+  };
+
+  // Interpolate variables in prompt
+  const interpolatedPrompt = interpolatePrompt(prompt, context);
+
+  const model = config.model || 'fast';
+
+  console.log(`    Using model: ${model}`);
+
+  const response = await llm(context, {
+    model: model,
+    prompt: interpolatedPrompt,
+    includeContext: config.includeContext !== 'false'
+  });
+
+  // Parse output based on format
+  let output = response.text;
+  if (config.format === 'json') {
+    try {
+      output = parseJSON(response.text);
+    } catch {
+      console.warn(`    Warning: Failed to parse JSON output`);
+    }
+  }
+
+  // Check for interaction request
+  const explicitInteraction =
+    config.format === 'interaction' ||
+    config.interaction === 'true' ||
+    (typeof config.interaction === 'string' && config.interaction.length > 0);
+
+  const parsedInteraction = parseInteractionRequest(response.text);
+  const structuredInteraction =
+    config.autoInteract !== 'false' && parsedInteraction.isInteraction;
+
+  if (explicitInteraction || structuredInteraction) {
+    const slugRaw =
+      (typeof config.interaction === 'string' && config.interaction !== 'true'
+        ? config.interaction
+        : null) ||
+      config.interactionSlug ||
+      config.interactionKey ||
+      outputKey ||
+      name;
+
+    const slug = sanitizeSlug(slugRaw);
+    const targetKey = config.interactionKey || outputKey || slug;
+    const interactionContent = structuredInteraction ? parsedInteraction.question : response.text;
+
+    const userResponse = await handleInteraction(runtime, {
+      slug,
+      targetKey,
+      content: interactionContent
+    });
+
+    // Return the user's response as the agent result
+    return { [outputKey]: userResponse };
+  }
+
+  // Return result object
+  return { [outputKey]: output };
+}
+
+/**
+ * Parse markdown agent with simple frontmatter
+ */
+function parseMarkdownAgent(content) {
+  // Frontmatter format:
+  // ---
+  // key: value
+  // ---
+  // prompt...
+  if (content.startsWith('---')) {
+    const parts = content.split('---');
+    if (parts.length >= 3) {
+      const frontmatter = parts[1].trim();
+      const prompt = parts.slice(2).join('---').trim();
+
+      const config = {};
+      frontmatter.split('\n').forEach((line) => {
+        const [key, ...rest] = line.split(':');
+        if (key && rest.length) {
+          const value = rest.join(':').trim();
+          config[key.trim()] = value.replace(/^["']|["']$/g, '');
+        }
+      });
+
+      return { config, prompt };
+    }
+  }
+
+  return { config: {}, prompt: content.trim() };
+}
+
+/**
+ * Interpolate {{variables}} in prompt template
+ */
+function interpolatePrompt(template, context) {
+  return template.replace(/\{\{\s*([^}]+?)\s*\}\}/g, (match, pathStr) => {
+    const value = getByPath(context, pathStr);
+    return value !== undefined ? String(value) : match;
+  });
+}
+
+/**
+ * Get nested value by dot-notation path
+ */
+function getByPath(obj, pathStr) {
+  const trimmed = String(pathStr || '').trim();
+  if (!trimmed) return undefined;
+
+  const normalized = trimmed.startsWith('context.')
+    ? trimmed.slice('context.'.length)
+    : trimmed;
+
+  const parts = normalized.split('.').filter(Boolean);
+  let current = obj;
+
+  for (const part of parts) {
+    if (current == null) return undefined;
+    current = current[String(part)];
+  }
+
+  return current;
+}
+
+function sanitizeSlug(input) {
+  const raw = String(input || '').trim();
+  const cleaned = raw
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '');
+
+  return cleaned || 'interaction';
+}
+
+/**
+ * Handle interaction (create file, wait for user, return response)
+ */
+async function handleInteraction(runtime, interaction) {
+  const slug = sanitizeSlug(interaction.slug);
+  const targetKey = String(interaction.targetKey || slug);
+  const content = String(interaction.content || '').trim();
+
+  const filePath = path.join(runtime.interactionsDir, `${slug}.md`);
+
+  // Create interaction file
+  const fileContent = `# ${slug}
+
+${content}
+
+---
+Enter your response below:
+
+`;
+
+  fs.writeFileSync(filePath, fileContent);
+
+  runtime.prependHistory({
+    event: 'INTERACTION_REQUESTED',
+    slug,
+    targetKey
+  });
+
+  // Block and wait for user input (instead of throwing)
+  const response = await runtime.waitForInteraction(filePath, slug, targetKey);
+
+  return response;
+}

package/lib/runtime/index.js

@@ -0,0 +1,35 @@
+/**
+ * File: /lib/runtime/index.js
+ */
+
+/**
+ * Runtime module exports for native JS workflows
+ */
+
+export {
+  WorkflowRuntime,
+  getCurrentRuntime,
+  setCurrentRuntime,
+  clearCurrentRuntime
+} from './runtime.js';
+
+export { agent, executeAgent } from './agent.js';
+export { initialPrompt } from './prompt.js';
+export { parallel, parallelLimit } from './parallel.js';
+export { createMemoryProxy } from './memory.js';
+
+import { getCurrentRuntime } from './runtime.js';
+
+/**
+ * Get the current workflow's memory object
+ * Returns a proxy that auto-persists on mutation
+ */
+export function getMemory() {
+  const runtime = getCurrentRuntime();
+  if (!runtime) {
+    // Return empty object when not in workflow context
+    // This allows imports to work without throwing
+    return {};
+  }
+  return runtime.memory;
+}

package/lib/runtime/memory.js

@@ -0,0 +1,88 @@
+/**
+ * File: /lib/runtime/memory.js
+ */
+
+/**
+ * Memory Proxy Module
+ * Creates a proxy object that auto-persists to disk on mutation
+ */
+
+let persistTimeout = null;
+const DEBOUNCE_MS = 10;
+
+/**
+ * Schedule a debounced persistence call
+ */
+function schedulePersist(fn) {
+  if (persistTimeout) clearTimeout(persistTimeout);
+  persistTimeout = setTimeout(() => {
+    fn();
+    persistTimeout = null;
+  }, DEBOUNCE_MS);
+}
+
+/**
+ * Force immediate persistence (clears any pending debounce)
+ */
+export function flushPersist(fn) {
+  if (persistTimeout) {
+    clearTimeout(persistTimeout);
+    persistTimeout = null;
+  }
+  fn();
+}
+
+/**
+ * Create a proxy that auto-saves on mutation
+ * @param {object} data - The raw data object to proxy
+ * @param {function} persistFn - Function to call when data changes
+ * @param {object} root - Root object for nested proxy tracking (internal)
+ * @returns {Proxy} Proxied memory object
+ */
+export function createMemoryProxy(data, persistFn, root = null) {
+  const handler = {
+    get(target, prop) {
+      // Return primitives and functions as-is
+      if (prop === '_raw') return target;
+      if (prop === '_flush') return () => flushPersist(persistFn);
+
+      const value = target[prop];
+
+      // Don't proxy internal properties, functions, or primitives
+      if (typeof prop === 'symbol') return value;
+      if (prop.startsWith('_')) return value;
+      if (typeof value === 'function') return value;
+      if (value === null || typeof value !== 'object') return value;
+
+      // Wrap nested objects in proxies for deep observation
+      return createMemoryProxy(value, persistFn, root || data);
+    },
+
+    set(target, prop, value) {
+      // Skip internal properties (don't trigger persist)
+      if (typeof prop === 'symbol' || prop.startsWith('_')) {
+        target[prop] = value;
+        return true;
+      }
+
+      target[prop] = value;
+      schedulePersist(persistFn);
+      return true;
+    },
+
+    deleteProperty(target, prop) {
+      if (typeof prop === 'symbol' || prop.startsWith('_')) {
+        delete target[prop];
+        return true;
+      }
+
+      delete target[prop];
+      schedulePersist(persistFn);
+      return true;
+    }
+  };
+
+  return new Proxy(data, handler);
+}
+
+export { schedulePersist };

package/lib/runtime/parallel.js

@@ -0,0 +1,66 @@
+/**
+ * File: /lib/runtime/parallel.js
+ */
+
+/**
+ * Parallel execution module for running multiple agents concurrently
+ */
+
+/**
+ * Execute multiple agent calls in parallel
+ * @param {Promise[]} agentCalls - Array of agent() call promises
+ * @returns {Promise<any[]>} Array of results in same order as input
+ *
+ * @example
+ * const [review1, review2] = await parallel([
+ *   agent('code-review', { file: 'src/a.js' }),
+ *   agent('code-review', { file: 'src/b.js' })
+ * ]);
+ */
+export async function parallel(agentCalls) {
+  if (!Array.isArray(agentCalls)) {
+    throw new Error('parallel() expects an array of promises');
+  }
+
+  if (agentCalls.length === 0) {
+    return [];
+  }
+
+  // Promise.all maintains order
+  return Promise.all(agentCalls);
+}
+
+/**
+ * Execute agent calls in parallel with a concurrency limit
+ * @param {Promise[]} agentCalls - Array of agent() call promises
+ * @param {number} limit - Maximum concurrent executions
+ * @returns {Promise<any[]>} Array of results in same order as input
+ */
+export async function parallelLimit(agentCalls, limit = 3) {
+  if (!Array.isArray(agentCalls)) {
+    throw new Error('parallelLimit() expects an array of promises');
+  }
+
+  if (agentCalls.length === 0) {
+    return [];
+  }
+
+  const results = new Array(agentCalls.length);
+  let currentIndex = 0;
+
+  async function worker() {
+    while (currentIndex < agentCalls.length) {
+      const index = currentIndex++;
+      results[index] = await agentCalls[index];
+    }
+  }
+
+  // Start up to 'limit' workers
+  const workers = [];
+  for (let i = 0; i < Math.min(limit, agentCalls.length); i++) {
+    workers.push(worker());
+  }
+
+  await Promise.all(workers);
+  return results;
+}

package/lib/runtime/prompt.js

@@ -0,0 +1,118 @@
+/**
+ * File: /lib/runtime/prompt.js
+ */
+
+/**
+ * Initial prompt module for user input collection
+ */
+
+import fs from 'fs';
+import path from 'path';
+import readline from 'readline';
+import { getCurrentRuntime } from './runtime.js';
+
+/**
+ * Request user input with memory-based resume support
+ * @param {string} question - Question to ask the user
+ * @param {object} options - Options
+ * @param {string} options.slug - Unique identifier for this prompt (for file)
+ * @returns {Promise<string>} User's response
+ */
+export async function initialPrompt(question, options = {}) {
+  const runtime = getCurrentRuntime();
+  if (!runtime) {
+    throw new Error('initialPrompt() must be called within a workflow context');
+  }
+
+  const slug = options.slug || generateSlug(question);
+  const memoryKey = `_interaction_${slug}`;
+
+  runtime.prependHistory({
+    event: 'PROMPT_REQUESTED',
+    slug,
+    question
+  });
+
+  // Check if we're in TTY mode (interactive terminal)
+  if (process.stdin.isTTY && process.stdout.isTTY) {
+    // Interactive mode - prompt directly
+    console.log('');
+    const answer = await askQuestion(question);
+    console.log('');
+
+    // Save the response to memory
+    runtime._rawMemory[memoryKey] = answer;
+    runtime.persist();
+
+    runtime.prependHistory({
+      event: 'PROMPT_ANSWERED',
+      slug,
+      answer: answer.substring(0, 100) + (answer.length > 100 ? '...' : '')
+    });
+
+    return answer;
+  }
+
+  // Non-TTY mode - create interaction file and wait inline
+  const interactionFile = path.join(runtime.interactionsDir, `${slug}.md`);
+
+  const fileContent = `# ${slug}
+
+${question}
+
+---
+Enter your response below:
+
+`;
+
+  fs.writeFileSync(interactionFile, fileContent);
+
+  runtime.prependHistory({
+    event: 'INTERACTION_REQUESTED',
+    slug,
+    targetKey: memoryKey,
+    file: interactionFile
+  });
+
+  // Block and wait for user input (instead of throwing)
+  const answer = await runtime.waitForInteraction(interactionFile, slug, memoryKey);
+
+  runtime._rawMemory[memoryKey] = answer;
+  runtime.persist();
+
+  runtime.prependHistory({
+    event: 'PROMPT_ANSWERED',
+    slug,
+    answer: answer.substring(0, 100) + (answer.length > 100 ? '...' : '')
+  });
+
+  return answer;
+}
+
+/**
+ * Interactive terminal question
+ */
+function askQuestion(question) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout
+    });
+
+    rl.question(`${question}\n> `, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+/**
+ * Generate a slug from question text
+ */
+function generateSlug(question) {
+  return question
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .substring(0, 30);
+}