@adaptic/maestro 1.1.0 → 1.1.1

package/lib/action-executor.js

@@ -0,0 +1,225 @@
+/**
+ * Maestro — Action Executor
+ *
+ * Executes tool calls from the Claude API. Write tools run agent-local
+ * scripts; lookup/RAG tools run targeted `claude --print` queries that
+ * leverage MCP servers (Gmail, Calendar, Slack, filesystem, etc.)
+ * via the agent's Max subscription.
+ *
+ * Usage:
+ *   import { executeAction } from "@adaptic/maestro/lib/action-executor.js";
+ *   const result = await executeAction("search_email", { query: "..." }, callerInfo, sessionId);
+ *
+ * @module action-executor
+ */
+
+import { execFile } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { getToolNamesForAccessLevel } from "./tool-definitions.js";
+
+const AGENT_ROOT = process.env.AGENT_ROOT || process.cwd();
+
+// ---------------------------------------------------------------------------
+// Access Control
+// ---------------------------------------------------------------------------
+
+function isAuthorized(toolName, accessLevel) {
+  return getToolNamesForAccessLevel(accessLevel).includes(toolName);
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Execute a tool call.
+ * @param {string} toolName
+ * @param {object} input
+ * @param {object} callerInfo - { slug, name, accessLevel }
+ * @param {string} sessionId
+ * @param {object} [options] - { agentRoot, scripts }
+ * @returns {Promise<{success: boolean, result: string}>}
+ */
+export async function executeAction(toolName, input, callerInfo, sessionId, options = {}) {
+  const agentRoot = options.agentRoot || AGENT_ROOT;
+
+  if (!isAuthorized(toolName, callerInfo.accessLevel)) {
+    return { success: false, result: "You do not have permission to perform this action." };
+  }
+
+  try {
+    // Lookup tools — RAG via Claude Code CLI
+    if (LOOKUP_PROMPTS[toolName]) {
+      return await executeLookup(toolName, input, agentRoot);
+    }
+
+    // Write tools — delegate to agent-local scripts
+    switch (toolName) {
+      case "slack_send":
+        return await executeScript(agentRoot, "slack-send.sh", [input.recipient, input.message]);
+      case "draft_email":
+        return await executeDraft(agentRoot, input);
+      case "whatsapp_send":
+        return await executeScript(agentRoot, "send-whatsapp.sh", [input.recipient, input.message]);
+      case "sms_send":
+        return await executeScript(agentRoot, "send-sms.sh", [input.recipient, input.message]);
+      case "queue_update":
+        return await executeQueueUpdate(agentRoot, input);
+      case "create_action_item":
+        return await executeCreateItem(agentRoot, input);
+      case "schedule_meeting":
+        return await executeLookup("schedule_meeting", input, agentRoot);
+      case "create_reminder":
+        return await executeLookup("create_reminder", input, agentRoot);
+      case "generate_memo":
+        return await executeGenerateMemo(agentRoot, input);
+      case "generate_report":
+        return await executeLookup("generate_report", input, agentRoot);
+      default:
+        return { success: false, result: `Unknown tool: ${toolName}` };
+    }
+  } catch (err) {
+    return { success: false, result: `Action failed: ${err.message}` };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Lookup / RAG via Claude Code CLI
+// ---------------------------------------------------------------------------
+
+const LOOKUP_PROMPTS = {
+  search_email: (i) =>
+    `Search Gmail for: "${i.query}". Return top ${i.max_results || 5} results with sender, subject, date, 1-sentence summary. Be concise — spoken aloud.`,
+  search_calendar: (i) =>
+    `Look up calendar: "${i.query}" for ${i.time_range || "this week"}. List events with title, time, attendees. Be concise.`,
+  search_files: (i) =>
+    `Search operational files for: "${i.query}"${i.scope && i.scope !== "all" ? ` in ${i.scope}/` : ""}. Summarise in 2-4 sentences.`,
+  search_meetings: (i) =>
+    `Search Granola meeting notes for: "${i.query}"${i.date_range ? ` from ${i.date_range}` : ""}. Summarise key discussions and decisions in 2-4 sentences.`,
+  search_slack: (i) =>
+    `Search Slack for: "${i.query}"${i.channel ? ` in ${i.channel}` : ""}. Summarise who said what, when. 2-4 sentences.`,
+  search_web: (i) =>
+    `Web search: "${i.query}". Summarise top ${i.max_results || 5} results concisely.`,
+  search_documents: (i) =>
+    `Search shared documents for: "${i.query}"${i.doc_type && i.doc_type !== "all" ? ` (${i.doc_type} only)` : ""}. List titles and brief summaries.`,
+  search_decisions: (i) =>
+    `Search the decision archive for: "${i.query}". Include rationale, who decided, and outcome. 2-4 sentences.`,
+  lookup_person: (i) =>
+    `Look up information about ${i.name}: ${i.info_type || "all available info"} — role, contact, recent activity. Be concise.`,
+  search_regulatory: (i) =>
+    `Search regulatory/compliance info for: "${i.query}"${i.jurisdiction ? ` in ${i.jurisdiction}` : ""}. Status, deadlines, requirements. Be concise.`,
+  search_strategy: (i) =>
+    `Search strategic context for: "${i.query}". Priorities, OKRs, initiative status. 2-4 sentences.`,
+  search_precedents: (i) =>
+    `Search operational precedents for: "${i.query}". How was this handled before? Templates? 2-4 sentences.`,
+  search_financial: (i) =>
+    `Search financial data for: "${i.query}". Runway, burn, capital readiness. Be concise.`,
+  search_pipeline: (i) =>
+    `Search pipeline for: "${i.query}"${i.stage && i.stage !== "all" ? ` (stage: ${i.stage})` : ""}. Deal status, partner conversations. Be concise.`,
+  search_engineering: (i) =>
+    `Search engineering health for: "${i.query}"${i.repo ? ` in ${i.repo}` : ""}. PRs, delivery confidence, blockers. Be concise.`,
+  search_hiring: (i) =>
+    `Search hiring pipeline for: "${i.query}"${i.status && i.status !== "all" ? ` (status: ${i.status})` : ""}. Roles, candidates, offers. Be concise.`,
+  search_risk: (i) =>
+    `Search risk register for: "${i.query}"${i.severity && i.severity !== "all" ? ` (severity: ${i.severity})` : ""}. Risks, mitigations, owners. Be concise.`,
+  schedule_meeting: (i) =>
+    `Schedule a meeting: "${i.title}" with ${i.attendees} on ${i.date}${i.time ? ` at ${i.time}` : ""}${i.duration ? ` for ${i.duration}` : ""}. Check availability and create the event. Confirm what was scheduled.`,
+  create_reminder: (i) =>
+    `Create a reminder: "${i.message}" for ${i.for_whom || "the principal"} at ${i.when}. Confirm when it will fire.`,
+  generate_report: (i) =>
+    `Generate a ${i.report_type} report${i.custom_query ? `: ${i.custom_query}` : ""}${i.time_range ? ` for ${i.time_range}` : ""}. Aggregate data from dashboards and queues. Format as a concise executive summary.`,
+};
+
+async function executeLookup(toolName, input, agentRoot) {
+  const promptBuilder = LOOKUP_PROMPTS[toolName];
+  if (!promptBuilder) return { success: false, result: `No prompt for: ${toolName}` };
+
+  const prompt = promptBuilder(input);
+
+  try {
+    const { stdout } = await new Promise((resolve, reject) => {
+      execFile("claude", ["--print", "--model", "haiku", "-p", prompt], {
+        timeout: 25000,
+        maxBuffer: 1024 * 1024,
+        env: { ...process.env, TERM: "dumb" },
+        cwd: agentRoot,
+      }, (err, stdout, stderr) => {
+        if (err) reject(err);
+        else resolve({ stdout, stderr });
+      });
+    });
+
+    return { success: true, result: (stdout || "").trim() || "No results found." };
+  } catch (err) {
+    if (err.killed) return { success: false, result: "Search timed out. Try a more specific query." };
+    return { success: false, result: `Search failed: ${err.message}` };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Write tool executors (generic implementations — agents can override)
+// ---------------------------------------------------------------------------
+
+async function executeScript(agentRoot, scriptName, args) {
+  const scriptPath = path.join(agentRoot, "scripts", scriptName);
+  if (!fs.existsSync(scriptPath)) {
+    return { success: false, result: `Script not found: ${scriptName}` };
+  }
+
+  return new Promise((resolve) => {
+    execFile("bash", [scriptPath, ...args.filter(Boolean)], {
+      timeout: 15000,
+      cwd: agentRoot,
+      env: { ...process.env },
+    }, (err, stdout, stderr) => {
+      if (err) resolve({ success: false, result: stderr || err.message });
+      else resolve({ success: true, result: stdout.trim() || "Done." });
+    });
+  });
+}
+
+async function executeDraft(agentRoot, input) {
+  const draftsDir = path.join(agentRoot, "outputs/drafts");
+  fs.mkdirSync(draftsDir, { recursive: true });
+
+  const date = new Date().toISOString().split("T")[0];
+  const slug = input.to.replace(/[^a-zA-Z0-9]/g, "-").toLowerCase();
+  const filePath = path.join(draftsDir, `${date}-draft-${slug}.md`);
+
+  const content = `---\nto: ${input.to}\nsubject: ${input.subject}\nvoice: ${input.voice || "agent"}\nurgency: ${input.urgency || "routine"}\ndate: ${new Date().toISOString()}\n---\n\n${input.body}\n`;
+  fs.writeFileSync(filePath, content);
+
+  if (input.urgency === "immediate") {
+    return executeScript(agentRoot, "send-email.sh", [input.to, input.subject, input.body]);
+  }
+
+  return { success: true, result: `Draft saved: ${filePath}` };
+}
+
+async function executeQueueUpdate(agentRoot, input) {
+  // Delegate to claude CLI for intelligent queue searching and updating
+  return executeLookup("queue_update_internal", input, agentRoot);
+}
+
+// Add queue_update_internal to LOOKUP_PROMPTS
+LOOKUP_PROMPTS.queue_update_internal = (i) =>
+  `In the state/queues/ directory, find the item matching "${i.search_term}" and update its status to "${i.new_status}"${i.new_priority ? ` and priority to "${i.new_priority}"` : ""}${i.note ? `. Add note: "${i.note}"` : ""}. Confirm what was updated.`;
+
+async function executeCreateItem(agentRoot, input) {
+  return executeLookup("create_item_internal", input, agentRoot);
+}
+
+LOOKUP_PROMPTS.create_item_internal = (i) =>
+  `Create a new item in state/queues/${i.queue || "action-stack"}.yaml with title "${i.title}", priority "${i.priority || "high"}"${i.due_date ? `, due ${i.due_date}` : ""}${i.owner ? `, owner: ${i.owner}` : ""}${i.context ? `, context: "${i.context}"` : ""}. Use the existing YAML format. Confirm what was created.`;
+
+async function executeGenerateMemo(agentRoot, input) {
+  const draftsDir = path.join(agentRoot, "outputs/drafts");
+  fs.mkdirSync(draftsDir, { recursive: true });
+
+  const slug = input.title.replace(/[^a-zA-Z0-9]/g, "-").toLowerCase().slice(0, 40);
+  const filePath = path.join(draftsDir, `${new Date().toISOString().split("T")[0]}-${slug}.md`);
+  fs.writeFileSync(filePath, `# ${input.title}\n\n${input.content}\n`);
+
+  return { success: true, result: `Memo saved to ${filePath}` };
+}

package/lib/index.js

@@ -0,0 +1,16 @@
+/**
+ * @adaptic/maestro — Main entry point
+ *
+ * Re-exports all public modules for convenient consumption:
+ *   import { getToolsForAccessLevel, executeAction } from "@adaptic/maestro";
+ */
+
+export {
+  getToolsForAccessLevel,
+  getToolNamesForAccessLevel,
+  getAllToolsByCategory,
+} from "./tool-definitions.js";
+
+export { executeAction } from "./action-executor.js";
+
+export { acquireLock, releaseLock, checkLock } from "./singleton.js";

package/lib/singleton.js

@@ -0,0 +1,116 @@
+/**
+ * Maestro — Process Singleton Guard
+ *
+ * Prevents duplicate instances of long-running services (daemon, events
+ * server, huddle server, etc.). Uses PID files with stale detection.
+ *
+ * Usage:
+ *   import { acquireLock, releaseLock } from "@adaptic/maestro/lib/singleton.js";
+ *
+ *   // At startup:
+ *   if (!acquireLock("slack-events")) {
+ *     console.log("Already running — exiting");
+ *     process.exit(0);
+ *   }
+ *
+ *   // On shutdown:
+ *   process.on("SIGTERM", () => { releaseLock("slack-events"); process.exit(0); });
+ *
+ * @module singleton
+ */
+
+import { writeFileSync, readFileSync, unlinkSync, existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { execSync } from "node:child_process";
+
+const AGENT_ROOT = process.env.AGENT_ROOT || process.cwd();
+const LOCKS_DIR = join(AGENT_ROOT, "state", "locks", "process");
+
+/**
+ * Attempt to acquire a singleton lock for a named service.
+ * Returns true if the lock was acquired (no other instance running).
+ * Returns false if another instance is already running.
+ *
+ * Handles stale PID files (process died without cleanup).
+ *
+ * @param {string} name - Service name (e.g., "slack-events", "daemon", "huddle-server")
+ * @returns {boolean}
+ */
+export function acquireLock(name) {
+  mkdirSync(LOCKS_DIR, { recursive: true });
+  const pidFile = join(LOCKS_DIR, `${name}.pid`);
+
+  // Check for existing lock
+  if (existsSync(pidFile)) {
+    try {
+      const existingPid = parseInt(readFileSync(pidFile, "utf8").trim(), 10);
+      if (existingPid && isProcessRunning(existingPid)) {
+        // Another instance is genuinely running
+        return false;
+      }
+      // Stale PID file — process is dead, clean up
+      unlinkSync(pidFile);
+    } catch {
+      // Corrupt PID file — remove it
+      try { unlinkSync(pidFile); } catch { /* ignore */ }
+    }
+  }
+
+  // Write our PID
+  writeFileSync(pidFile, String(process.pid));
+
+  // Register cleanup on exit
+  const cleanup = () => {
+    try { unlinkSync(pidFile); } catch { /* ignore */ }
+  };
+  process.on("exit", cleanup);
+  process.on("SIGINT", () => { cleanup(); process.exit(0); });
+  process.on("SIGTERM", () => { cleanup(); process.exit(0); });
+
+  return true;
+}
+
+/**
+ * Manually release a lock.
+ * @param {string} name
+ */
+export function releaseLock(name) {
+  const pidFile = join(LOCKS_DIR, `${name}.pid`);
+  try { unlinkSync(pidFile); } catch { /* ignore */ }
+}
+
+/**
+ * Check if a service is currently running.
+ * @param {string} name
+ * @returns {{ running: boolean, pid: number|null }}
+ */
+export function checkLock(name) {
+  const pidFile = join(LOCKS_DIR, `${name}.pid`);
+  if (!existsSync(pidFile)) return { running: false, pid: null };
+
+  try {
+    const pid = parseInt(readFileSync(pidFile, "utf8").trim(), 10);
+    if (pid && isProcessRunning(pid)) {
+      return { running: true, pid };
+    }
+    // Stale — clean up
+    try { unlinkSync(pidFile); } catch { /* ignore */ }
+    return { running: false, pid: null };
+  } catch {
+    return { running: false, pid: null };
+  }
+}
+
+/**
+ * Check if a PID is still alive.
+ * @param {number} pid
+ * @returns {boolean}
+ */
+function isProcessRunning(pid) {
+  try {
+    process.kill(pid, 0); // Signal 0 = existence check, no actual signal
+    return true;
+  } catch {
+    return false;
+  }
+}