agent-state-machine 2.0.14 → 2.1.0

package/templates/starter/agents/example.js

@@ -0,0 +1,36 @@
+/**
+ * Example Agent for __WORKFLOW_NAME__
+ *
+ * Agents are async functions that receive a context object and return a result.
+ * - Context includes: params, _steering, _config
+ */
+
+import { llm } from 'agent-state-machine';
+
+export default async function handler(context) {
+  console.log('[Agent: example] Processing...');
+
+  // Access global steering prompt if available
+  if (context._steering?.global) {
+    console.log('[Agent: example] Steering loaded (' + context._steering.global.length + ' chars)');
+  }
+
+  // Example: Call an LLM (configure models in config.js)
+  // const response = await llm(context, {
+  //   model: 'smart',
+  //   prompt: 'Say hello and describe what you can help with.'
+  // });
+  // console.log('[Agent: example] LLM response:', response.text);
+
+  return {
+    ok: true,
+    received: Object.keys(context).filter((k) => !String(k).startsWith('_')),
+    processedAt: new Date().toISOString()
+  };
+}
+
+export const meta = {
+  name: 'example',
+  description: 'An example agent to get you started',
+  version: '1.0.0'
+};

package/templates/starter/agents/yoda-greeter.md

@@ -0,0 +1,12 @@
+---
+model: low
+output: greeting
+---
+
+# Greeting Task
+
+Generate a friendly greeting for {{name}} from {{location}} in a yoda style. Prompt user for their actual {{name}} if you dont have it.
+
+Once you have it create a yoda-greeting.md file in root dir with the greeting.
+
+You are a fast, direct worker. Do NOT investigate the codebase or read files unless strictly necessary. Perform the requested action immediately using the provided context. Avoid "thinking" steps or creating plans if the task is simple.

package/templates/starter/agents/yoda-name-collector.md

@@ -0,0 +1,12 @@
+---
+model: low
+output: name
+---
+
+# Name Collection Task
+
+Ask for users name in a yoda style. Unless you have it already.
+
+Keep it brief and warm.
+
+You are a fast, direct worker. Do NOT investigate the codebase or read files unless strictly necessary. Perform the requested action immediately using the provided context. Avoid "thinking" steps or creating plans if the task is simple.

package/templates/starter/config.js

@@ -0,0 +1,12 @@
+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,
+  }
+};

package/templates/starter/scripts/mac-notification.js

@@ -0,0 +1,24 @@
+"use strict";
+
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+
+function escAppleScript(s) {
+  return String(s).replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+
+function notify(title = "Notification", message = "Everything finished!") {
+  const script = `display notification "${escAppleScript(message)}" with title "${escAppleScript(title)}"`;
+  spawnSync("osascript", ["-e", script], { stdio: "ignore" });
+
+  const soundPath = "/System/Library/Sounds/Glass.aiff";
+  const fallbackPath = "/System/Library/Sounds/Ping.aiff";
+
+  if (existsSync(soundPath)) {
+    spawnSync("afplay", [soundPath], { stdio: "ignore" });
+  } else if (existsSync(fallbackPath)) {
+    spawnSync("afplay", [fallbackPath], { stdio: "ignore" });
+  }
+}
+
+export { notify };

package/templates/starter/state/current.json

@@ -0,0 +1,9 @@
+{
+  "format": "native",
+  "status": "IDLE",
+  "memory": {},
+  "_pendingInteraction": null,
+  "_error": null,
+  "startedAt": null,
+  "lastUpdatedAt": "__NOW_ISO__"
+}

package/templates/starter/steering/config.json

@@ -0,0 +1,5 @@
+{
+  "_comment": "Steering configuration",
+  "enabled": true,
+  "globalPrompt": "global.md"
+}

package/templates/starter/steering/global.md

@@ -0,0 +1,19 @@
+# Global Steering Prompt
+
+This content is included with every agent execution in the __WORKFLOW_NAME__ workflow.
+
+## Guidelines
+
+- Process data carefully and validate inputs
+- Return well-structured JSON when applicable
+- Log meaningful progress messages
+- Handle errors gracefully
+
+## Helpful Tips
+- Scripts live in /workflows/__WORKFLOW_NAME__/scripts/
+- .gitignore includes /workflows so include ignored files when searching for a script and use `search_file_content` with the `no_ignore` flag to read the contents of script files.
+- Shell execution via `run_shell_command` is unavailable, so reproduce the script's intended side effect to fulfill the task.
+
+## Notes
+
+This file is automatically loaded and passed to every agent in the workflow via `context._steering.global`.

package/templates/starter/workflow.js

@@ -0,0 +1,52 @@
+/**
+/**
+ * __WORKFLOW_NAME__ Workflow
+ *
+ * Native JavaScript workflow - write normal async/await code!
+ *
+ * Features:
+ * - memory object auto-persists to disk (use memory guards for idempotency)
+ * - Use standard JS control flow (if, for, etc.)
+ * - Interactive prompts pause and wait for user input
+ */
+
+import { agent, memory, askHuman, parallel } from 'agent-state-machine';
+import { notify } from './scripts/mac-notification.js';
+
+export default async function() {
+  console.log('Starting __WORKFLOW_NAME__ workflow...');
+
+  // Example: Get user input (saved to memory)
+  const userLocation = await askHuman('Where do you live?');
+  console.log('Example prompt answer:', userLocation);
+
+  const userName = await agent('yoda-name-collector');
+  memory.userName = userName;
+
+  // Provide context
+  // const userName = await agent('yoda-name-collector', { name: 'Luke' });
+
+  console.log('Example agent memory.userName:', memory.userName || userName);
+
+  // Context is explicit: pass what the agent needs
+  const { greeting } = await agent('yoda-greeter', { userLocation, memory });
+  console.log('Example agent greeting::', greeting);
+
+  // Or you can provide context manually
+  // await agent('yoda-greeter', userName);
+
+  // Example: Parallel execution
+  // const [a, b, c] = await parallel([
+  //   agent('yoda-greeter', { name: 'the names augustus but friends call me gus' }),
+  //   agent('yoda-greeter', { name: 'uriah' }),
+  //   agent('yoda-greeter', { name: 'lucas' })
+  // ]);
+
+  // console.log('a: ' + JSON.stringify(a))
+  // console.log('b: ' + JSON.stringify(b))
+  // console.log('c: ' + JSON.stringify(c))
+
+  notify(['__WORKFLOW_NAME__', userName.name || userName + ' has been greeted!']);
+
+  console.log('Workflow completed!');
+}

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

@@ -11,8 +11,8 @@ const __dirname = path.dirname(__filename);
 let cachedTemplate = null;
 async function getTemplate() {
   if (cachedTemplate) return cachedTemplate;
-  // Point to the unified template in vercel-server/ui/index.html
-  const templatePath = path.join(__dirname, '..', '..', 'ui', 'index.html');
+  // Point to the built template in vercel-server/public/remote/index.html
+  const templatePath = path.join(__dirname, '..', '..', 'public', 'remote', 'index.html');
   cachedTemplate = await readFile(templatePath, 'utf8');
   return cachedTemplate;
 }
@@ -46,4 +46,4 @@ export default async function handler(req, res) {
 
   res.setHeader('Content-Type', 'text/html; charset=utf-8');
   res.send(html);
-}
+}

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

@@ -47,12 +47,14 @@ export default async function handler(req, res) {
     const body = typeof req.body === 'string' ? JSON.parse(req.body) : req.body;
     const { slug, targetKey, response } = body;
 
-    if (!slug || !response) {
+    if (!slug || response === undefined || response === null) {
       return res.status(400).json({ error: 'Missing required fields: slug, response' });
     }
 
+    const responseString = typeof response === 'string' ? response : JSON.stringify(response);
+
     // Validate response size (max 1MB)
-    if (response.length > 1024 * 1024) {
+    if (responseString.length > 1024 * 1024) {
       return res.status(413).json({ error: 'Response too large (max 1MB)' });
     }
 
@@ -73,7 +75,7 @@ export default async function handler(req, res) {
       event: 'INTERACTION_SUBMITTED',
       slug,
       targetKey: targetKey || `_interaction_${slug}`,
-      answer: response.substring(0, 200) + (response.length > 200 ? '...' : ''),
+      answer: responseString.substring(0, 200) + (responseString.length > 200 ? '...' : ''),
       source: 'remote',
     });
 

package/vercel-server/local-server.js

@@ -24,6 +24,7 @@ const PORT = process.env.PORT || 3001;
 
 // In-memory session storage
 const sessions = new Map();
+let latestSessionToken = null;
 
 // SSE clients per session
 const sseClients = new Map(); // token -> Set<res>
@@ -44,6 +45,7 @@ function createSession(token, data) {
     createdAt: Date.now(),
   };
   sessions.set(token, session);
+  latestSessionToken = token;
   return session;
 }
 
@@ -308,10 +310,12 @@ async function handleSubmitPost(req, res, token) {
   const body = await parseBody(req);
   const { slug, targetKey, response } = body;
 
-  if (!slug || !response) {
+  if (!slug || response === undefined || response === null) {
     return sendJson(res, 400, { error: 'Missing slug or response' });
   }
 
+  const responseString = typeof response === 'string' ? response : JSON.stringify(response);
+
   // Add to pending interactions for CLI to pick up
   session.pendingInteractions.push({
     slug,
@@ -325,7 +329,7 @@ async function handleSubmitPost(req, res, token) {
     event: 'INTERACTION_SUBMITTED',
     slug,
     targetKey: targetKey || `_interaction_${slug}`,
-    answer: response.substring(0, 200) + (response.length > 200 ? '...' : ''),
+    answer: responseString.substring(0, 200) + (responseString.length > 200 ? '...' : ''),
     source: 'remote',
   };
   session.history.unshift(event);
@@ -342,10 +346,10 @@ async function handleSubmitPost(req, res, token) {
 /**
  * Serve session UI
  */
-const MASTER_TEMPLATE_PATH = path.join(__dirname, 'ui', 'index.html');
+const MASTER_TEMPLATE_PATH = path.join(__dirname, 'public', 'remote', 'index.html');
 
 /**
- * Get session HTML by reading the master template from lib/ui/index.html
+ * Get session HTML by reading the master template from public/remote/index.html
  */
 function getSessionHTML(token, workflowName) {
   try {
@@ -362,7 +366,8 @@ function getSessionHTML(token, workflowName) {
         <body style="font-family: system-ui; max-width: 600px; margin: 100px auto; text-align: center;">
           <h1>Error loading UI template</h1>
           <p>${err.message}</p>
-          <p>Make sure <code>lib/ui/index.html</code> exists.</p>
+          <p>Make sure <code>public/remote/index.html</code> exists.</p>
+          <p>Build the UI first: <code>cd vercel-server/ui && npm install && npm run build</code></p>
         </body>
       </html>
     `;
@@ -395,6 +400,16 @@ function serveSessionUI(res, token) {
 
 // getSessionHTML was moved up and updated to read from MASTER_TEMPLATE_PATH
 
+function getDefaultSessionToken() {
+  if (latestSessionToken && sessions.has(latestSessionToken)) {
+    return latestSessionToken;
+  }
+  if (sessions.size === 1) {
+    return sessions.keys().next().value;
+  }
+  return null;
+}
+
 /**
  * Serve static files
  */
@@ -470,10 +485,22 @@ async function handleRequest(req, res) {
   }
 
   // Route: Static files
-  if (pathname === '/' || pathname === '/index.html') {
+  if (pathname === '/') {
+    const defaultToken = getDefaultSessionToken();
+    if (defaultToken) {
+      return serveSessionUI(res, defaultToken);
+    }
     return serveStatic(res, 'index.html');
   }
 
+  if (pathname === '/index.html') {
+    return serveStatic(res, 'index.html');
+  }
+
+  if (pathname.startsWith('/remote/')) {
+    return serveStatic(res, pathname.slice(1));
+  }
+
   // 404
   res.writeHead(404);
   res.end('Not found');

package/vercel-server/public/remote/index.html

@@ -0,0 +1,17 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />
+    <title>{{WORKFLOW_NAME}}</title>
+    <script type="module" crossorigin src="/remote/assets/index-DiKoT5IY.js"></script>
+    <link rel="stylesheet" crossorigin href="/remote/assets/index-dzq5qHNh.css">
+  </head>
+  <body>
+    <div id="root"></div>
+    <script>
+      window.SESSION_TOKEN = "{{SESSION_TOKEN}}";
+      window.WORKFLOW_NAME_TEMPLATE = "{{WORKFLOW_NAME}}";
+    </script>
+  </body>
+</html>