agent-state-machine 1.0.0

package/README.md

@@ -0,0 +1,299 @@
+# agent-state-machine
+
+A workflow runner for building **linear, stateful agent workflows** in plain JavaScript.
+
+You write normal `async/await` code. The runtime handles:
+- **Auto-persisted** `memory` (saved to disk on mutation)
+- **Human-in-the-loop** blocking via `initialPrompt()` or agent-driven interactions
+- Local **JS agents** + **Markdown agents** (LLM-powered)
+
+---
+
+## Install
+
+```bash
+npm i agent-state-machine
+```
+
+Global CLI:
+
+```bash
+npm i -g agent-state-machine
+```
+
+Requirements: Node.js >= 16.
+
+---
+
+## CLI
+
+```bash
+state-machine --setup <workflow-name>
+state-machine run <workflow-name>
+state-machine resume <workflow-name>
+state-machine status <workflow-name>
+state-machine history <workflow-name> [limit]
+state-machine reset <workflow-name>
+```
+
+Workflows live in:
+
+```text
+workflows/<name>/
+├── workflow.js        # Native JS workflow (async/await)
+├── 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, generated-prompt.md
+└── steering/          # global.md + config.json
+```
+
+---
+
+## Writing workflows (native JS)
+
+```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, initialPrompt, parallel } from 'agent-state-machine';
+import { notify } from './scripts/mac-notification.js';
+
+// Model configuration (also supports models in a separate config export)
+export const config = {
+  models: {
+    low: "gemini",
+    med: "codex --model gpt-5.2",
+    high: "claude -m claude-opus-4-20250514 -p",
+  },
+  apiKeys: {
+    gemini: process.env.GEMINI_API_KEY,
+    anthropic: process.env.ANTHROPIC_API_KEY,
+    openai: process.env.OPENAI_API_KEY,
+  }
+};
+
+export default async function() {
+  console.log('Starting project-builder workflow...');
+
+  // Example: Get user input (saved to memory)
+  const answer = await initialPrompt('Where do you live?');
+  console.log('Example prompt answer:', answer);
+
+  const userInfo = await agent('yoda-name-collector');
+  memory.userInfo = userInfo;
+
+  // Provide context
+  // const userInfo = await agent('yoda-name-collector', { name: 'Luke' });
+
+  console.log('Example agent memory.userInfo:', memory.userInfo || userInfo);
+
+  // Context is provided automatically
+  const { greeting } = await agent('yoda-greeter');
+  console.log('Example agent greeting:', greeting);
+
+  // Or you can provide context manually
+  // await agent('yoda-greeter', userInfo);
+
+  // Example: Parallel execution
+  // const [a, b] = await parallel([
+  //   agent('example', { which: 'a' }),
+  //   agent('example', { which: 'b' })
+  // ]);
+
+  notify(['project-builder', userInfo.name || userInfo + ' has been greeted!']);
+
+  console.log('Workflow completed!');
+}
+```
+
+### How “resume” works
+
+`resume` restarts your workflow from the top. 
+
+If the workflow needs human input, it will **block inline** in the terminal. You’ll be told which `interactions/<slug>.md` file to edit; after you fill it in, press `y` in the same terminal session to continue.
+
+If the process is interrupted, running `state-machine resume <workflow-name>` will restart the execution. Use the `memory` object to store and skip work manually if needed.
+
+---
+
+## Core API
+
+### `agent(name, params?)`
+
+Runs `workflows/<name>/agents/<agent>.(js|mjs|cjs)` or `<agent>.md`.
+
+```js
+const out = await agent('review', { file: 'src/app.js' });
+memory.lastReview = out;
+```
+
+### `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;
+```
+
+### `initialPrompt(question, options?)`
+
+Gets user input.
+
+- In a TTY, it prompts in the terminal.
+- Otherwise it creates `interactions/<slug>.md` and blocks until you confirm in the terminal.
+
+```js
+const repo = await initialPrompt('What repo should I work on?', { slug: 'repo' });
+memory.repo = repo;
+```
+
+### `parallel([...])` / `parallelLimit([...], limit)`
+
+Run multiple `agent()` calls concurrently:
+
+```js
+import { agent, parallel, parallelLimit } from 'agent-state-machine';
+
+const [a, b] = await parallel([
+  agent('review', { file: 'src/a.js' }),
+  agent('review', { file: 'src/b.js' }),
+]);
+
+const results = await parallelLimit(
+  ['a.js', 'b.js', 'c.js'].map(f => agent('review', { file: f })),
+  2
+);
+```
+
+---
+
+## Agents
+
+Agents live in `workflows/<workflow>/agents/`.
+
+### JavaScript agents
+
+**ESM (`.js` / `.mjs`)**:
+
+```js
+// workflows/<name>/agents/example.js
+import { llm } from 'agent-state-machine';
+
+export default async function handler(context) {
+  // context includes:
+  // - persisted memory (spread into the object)
+  // - params passed to agent(name, params)
+  // - context._steering (global steering prompt/config)
+  // - context._config (models/apiKeys/workflowDir)
+  return { ok: true };
+}
+```
+
+**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;
+```
+
+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.
+
+```md
+---
+model: smart
+output: greeting
+---
+Generate a friendly greeting for {{name}}.
+```
+
+Calling it:
+
+```js
+const { greeting } = await agent('greeter', { name: 'Sam' });
+memory.greeting = greeting;
+```
+
+---
+
+## Models & LLM execution
+
+In your workflow’s `export const config = { models: { ... } }`, each model value can be:
+
+### CLI command
+
+```js
+export const config = {
+  models: {
+    smart: "claude -m claude-sonnet-4-20250514 -p"
+  }
+};
+```
+
+### API target
+
+Format: `api:<provider>:<model>`
+
+```js
+export const config = {
+  models: {
+    smart: "api:openai:gpt-4.1-mini"
+  },
+  apiKeys: {
+    openai: process.env.OPENAI_API_KEY
+  }
+};
+```
+
+The runtime writes the fully-built prompt to:
+
+```text
+workflows/<name>/state/generated-prompt.md
+```
+
+---
+
+## State & persistence
+
+Native JS workflows persist to:
+
+- `workflows/<name>/state/current.json` — status, memory, pending interaction
+- `workflows/<name>/state/history.jsonl` — event log (newest entries first)
+- `workflows/<name>/interactions/*.md` — human input files (when paused)
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,246 @@
+#!/usr/bin/env node
+
+import path from 'path';
+import fs from 'fs';
+import { pathToFileURL } from 'url';
+import { WorkflowRuntime } from '../lib/index.js';
+import { setup } from '../lib/setup.js';
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+function printHelp() {
+  console.log(`
+Agent State Machine CLI (Native JS Workflows Only)
+
+Usage:
+  state-machine --setup <workflow-name>    Create a new workflow project
+  state-machine run <workflow-name>        Run a workflow from the beginning
+  state-machine resume <workflow-name>     Resume a paused workflow
+  state-machine status [workflow-name]     Show current state (or list all)
+  state-machine history <workflow-name> [limit]  Show execution history
+  state-machine reset <workflow-name>      Reset workflow state
+  state-machine reset-hard <workflow-name> Hard reset (clear history/interactions)
+  state-machine list                       List all workflows
+  state-machine help                       Show this help
+
+Options:
+  --setup, -s     Initialize a new workflow with directory structure
+  --help, -h      Show help
+
+Workflow Structure:
+  workflows/<name>/
+  ├── workflow.js        # Native JS workflow (async/await)
+  ├── 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, generated-prompt.md
+  └── steering/          # global.md + config.json
+`);
+}
+
+function workflowsRoot() {
+  return path.join(process.cwd(), 'workflows');
+}
+
+function resolveWorkflowDir(workflowName) {
+  return path.join(workflowsRoot(), workflowName);
+}
+
+function resolveWorkflowEntry(workflowDir) {
+  const candidates = ['workflow.js', 'workflow.mjs'];
+  for (const f of candidates) {
+    const p = path.join(workflowDir, f);
+    if (fs.existsSync(p)) return p;
+  }
+  return null;
+}
+
+function readState(workflowDir) {
+  const stateFile = path.join(workflowDir, 'state', 'current.json');
+  if (!fs.existsSync(stateFile)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(stateFile, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+function summarizeStatus(state) {
+  if (!state) return ' [no state]';
+
+  const s = String(state.status || '').toUpperCase();
+  if (s === 'COMPLETED') return ' [completed]';
+  if (s === 'FAILED') return ' [failed - can resume]';
+  if (s === 'PAUSED') return ' [paused - can resume]';
+  if (s === 'RUNNING') return ' [running]';
+  if (s === 'IDLE') return ' [idle]';
+  return state.status ? ` [${state.status}]` : '';
+}
+
+function listWorkflows() {
+  const root = workflowsRoot();
+
+  if (!fs.existsSync(root)) {
+    console.log('No workflows directory found.');
+    console.log('Run `state-machine --setup <name>` to create your first workflow.');
+    return;
+  }
+
+  const workflows = fs
+    .readdirSync(root, { withFileTypes: true })
+    .filter((d) => d.isDirectory())
+    .map((d) => d.name)
+    .sort((a, b) => a.localeCompare(b));
+
+  if (workflows.length === 0) {
+    console.log('No workflows found.');
+    console.log('Run `state-machine --setup <name>` to create your first workflow.');
+    return;
+  }
+
+  console.log('\nAvailable Workflows:');
+  console.log('─'.repeat(40));
+
+  for (const name of workflows) {
+    const dir = resolveWorkflowDir(name);
+    const entry = resolveWorkflowEntry(dir);
+    const state = readState(dir);
+
+    const entryNote = entry ? '' : ' [missing workflow.js]';
+    const statusNote = summarizeStatus(state);
+
+    const pausedNote =
+      state && state._pendingInteraction && state._pendingInteraction.file
+        ? ` [needs input: ${state._pendingInteraction.file}]`
+        : '';
+
+    console.log(`  ${name}${entryNote}${statusNote}${pausedNote}`);
+  }
+
+  console.log('');
+}
+
+async function runOrResume(workflowName) {
+  const workflowDir = resolveWorkflowDir(workflowName);
+
+  if (!fs.existsSync(workflowDir)) {
+    console.error(`Error: Workflow '${workflowName}' not found at ${workflowDir}`);
+    console.error(`Run: state-machine --setup ${workflowName}`);
+    process.exit(1);
+  }
+
+  const entry = resolveWorkflowEntry(workflowDir);
+  if (!entry) {
+    console.error(`Error: No workflow entry found (expected workflow.js or workflow.mjs) in ${workflowDir}`);
+    process.exit(1);
+  }
+
+  const runtime = new WorkflowRuntime(workflowDir);
+  const workflowUrl = pathToFileURL(entry).href;
+
+  await runtime.runWorkflow(workflowUrl);
+}
+
+async function main() {
+  if (!command || command === 'help' || command === '--help' || command === '-h') {
+    printHelp();
+    process.exit(0);
+  }
+
+  if (command === '--setup' || command === '-s') {
+    const workflowName = args[1];
+    if (!workflowName) {
+      console.error('Error: Workflow name required');
+      console.error('Usage: state-machine --setup <workflow-name>');
+      process.exit(1);
+    }
+    await setup(workflowName);
+    process.exit(0);
+  }
+
+  const workflowName = args[1];
+
+  switch (command) {
+    case 'run':
+    case 'resume':
+      if (!workflowName) {
+        console.error('Error: Workflow name required');
+        console.error(`Usage: state-machine ${command} <workflow-name>`);
+        process.exit(1);
+      }
+      try {
+        await runOrResume(workflowName);
+      } catch (err) {
+        console.error('Error:', err.message || String(err));
+        process.exit(1);
+      }
+      break;
+
+    case 'status':
+      if (!workflowName) {
+        listWorkflows();
+        break;
+      }
+      {
+        const workflowDir = resolveWorkflowDir(workflowName);
+        const runtime = new WorkflowRuntime(workflowDir);
+        runtime.showStatus();
+      }
+      break;
+
+    case 'history':
+      if (!workflowName) {
+        console.error('Error: Workflow name required');
+        console.error('Usage: state-machine history <workflow-name> [limit]');
+        process.exit(1);
+      }
+      {
+        const limit = parseInt(args[2], 10) || 20;
+        const workflowDir = resolveWorkflowDir(workflowName);
+        const runtime = new WorkflowRuntime(workflowDir);
+        runtime.showHistory(limit);
+      }
+      break;
+
+    case 'reset':
+      if (!workflowName) {
+        console.error('Error: Workflow name required');
+        console.error('Usage: state-machine reset <workflow-name>');
+        process.exit(1);
+      }
+      {
+        const workflowDir = resolveWorkflowDir(workflowName);
+        const runtime = new WorkflowRuntime(workflowDir);
+        runtime.reset();
+      }
+      break;
+
+    case 'reset-hard':
+      if (!workflowName) {
+        console.error('Error: Workflow name required');
+        console.error('Usage: state-machine reset-hard <workflow-name>');
+        process.exit(1);
+      }
+      {
+        const workflowDir = resolveWorkflowDir(workflowName);
+        const runtime = new WorkflowRuntime(workflowDir);
+        runtime.resetHard();
+      }
+      break;
+
+    case 'list':
+      listWorkflows();
+      break;
+
+    default:
+      console.error(`Unknown command: ${command}`);
+      printHelp();
+      process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  console.error('Fatal error:', err);
+  process.exit(1);
+});

package/lib/index.js

@@ -0,0 +1,110 @@
+/**
+ * File: /lib/index.js
+ *
+ * Public API (native JS workflows only)
+ */
+
+import { setup } from './setup.js';
+import { llm, llmText, llmJSON, parseJSON, detectAvailableCLIs } from './llm.js';
+
+import {
+  WorkflowRuntime,
+  agent,
+  executeAgent,
+  initialPrompt,
+  parallel,
+  parallelLimit,
+  getMemory,
+  getCurrentRuntime
+} from './runtime/index.js';
+
+/**
+ * Live memory proxy:
+ * - Reads/writes always target the *current* workflow runtime's memory proxy
+ * - Throws on writes if used outside a workflow run (prevents silent no-op)
+ */
+export const memory = new Proxy(
+  {},
+  {
+    get(_target, prop) {
+      const runtime = getCurrentRuntime();
+      if (!runtime) return undefined;
+      return runtime.memory[prop];
+    },
+    set(_target, prop, value) {
+      const runtime = getCurrentRuntime();
+      if (!runtime) {
+        throw new Error('memory can only be mutated within a running workflow');
+      }
+      runtime.memory[prop] = value;
+      return true;
+    },
+    deleteProperty(_target, prop) {
+      const runtime = getCurrentRuntime();
+      if (!runtime) {
+        throw new Error('memory can only be mutated within a running workflow');
+      }
+      delete runtime.memory[prop];
+      return true;
+    },
+    has(_target, prop) {
+      const runtime = getCurrentRuntime();
+      if (!runtime) return false;
+      const raw = runtime.memory?._raw || runtime._rawMemory || {};
+      return prop in raw;
+    },
+    ownKeys() {
+      const runtime = getCurrentRuntime();
+      if (!runtime) return [];
+      const raw = runtime.memory?._raw || runtime._rawMemory || {};
+      return Reflect.ownKeys(raw);
+    },
+    getOwnPropertyDescriptor(_target, prop) {
+      const runtime = getCurrentRuntime();
+      if (!runtime) return undefined;
+      const raw = runtime.memory?._raw || runtime._rawMemory || {};
+      if (!(prop in raw)) return undefined;
+      return {
+        enumerable: true,
+        configurable: true
+      };
+    }
+  }
+);
+
+export {
+  setup,
+  llm,
+  llmText,
+  llmJSON,
+  parseJSON,
+  detectAvailableCLIs,
+  WorkflowRuntime,
+  agent,
+  executeAgent,
+  initialPrompt,
+  parallel,
+  parallelLimit,
+  getCurrentRuntime,
+  getMemory
+};
+
+const api = {
+  setup,
+  llm,
+  llmText,
+  llmJSON,
+  parseJSON,
+  detectAvailableCLIs,
+  WorkflowRuntime,
+  agent,
+  executeAgent,
+  initialPrompt,
+  parallel,
+  parallelLimit,
+  getCurrentRuntime,
+  getMemory,
+  memory
+};
+
+export default api;

package/lib/index.mjs

@@ -0,0 +1,9 @@
+/**
+ * File: /lib/index.mjs
+ *
+ * ESM re-export shim
+ */
+
+export * from './index.js';
+import * as api from './index.js';
+export default api;