@cohortapp/agent-sdk 2.3.0

package/scripts/setup/lib/install-plist.mjs

@@ -0,0 +1,95 @@
+/**
+ * Maestro — Shared plist installer for setup scripts.
+ *
+ * Renders a template from scripts/local-triggers/templates/<name>.plist.template
+ * into ~/Library/LaunchAgents/ai.maestro.<firstname>-<name>.plist, substituting
+ * {{AGENT_ROOT}}, {{HOME}}, {{USER}}, {{FIRSTNAME}}, {{NODE_BIN}}. Idempotent:
+ * compares the rendered output against the installed file and only writes when
+ * different. Caller is responsible for booting the agent via launchctl
+ * bootstrap/kickstart.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { execFileSync } from "node:child_process";
+
+export function renderTemplate(template, substitutions) {
+  let out = template;
+  for (const [k, v] of Object.entries(substitutions)) {
+    out = out.split(`{{${k}}}`).join(v);
+  }
+  return out;
+}
+
+/**
+ * @param {object} opts
+ * @param {string} opts.templatePath  Absolute path to <name>.plist.template
+ * @param {string} opts.firstname     Agent's first name (lowercased)
+ * @param {string} opts.agentRoot     Absolute path to the agent repo
+ * @param {string} [opts.nodeBin]     Path to node binary; defaults to current node
+ * @param {string} [opts.label]       Override label suffix; defaults to template basename
+ * @returns {{label, installedPath, changed}}
+ */
+export function installPlist({ templatePath, firstname, agentRoot, nodeBin, label }) {
+  if (!existsSync(templatePath)) {
+    throw new Error(`template not found: ${templatePath}`);
+  }
+  const templateBasename = templatePath.split("/").pop().replace(/\.plist\.template$/, "");
+  const lbl = label || templateBasename;
+  const fullLabel = `ai.maestro.${firstname}-${lbl}`;
+  const launchAgentsDir = join(homedir(), "Library", "LaunchAgents");
+  mkdirSync(launchAgentsDir, { recursive: true });
+  const installedPath = join(launchAgentsDir, `${fullLabel}.plist`);
+
+  const tpl = readFileSync(templatePath, "utf-8");
+  const rendered = renderTemplate(tpl, {
+    NODE_BIN: nodeBin || resolveNodeBin(),
+    AGENT_ROOT: agentRoot,
+    HOME: homedir(),
+    USER: process.env.USER || process.env.LOGNAME || "unknown",
+    FIRSTNAME: firstname,
+  });
+  const unfilled = rendered.match(/\{\{[A-Z_]+\}\}/g);
+  if (unfilled) {
+    throw new Error(`template ${templatePath} has un-substituted placeholders: ${unfilled.join(", ")}`);
+  }
+
+  let changed = true;
+  if (existsSync(installedPath)) {
+    const existing = readFileSync(installedPath, "utf-8");
+    if (existing === rendered) changed = false;
+  }
+  if (changed) {
+    mkdirSync(dirname(installedPath), { recursive: true });
+    writeFileSync(installedPath, rendered);
+  }
+  return { label: fullLabel, installedPath, changed };
+}
+
+/**
+ * Load the installed plist into launchd and start the agent. Safe to call when
+ * the agent is already loaded — performs bootout (suppressing errors if the
+ * agent wasn't loaded) before bootstrap.
+ */
+export function bootInLaunchd(installedPath) {
+  const uid = process.getuid();
+  const domain = `gui/${uid}`;
+  try {
+    execFileSync("launchctl", ["bootout", domain, installedPath], { stdio: "ignore" });
+  } catch { /* not currently loaded — fine */ }
+  execFileSync("launchctl", ["bootstrap", domain, installedPath], { stdio: "inherit" });
+}
+
+function resolveNodeBin() {
+  try {
+    const which = execFileSync("which", ["node"], { encoding: "utf-8" }).trim();
+    if (which) {
+      try {
+        const real = execFileSync("readlink", ["-f", which], { encoding: "utf-8" }).trim();
+        if (real) return real;
+      } catch { /* fall through */ }
+      return which;
+    }
+  } catch { /* fall through */ }
+  return process.argv[0];
+}

package/scripts/setup/migrate-agent-to-sot.mjs

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+/**
+ * migrate-agent-to-sot.mjs — Migrate an existing maestro agent repo to the
+ * Source-of-Truth layout (`config/agent.json` canonical + `config/agent.ts`
+ * thin wrapper + `config/agent.env` generated).
+ *
+ * Before:
+ *   config/agent.ts  ← contains inline `export const agent = { firstName: "Ravi", ... }`
+ *
+ * After:
+ *   config/agent.json  ← canonical data extracted from agent.ts
+ *   config/agent.ts    ← thin wrapper that imports agent.json + provides types
+ *   config/agent.env   ← generated for shell scripts
+ *
+ * Run from inside an agent repo:
+ *   npx tsx scripts/setup/migrate-agent-to-sot.mjs
+ *
+ * Requires `tsx` in the agent's devDependencies (it is — the scaffold sets it).
+ *
+ * Safety:
+ *   - Backs up the existing config/agent.ts to config/agent.ts.bak
+ *   - Refuses to run if config/agent.json already exists
+ *   - Refuses to run if config/agent.ts can't be imported
+ */
+
+import { readFileSync, writeFileSync, copyFileSync, existsSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { execFileSync } from "node:child_process";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const AGENT_DIR = process.env.AGENT_DIR || resolve(__dirname, "../..");
+const TS_PATH = resolve(AGENT_DIR, "config/agent.ts");
+const JSON_PATH = resolve(AGENT_DIR, "config/agent.json");
+const BAK_PATH = resolve(AGENT_DIR, "config/agent.ts.pre-sot-migration.bak");
+
+if (!existsSync(TS_PATH)) {
+  console.error(`[migrate] config/agent.ts not found at ${TS_PATH}`);
+  process.exit(1);
+}
+
+if (existsSync(JSON_PATH)) {
+  console.error(`[migrate] config/agent.json already exists — already migrated?`);
+  console.error(`[migrate] Delete it manually if you want to re-run.`);
+  process.exit(1);
+}
+
+// Use tsx to load the existing TS module. This is the most reliable way to
+// extract the data without writing a fragile parser.
+let agent;
+try {
+  const tsxBin = execFileSync("npx", ["--yes", "tsx", "-e", "console.log(0)"], {
+    encoding: "utf-8",
+    stdio: ["pipe", "pipe", "ignore"],
+  });
+  // tsx is available — load via inline eval.
+  const json = execFileSync(
+    "npx",
+    [
+      "--yes",
+      "tsx",
+      "-e",
+      `import("${TS_PATH}").then(m => { console.log(JSON.stringify(m.agent)); }).catch(e => { console.error(e.message); process.exit(1); });`,
+    ],
+    { encoding: "utf-8" }
+  );
+  agent = JSON.parse(json.trim());
+} catch (e) {
+  console.error(`[migrate] failed to import config/agent.ts: ${e.message}`);
+  console.error(`[migrate] ensure tsx is installed (npm install --save-dev tsx) and agent.ts has a default \`export const agent = ...\``);
+  process.exit(1);
+}
+
+// Sanity check
+if (!agent || typeof agent !== "object" || !agent.firstName) {
+  console.error("[migrate] extracted config doesn't look right (missing firstName)");
+  console.error("[migrate] received:", JSON.stringify(agent).slice(0, 200));
+  process.exit(1);
+}
+
+// Backup
+copyFileSync(TS_PATH, BAK_PATH);
+console.log(`[migrate] backed up agent.ts → ${BAK_PATH}`);
+
+// Write canonical JSON
+writeFileSync(JSON_PATH, JSON.stringify(agent, null, 2) + "\n");
+console.log(`[migrate] wrote config/agent.json (canonical)`);
+
+// Replace agent.ts with thin wrapper template (read from scaffold).
+// The wrapper is shipped alongside this migration script in the maestro
+// package, but we also fall back to writing it inline so the migration
+// works even without access to the scaffold.
+const wrapperTemplate = inlineWrapper();
+writeFileSync(TS_PATH, wrapperTemplate);
+console.log(`[migrate] rewrote config/agent.ts as thin JSON wrapper`);
+
+// Generate agent.env
+try {
+  execFileSync(
+    "node",
+    [resolve(__dirname, "generate-agent-env.mjs")],
+    { encoding: "utf-8", stdio: "inherit" }
+  );
+} catch (e) {
+  console.warn(`[migrate] could not auto-generate agent.env: ${e.message}`);
+  console.warn(`[migrate] run manually: node scripts/setup/generate-agent-env.mjs`);
+}
+
+console.log();
+console.log("[migrate] ✓ migration complete");
+console.log(`[migrate]   config/agent.json    canonical identity data`);
+console.log(`[migrate]   config/agent.ts      thin TS wrapper (imports agent.json)`);
+console.log(`[migrate]   config/agent.env     shell-sourceable identity vars`);
+console.log(`[migrate]   ${BAK_PATH.split("/").slice(-2).join("/")}  original (delete after verifying)`);
+
+function inlineWrapper() {
+  return `/**
+ * Maestro — Agent Configuration (TypeScript wrapper)
+ *
+ * The canonical source of truth is \`config/agent.json\`. Edit that file,
+ * then run \`node scripts/setup/generate-agent-env.mjs\` to regenerate the
+ * shell environment file.
+ *
+ * This wrapper exposes typed access plus a few computed convenience values.
+ */
+
+import agentData from './agent.json' with { type: 'json' };
+
+export interface VoiceMode {
+  id: string;
+  label: string;
+  description: string;
+}
+
+export interface PrincipalConfig {
+  firstName: string;
+  lastName: string;
+  fullName: string;
+  title: string;
+  email: string;
+  slackMemberId: string;
+}
+
+export interface AgentConfig {
+  firstName: string;
+  lastName: string;
+  fullName: string;
+  title: string;
+  archetype: string;
+
+  email: string;
+  phone: string;
+  slackMemberId: string;
+
+  company: string;
+  companyDomain: string;
+  companyDescription: string;
+
+  principal: PrincipalConfig;
+
+  machineName: string;
+  repoSlug: string;
+  launchdLabelPrefix: string;
+
+  timezone: string;
+  locale: string;
+
+  schedule: {
+    morningBrief: string;
+    commsTriage: string[];
+    eveningWrap: string;
+    overnightMonitoring: string;
+  };
+
+  communication: {
+    defaultTone: string;
+    externalTone: string;
+    voiceModes: VoiceMode[];
+  };
+
+  responsibilities: string[];
+  operatingPrinciples: string[];
+}
+
+export const agent: AgentConfig = agentData as AgentConfig;
+
+export const AGENT_UPPER = agent.firstName.toUpperCase();
+export const AGENT_LOWER = agent.firstName.toLowerCase();
+export const REPO_DIR = \`~/\${agent.repoSlug}\`;
+export const EMAIL_SIGNATURE = \`\${agent.fullName} | \${agent.title} | \${agent.company}\`;
+`;
+}

package/scripts/setup/render-environment-yaml.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+/**
+ * render-environment-yaml.mjs
+ *
+ * Derive `config/environment.yaml` from `config/agent.json` (the SOT).
+ * Replaces the previously-static, agent-name-hardcoded environment.yaml so
+ * that operator_persona / operator_role / ceo / hostname / paths / agent
+ * blocks always reflect what agent.json says.
+ *
+ * Called by `maestro upgrade` (post-merge) and safe to run by hand:
+ *
+ *   node scripts/setup/render-environment-yaml.mjs               # write
+ *   node scripts/setup/render-environment-yaml.mjs --dry-run     # preview
+ *   node scripts/setup/render-environment-yaml.mjs --check       # exit 1 if drift
+ *
+ * Output is canonical (deterministic). If the existing file already matches,
+ * nothing is written. The first 5 lines of the rendered file always include
+ * a `# regenerated-from: config/agent.json` banner so operators editing it
+ * directly know they're editing a derived file.
+ */
+
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { resolve, join } from "node:path";
+
+const AGENT_DIR = process.env.AGENT_ROOT || process.env.AGENT_DIR || process.cwd();
+const AGENT_JSON = join(AGENT_DIR, "config", "agent.json");
+const TARGET = join(AGENT_DIR, "config", "environment.yaml");
+
+function fail(msg) {
+  process.stderr.write(`[render-environment-yaml] ${msg}\n`);
+  process.exit(1);
+}
+
+if (!existsSync(AGENT_JSON)) {
+  fail(`config/agent.json not found at ${AGENT_JSON} — nothing to derive from.`);
+}
+
+let agent;
+try {
+  agent = JSON.parse(readFileSync(AGENT_JSON, "utf-8"));
+} catch (err) {
+  fail(`failed to parse agent.json: ${err.message}`);
+}
+
+// Render a stable, predictable YAML. We don't use a YAML library to keep
+// this script dep-free and to control the exact formatting & comment
+// placement. Mind the trailing newline on every value.
+function quote(s) {
+  if (typeof s !== "string") return `"${s ?? ""}"`;
+  // No double-quotes in agent identity strings expected; if any appear,
+  // escape them properly.
+  return `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+
+function yamlValue(v) {
+  if (v === null || v === undefined) return '""';
+  if (typeof v === "number" || typeof v === "boolean") return String(v);
+  return quote(String(v));
+}
+
+function render(agent) {
+  const repoSlug = agent.repoSlug || `${(agent.firstName || "agent").toLowerCase()}-ai`;
+  const home = `~/${repoSlug}`;
+  const lines = [
+    "# Environment Configuration",
+    "# regenerated-from: config/agent.json by scripts/setup/render-environment-yaml.mjs",
+    "# DO NOT EDIT BY HAND — changes will be overwritten on every upgrade.",
+    "# Edit config/agent.json (the SOT) and re-run the renderer instead.",
+    "",
+    "system:",
+    `  name: maestro`,
+    `  version: 1.0.0`,
+    `  operator_persona: ${yamlValue(agent.fullName)}`,
+    `  operator_role: ${yamlValue(agent.title)}`,
+    `  company: ${yamlValue(agent.company)}`,
+    `  ceo: ${yamlValue(agent.principal?.fullName || "")}`,
+    `  timezone: ${yamlValue(agent.timezone || "UTC")}`,
+    "",
+    "machine:",
+    `  type: mac-mini`,
+    `  os: macOS`,
+    `  hostname: ${yamlValue(agent.machineName || "")}`,
+    `  purpose: Autonomous agent operations node`,
+    "",
+    "paths:",
+    `  agent_home: ${home}`,
+    `  logs: ${home}/logs`,
+    `  outputs: ${home}/outputs`,
+    "",
+    "agent:",
+    `  name: ${yamlValue(agent.fullName)}`,
+    `  email: ${yamlValue(agent.email)}`,
+    `  phone: ${yamlValue(agent.phone || "")}`,
+    "",
+  ];
+  return lines.join("\n");
+}
+
+const rendered = render(agent);
+const args = process.argv.slice(2);
+const dryRun = args.includes("--dry-run") || args.includes("-n");
+const check = args.includes("--check");
+
+if (check) {
+  if (!existsSync(TARGET)) {
+    process.stdout.write("config/environment.yaml missing\n");
+    process.exit(1);
+  }
+  const current = readFileSync(TARGET, "utf-8");
+  if (current === rendered) {
+    process.stdout.write("environment.yaml is up to date with agent.json\n");
+    process.exit(0);
+  }
+  process.stdout.write("environment.yaml drifts from agent.json — rerun the renderer\n");
+  process.exit(1);
+}
+
+if (dryRun) {
+  process.stdout.write(rendered);
+  process.exit(0);
+}
+
+// Skip the write if already up to date — keeps `upgrade` idempotent.
+if (existsSync(TARGET)) {
+  const current = readFileSync(TARGET, "utf-8");
+  if (current === rendered) {
+    process.stdout.write("environment.yaml already up to date\n");
+    process.exit(0);
+  }
+}
+
+writeFileSync(TARGET, rendered);
+process.stdout.write(`environment.yaml regenerated from agent.json (${rendered.split("\n").length} lines)\n`);

package/scripts/slack-events-ctl.sh

@@ -0,0 +1,177 @@
+#!/bin/bash
+# slack-events-ctl.sh — Start/stop/restart the Slack Events API server
+#
+# Usage:
+#   ./scripts/slack-events-ctl.sh start    — Start the server (background)
+#   ./scripts/slack-events-ctl.sh stop     — Stop the server
+#   ./scripts/slack-events-ctl.sh restart  — Restart the server
+#   ./scripts/slack-events-ctl.sh status   — Check if running
+#   ./scripts/slack-events-ctl.sh health   — Query health endpoint
+#   ./scripts/slack-events-ctl.sh logs     — Tail today's log
+#
+set -e
+
+SOPHIE_AI_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+PID_FILE="$SOPHIE_AI_DIR/state/locks/slack-events-server.pid"
+LOG_DIR="$SOPHIE_AI_DIR/logs/polling"
+DATE=$(date +%Y-%m-%d)
+PORT="${SLACK_EVENTS_PORT:-3100}"
+
+# Find node
+if command -v node >/dev/null 2>&1; then
+    NODE_BIN=$(command -v node)
+elif [ -x /opt/homebrew/bin/node ]; then
+    NODE_BIN="/opt/homebrew/bin/node"
+elif [ -x /usr/local/bin/node ]; then
+    NODE_BIN="/usr/local/bin/node"
+else
+    echo "[SLACK-EVENTS] ERROR: node not found"
+    exit 1
+fi
+
+start_server() {
+    # Check if already running
+    if [ -f "$PID_FILE" ]; then
+        PID=$(cat "$PID_FILE")
+        if kill -0 "$PID" 2>/dev/null; then
+            echo "[SLACK-EVENTS] Already running (PID $PID)"
+            return 0
+        else
+            echo "[SLACK-EVENTS] Stale PID file, cleaning up"
+            rm -f "$PID_FILE"
+        fi
+    fi
+
+    # Check if port is in use by something else
+    if lsof -i ":$PORT" -sTCP:LISTEN >/dev/null 2>&1; then
+        EXISTING_PID=$(lsof -i ":$PORT" -sTCP:LISTEN -t 2>/dev/null | head -1)
+        echo "[SLACK-EVENTS] Port $PORT already in use by PID $EXISTING_PID"
+        echo "[SLACK-EVENTS] Stop that process first, or set SLACK_EVENTS_PORT"
+        return 1
+    fi
+
+    mkdir -p "$LOG_DIR" "$(dirname "$PID_FILE")"
+
+    echo "[SLACK-EVENTS] Starting server on port $PORT..."
+    cd "$SOPHIE_AI_DIR"
+
+    # Source .env for environment variables
+    if [ -f "$SOPHIE_AI_DIR/.env" ]; then
+        set -a
+        source "$SOPHIE_AI_DIR/.env"
+        set +a
+    fi
+
+    "$NODE_BIN" "$SOPHIE_AI_DIR/scripts/slack-events-server.mjs" \
+        >> "$LOG_DIR/$DATE-slack-events.log" 2>&1 &
+
+    SERVER_PID=$!
+    echo "$SERVER_PID" > "$PID_FILE"
+
+    # Wait a moment and verify it started
+    sleep 1
+    if kill -0 "$SERVER_PID" 2>/dev/null; then
+        echo "[SLACK-EVENTS] Started (PID $SERVER_PID) on port $PORT"
+    else
+        echo "[SLACK-EVENTS] Failed to start — check $LOG_DIR/$DATE-slack-events.log"
+        rm -f "$PID_FILE"
+        return 1
+    fi
+}
+
+stop_server() {
+    if [ -f "$PID_FILE" ]; then
+        PID=$(cat "$PID_FILE")
+        if kill -0 "$PID" 2>/dev/null; then
+            echo "[SLACK-EVENTS] Stopping (PID $PID)..."
+            kill "$PID"
+            # Wait up to 5 seconds for graceful shutdown
+            for i in $(seq 1 5); do
+                if ! kill -0 "$PID" 2>/dev/null; then
+                    break
+                fi
+                sleep 1
+            done
+            if kill -0 "$PID" 2>/dev/null; then
+                echo "[SLACK-EVENTS] Force killing..."
+                kill -9 "$PID" 2>/dev/null
+            fi
+            echo "[SLACK-EVENTS] Stopped"
+        else
+            echo "[SLACK-EVENTS] Not running (stale PID)"
+        fi
+        rm -f "$PID_FILE"
+    else
+        # Try to find by port
+        PID=$(lsof -i ":$PORT" -sTCP:LISTEN -t 2>/dev/null | head -1)
+        if [ -n "$PID" ]; then
+            echo "[SLACK-EVENTS] Found server on port $PORT (PID $PID), stopping..."
+            kill "$PID"
+            echo "[SLACK-EVENTS] Stopped"
+        else
+            echo "[SLACK-EVENTS] Not running"
+        fi
+    fi
+}
+
+check_status() {
+    if [ -f "$PID_FILE" ]; then
+        PID=$(cat "$PID_FILE")
+        if kill -0 "$PID" 2>/dev/null; then
+            echo "[SLACK-EVENTS] Running (PID $PID) on port $PORT"
+            return 0
+        else
+            echo "[SLACK-EVENTS] Not running (stale PID file)"
+            return 1
+        fi
+    else
+        PID=$(lsof -i ":$PORT" -sTCP:LISTEN -t 2>/dev/null | head -1)
+        if [ -n "$PID" ]; then
+            echo "[SLACK-EVENTS] Running on port $PORT (PID $PID, no PID file)"
+            return 0
+        else
+            echo "[SLACK-EVENTS] Not running"
+            return 1
+        fi
+    fi
+}
+
+check_health() {
+    HEALTH=$(curl -s --max-time 3 "http://localhost:$PORT/health" 2>/dev/null)
+    if [ -n "$HEALTH" ]; then
+        echo "$HEALTH" | python3 -m json.tool 2>/dev/null || echo "$HEALTH"
+    else
+        echo "[SLACK-EVENTS] Health check failed — server not responding on port $PORT"
+        return 1
+    fi
+}
+
+tail_logs() {
+    LOG_FILE="$LOG_DIR/$DATE-slack-events.log"
+    JSONL_FILE="$LOG_DIR/$DATE-slack-events.jsonl"
+    if [ -f "$JSONL_FILE" ]; then
+        echo "=== Structured log ($JSONL_FILE) ==="
+        tail -20 "$JSONL_FILE"
+    fi
+    if [ -f "$LOG_FILE" ]; then
+        echo ""
+        echo "=== Console log ($LOG_FILE) ==="
+        tail -30 "$LOG_FILE"
+    fi
+    if [ ! -f "$LOG_FILE" ] && [ ! -f "$JSONL_FILE" ]; then
+        echo "[SLACK-EVENTS] No logs for today"
+    fi
+}
+
+case "${1:-status}" in
+    start)   start_server ;;
+    stop)    stop_server ;;
+    restart) stop_server; sleep 1; start_server ;;
+    status)  check_status ;;
+    health)  check_health ;;
+    logs)    tail_logs ;;
+    *)
+        echo "Usage: $0 {start|stop|restart|status|health|logs}"
+        exit 1
+        ;;
+esac