@adaptic/maestro 1.10.0 → 1.10.2

package/.env.example

@@ -76,6 +76,15 @@ SLACK_BOT_TOKEN=xoxb-...
 # Found at: https://api.slack.com/apps → Basic Information → Signing Secret
 SLACK_SIGNING_SECRET=
 
+# OPTIONAL — App-level token (starts with xapp-) for Slack Socket Mode.
+# Required when the slack-socket-mode feature is enabled. Generate it at:
+#   https://api.slack.com/apps → your app → "Basic Information" → "App-Level Tokens"
+# Add the scope: connections:write
+# Then also enable Socket Mode and Event Subscriptions (message.channels,
+# message.groups, message.im, message.mpim, app_mention) on the same app.
+# Run `maestro init slack-socket-mode --apply` to walk through the full setup.
+SLACK_APP_LEVEL_TOKEN=
+
 
 # ─── GMAIL ───────────────────────────────────────────────────────────────────
 #

package/bin/maestro.mjs

@@ -20,6 +20,9 @@ import {
   readdirSync,
   statSync,
   lstatSync,
+  openSync,
+  readSync,
+  closeSync,
 } from "node:fs";
 import { execFileSync, spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
@@ -1499,6 +1502,95 @@ function doctor() {
     } else if (preferSubs) {
       ok("MAESTRO_PREFER_SUBSCRIPTION_AUTH=1 — using Claude Code subscription (Keychain OAuth)");
     }
+
+    // ── Slack Socket Mode ────────────────────────────────────────────────
+    // When SLACK_APP_LEVEL_TOKEN is set, verify the launchd job is loaded
+    // and the listener has connected recently. The check is fully optional:
+    // the framework still works with the legacy 60s poller if the operator
+    // hasn't enabled Socket Mode yet.
+    const socketTokenMatch = env.match(/^SLACK_APP_LEVEL_TOKEN=(.+)$/m);
+    const socketToken = socketTokenMatch ? socketTokenMatch[1].trim().replace(/^["']|["']$/g, "") : "";
+    if (socketToken && socketToken.startsWith("xapp-")) {
+      ok("SLACK_APP_LEVEL_TOKEN configured (Socket Mode candidate)");
+
+      // Resolve the agent's first name the same way generate-plists.sh does
+      // so the label matches whatever is installed in ~/Library/LaunchAgents/.
+      let firstName = "";
+      try {
+        const aj = JSON.parse(readFileSync(join(cwd, "config/agent.json"), "utf-8"));
+        if (aj.firstName) firstName = String(aj.firstName).toLowerCase();
+      } catch { /* fall back */ }
+      if (!firstName) firstName = cwd.split("/").pop().replace(/-ai$/, "").toLowerCase();
+      const socketLabel = `ai.adaptic.${firstName}-slack-socket`;
+
+      // Is the plist installed at ~/Library/LaunchAgents/?
+      const installedDir = join(process.env.HOME || "/", "Library/LaunchAgents");
+      const installedPath = join(installedDir, `${socketLabel}.plist`);
+      if (existsSync(installedPath)) {
+        // Is it actually loaded? launchctl list returns 0 when the label exists.
+        const listRes = spawnSync("launchctl", ["list", socketLabel], { encoding: "utf-8" });
+        if (listRes.status === 0) ok(`launchd job loaded: ${socketLabel}`);
+        else {
+          warn(`Plist installed but launchd job not loaded: ${socketLabel}`);
+          warn(`  Fix: launchctl load ${installedPath}`);
+          issues++;
+        }
+      } else {
+        warn(`SLACK_APP_LEVEL_TOKEN set but ${installedPath} missing.`);
+        warn("  Run: node scripts/setup/init-slack-socket-mode.mjs");
+        issues++;
+      }
+
+      // Did the listener log a `hello` envelope recently? The log lives at
+      // logs/polling/<today>-slack-socket.jsonl — scan the last few lines
+      // for a fresh "hello" or "inbox-item-written" entry.
+      const today = new Date().toISOString().slice(0, 10);
+      const yesterday = new Date(Date.now() - 86400000).toISOString().slice(0, 10);
+      let foundRecent = false;
+      let latestTs = null;
+      for (const day of [today, yesterday]) {
+        const logPath = join(cwd, "logs/polling", `${day}-slack-socket.jsonl`);
+        if (!existsSync(logPath)) continue;
+        // Read the tail (last 50KB) to avoid loading huge files.
+        try {
+          const stat = statSync(logPath);
+          const buf = Buffer.alloc(Math.min(stat.size, 50_000));
+          const fd = openSync(logPath, "r");
+          try {
+            const start = Math.max(0, stat.size - buf.length);
+            readSync(fd, buf, 0, buf.length, start);
+          } finally { closeSync(fd); }
+          const tail = buf.toString("utf-8");
+          for (const line of tail.split("\n").reverse()) {
+            if (!line) continue;
+            try {
+              const entry = JSON.parse(line);
+              if (entry.message === "hello — connected to Slack Socket Mode" ||
+                  entry.message === "inbox-item-written" ||
+                  entry.message === "starting Socket Mode listener") {
+                latestTs = entry.ts;
+                const ageMs = Date.now() - new Date(entry.ts).getTime();
+                if (ageMs >= 0 && ageMs < 60 * 60_000) foundRecent = true;
+                break;
+              }
+            } catch { /* malformed line — skip */ }
+          }
+          if (latestTs) break;
+        } catch { /* unreadable log — skip */ }
+      }
+      if (foundRecent) {
+        const ageMin = Math.round((Date.now() - new Date(latestTs).getTime()) / 60_000);
+        ok(`Socket Mode listener was active ${ageMin}m ago`);
+      } else if (latestTs) {
+        const ageMin = Math.round((Date.now() - new Date(latestTs).getTime()) / 60_000);
+        warn(`Socket Mode last connect ${ageMin}m ago — may be stalled`);
+        issues++;
+      } else {
+        warn("Socket Mode listener has not produced a connect log yet.");
+        warn("  Check: tail -f logs/polling/$(date +%Y-%m-%d)-slack-socket.jsonl");
+        issues++;
+      }
+    }
   } else {
     fail(".env file not found — copy from .env.example");
     issues++;

package/framework-features.json

@@ -102,6 +102,16 @@
         "command": "node scripts/setup/init-backup.mjs",
         "description": "Configure off-machine backup of state/, knowledge/, outputs/, and rotated logs to GCS or S3. Requires bucket name + credentials. Doctor flags if last successful backup is >24h old once configured."
       }
+    },
+    "slack-socket-mode": {
+      "version": "1",
+      "since": "1.10.0",
+      "title": "Slack Socket Mode (realtime DM + @mention ingestion)",
+      "init": {
+        "auto": false,
+        "command": "node scripts/setup/init-slack-socket-mode.mjs",
+        "description": "Replace the 60s slack-poller cycle with a persistent WebSocket to Slack. Three steps in the Slack admin UI: (1) open the agent's Slack app at api.slack.com/apps; (2) enable Socket Mode and generate an app-level token (xapp-…) with the connections:write scope; (3) enable Event Subscriptions and subscribe to message.channels, message.groups, message.im, message.mpim, and app_mention. The init wizard prompts for the token, appends it to .env, regenerates the launchd plist, and launchctl-loads it. Doctor verifies the token is present, the plist is loaded, and the listener recently connected."
+      }
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adaptic/maestro",
-  "version": "1.10.0",
+  "version": "1.10.2",
   "description": "Maestro — Autonomous AI agent operating system. Deploy AI employees on dedicated Mac minis.",
   "type": "module",
   "bin": {

package/scripts/cadence/launchd-socket-mode-wrapper.sh

@@ -0,0 +1,95 @@
+#!/bin/bash
+# launchd-socket-mode-wrapper.sh — Bootstraps env for slack-socket-mode.mjs
+# under launchd.
+#
+# Mirrors launchd-wrapper.sh exactly: launchd's bare env doesn't include
+# HOME, PATH, or AGENT_ROOT, so we hydrate them before exec'ing the
+# Socket Mode listener. Logs land on the external SSD when available
+# (same fallback semantics as the main daemon wrapper).
+#
+# This wrapper is exec'd by ai.adaptic.{firstname}-slack-socket.plist.
+
+set -e
+
+AGENT_ROOT="$(cd "$(dirname "$0")/../.." && pwd -P)"
+export AGENT_ROOT
+export HOME="${HOME:-/Users/$(whoami)}"
+export USER="${USER:-$(whoami)}"
+export PATH="/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:$PATH"
+
+# ── SSD redirect ────────────────────────────────────────────────────────────
+# If an external SSD is mounted at /Volumes/{name}, redirect:
+#   - Claude Code per-cwd temp (CLAUDE_CODE_TMPDIR)
+#   - Listener stdout/stderr (via shell redirection at exec time)
+#
+# Detection mirrors launchd-wrapper.sh — first volume under /Volumes that's
+# not a system mount; MAESTRO_SSD_VOLUME env var overrides if multiple SSDs.
+
+SSD_VOLUME="${MAESTRO_SSD_VOLUME:-}"
+if [ -z "$SSD_VOLUME" ]; then
+  for v in /Volumes/*-SSD /Volumes/*SSD* /Volumes/maestro-data; do
+    if [ -d "$v" ] && [ "$v" != "/Volumes/Macintosh HD" ]; then
+      SSD_VOLUME="$v"
+      break
+    fi
+  done
+fi
+
+AGENT_NAME="$(basename "$AGENT_ROOT" | sed 's/-ai$//')"
+SSD_AGENT_ROOT=""
+SSD_WRITABLE=0
+if [ -n "$SSD_VOLUME" ] && [ -d "$SSD_VOLUME" ]; then
+  SSD_AGENT_ROOT="$SSD_VOLUME/maestro/$AGENT_NAME"
+  if mkdir -p "$SSD_AGENT_ROOT/claude-tmp" "$SSD_AGENT_ROOT/logs/slack-socket" 2>/dev/null && \
+     touch "$SSD_AGENT_ROOT/.write-test-$$" 2>/dev/null; then
+    rm -f "$SSD_AGENT_ROOT/.write-test-$$"
+    SSD_WRITABLE=1
+    export CLAUDE_CODE_TMPDIR="$SSD_AGENT_ROOT/claude-tmp"
+  fi
+fi
+
+cd "$AGENT_ROOT"
+
+# Resolve node binary — prefer nvm, fall back to homebrew, then system.
+NODE_BIN=""
+for candidate in \
+  "$HOME/.nvm/versions/node/v24.11.1/bin/node" \
+  "$HOME/.nvm/versions/node/v24/bin/node" \
+  "$HOME/.nvm/versions/node/v22/bin/node" \
+  "$HOME/.nvm/versions/node/v20/bin/node" \
+  /opt/homebrew/bin/node \
+  /usr/local/bin/node \
+  /usr/bin/node; do
+  if [ -x "$candidate" ]; then
+    NODE_BIN="$candidate"
+    break
+  fi
+done
+if [ -z "$NODE_BIN" ] && [ -d "$HOME/.nvm/versions/node" ]; then
+  NODE_BIN=$(ls -1d "$HOME/.nvm/versions/node"/v*/bin/node 2>/dev/null | sort -V | tail -1)
+fi
+if [ -z "$NODE_BIN" ] || [ ! -x "$NODE_BIN" ]; then
+  echo "[slack-socket-wrapper] FATAL: could not find node binary" >&2
+  exit 127
+fi
+
+# Node 22.4+ is required for the global WebSocket. Warn (don't fail) on
+# older versions — the user might have polyfilled via `--experimental-websocket`
+# or installed the `ws` package as a fallback.
+NODE_VERSION="$("$NODE_BIN" --version 2>/dev/null || echo 'v0.0.0')"
+NODE_MAJOR="$(echo "$NODE_VERSION" | sed -E 's/^v([0-9]+).*/\1/')"
+if [ "$NODE_MAJOR" -lt 22 ] 2>/dev/null; then
+  echo "[slack-socket-wrapper] WARNING: Node $NODE_VERSION is older than v22 — global WebSocket may be missing." >&2
+fi
+
+# Exec the listener. Prefer SSD log path if writable, otherwise fall back
+# to internal disk so the listener stays up even when macOS denies launchd
+# write access to /Volumes/{name}.
+if [ "$SSD_WRITABLE" = "1" ]; then
+  LISTENER_LOG="$SSD_AGENT_ROOT/logs/slack-socket/listener-$(date +%Y-%m-%d).log"
+  exec "$NODE_BIN" "$AGENT_ROOT/scripts/poller/slack-socket-mode.mjs" >> "$LISTENER_LOG" 2>&1
+else
+  LISTENER_LOG="$AGENT_ROOT/logs/polling/slack-socket-$(date +%Y-%m-%d).log"
+  mkdir -p "$(dirname "$LISTENER_LOG")" 2>/dev/null || true
+  exec "$NODE_BIN" "$AGENT_ROOT/scripts/poller/slack-socket-mode.mjs" >> "$LISTENER_LOG" 2>&1
+fi

package/scripts/healthcheck.sh

@@ -23,15 +23,21 @@ else
     echo "[OK]   No emergency stop flag"
 fi
 
-# Check 2: Required environment variables
-for var in ANTHROPIC_API_KEY; do
-    if [ -z "${!var}" ]; then
-        echo "[FAIL] Missing environment variable: $var"
-        ERRORS=$((ERRORS + 1))
-    else
-        echo "[OK]   Environment variable: $var"
-    fi
-done
+# Check 2: Anthropic auth — either ANTHROPIC_API_KEY set OR subscription
+# auth enabled. Daemons launched under launchd don't inherit the agent's
+# shell env, so a "missing" ANTHROPIC_API_KEY is normal when the operator
+# opted into Claude Code subscription auth (MAESTRO_PREFER_SUBSCRIPTION_AUTH=1
+# in .env strips the var and falls back to Keychain OAuth).
+if [ -n "${ANTHROPIC_API_KEY:-}" ]; then
+    echo "[OK]   Environment variable: ANTHROPIC_API_KEY"
+elif [ -f "$SOPHIE_AI_DIR/.env" ] && grep -qE "^MAESTRO_PREFER_SUBSCRIPTION_AUTH=(1|true|yes)$" "$SOPHIE_AI_DIR/.env"; then
+    echo "[OK]   Anthropic auth: subscription mode (.env: MAESTRO_PREFER_SUBSCRIPTION_AUTH=1)"
+elif [ -f "$SOPHIE_AI_DIR/.env" ] && grep -qE "^ANTHROPIC_API_KEY=." "$SOPHIE_AI_DIR/.env"; then
+    echo "[OK]   Anthropic auth: ANTHROPIC_API_KEY in .env"
+else
+    echo "[FAIL] Anthropic auth not configured (.env needs either ANTHROPIC_API_KEY or MAESTRO_PREFER_SUBSCRIPTION_AUTH=1)"
+    ERRORS=$((ERRORS + 1))
+fi
 
 # Check 3: Key directories exist and are writable
 for dir in logs outputs knowledge/memory config; do

package/scripts/local-triggers/generate-plists.sh

@@ -261,6 +261,21 @@ generate_plist "ai.adaptic.${AGENT_FIRST}-poll-relay" \
     "${AGENT_DIR}/scripts/daemon/launchd-wrapper-generic.sh|${AGENT_DIR}/scripts/poll-slack-events.sh" \
     "" "5" ""
 
+# 2b. Slack Socket Mode listener (persistent WebSocket — KeepAlive).
+#     Replaces the 60s slack-poller cycle for DMs + @mentions with a
+#     realtime WSS connection to Slack. Requires SLACK_APP_LEVEL_TOKEN
+#     in .env (the operator generates this via api.slack.com → App-Level
+#     Tokens with connections:write scope). The wrapper at
+#     scripts/cadence/launchd-socket-mode-wrapper.sh bootstraps env +
+#     execs scripts/poller/slack-socket-mode.mjs.
+#
+#     KeepAlive uses the same SuccessfulExit:false / Crashed:true semantics
+#     as the daemon plist so .emergency-stop (clean exit 0) refuses to
+#     restart, but unexpected crashes do trigger a restart treadmill.
+generate_plist "ai.adaptic.${AGENT_FIRST}-slack-socket" \
+    "${AGENT_DIR}/scripts/cadence/launchd-socket-mode-wrapper.sh" \
+    "" "" "true"
+
 # 3. Inbox processor (every 5 minutes)
 generate_trigger_plist "inbox-processor" "" "300"
 

package/scripts/local-triggers/generate-plists.test.mjs

@@ -56,6 +56,10 @@ async function makeAgent(firstName) {
     join(MAESTRO_ROOT, "scripts/cadence/launchd-cadence-wrapper.sh"),
     join(root, "scripts/cadence/launchd-cadence-wrapper.sh"),
   );
+  copyFileSync(
+    join(MAESTRO_ROOT, "scripts/cadence/launchd-socket-mode-wrapper.sh"),
+    join(root, "scripts/cadence/launchd-socket-mode-wrapper.sh"),
+  );
   copyFileSync(
     join(MAESTRO_ROOT, "scripts/cadence/enqueue-cadence-tick.mjs"),
     join(root, "scripts/cadence/enqueue-cadence-tick.mjs"),
@@ -68,6 +72,7 @@ async function makeAgent(firstName) {
     "scripts/daemon/launchd-wrapper.sh",
     "scripts/daemon/launchd-wrapper-generic.sh",
     "scripts/cadence/launchd-cadence-wrapper.sh",
+    "scripts/cadence/launchd-socket-mode-wrapper.sh",
   ]) {
     await fsp.chmod(join(root, p), 0o755);
   }
@@ -95,9 +100,9 @@ function listPlists(agentRoot) {
 // Tests
 // ---------------------------------------------------------------------------
 
-test("generator emits 15 plists with the agent's first name", async () => {
-  // Inventory (as of cadence-bus v1):
-  //   daemon, poll-relay,
+test("generator emits 16 plists with the agent's first name", async () => {
+  // Inventory (as of cadence-bus v1 + slack-socket-mode v1):
+  //   daemon, poll-relay, slack-socket,
   //   inbox-processor, backlog-executor, meeting-prep, meeting-action-capture,
   //   daily-morning-brief, daily-midday-sweep, daily-evening-wrap,
   //   weekly-hiring, weekly-priorities, weekly-execution,
@@ -108,7 +113,7 @@ test("generator emits 15 plists with the agent's first name", async () => {
     const r = runGenerator(root);
     assert.equal(r.status, 0, r.stderr);
     const plists = listPlists(root);
-    assert.equal(plists.length, 15);
+    assert.equal(plists.length, 16);
     for (const p of plists) {
       assert.match(p, /^ai\.adaptic\.alice-/);
     }
@@ -134,9 +139,12 @@ test("NO trigger plist invokes run-trigger.sh", async () => {
     const dir = join(root, "scripts/local-triggers/plists");
     for (const name of listPlists(root)) {
       const body = readFileSync(join(dir, name), "utf-8");
-      // Exception: the daemon/poll-relay plists don't run triggers at all.
-      // The trigger plists must invoke enqueue-cadence-tick.mjs.
-      if (name.endsWith("-daemon.plist") || name.endsWith("-poll-relay.plist")) {
+      // Exception: the daemon/poll-relay/slack-socket plists don't run cadence
+      // triggers at all (the first two are KeepAlive workers; slack-socket is
+      // a KeepAlive WSS listener). The trigger plists must invoke
+      // enqueue-cadence-tick.mjs.
+      if (name.endsWith("-daemon.plist") || name.endsWith("-poll-relay.plist") ||
+          name.endsWith("-slack-socket.plist")) {
         continue;
       }
       assert.ok(!body.includes("run-trigger.sh"),
@@ -229,6 +237,10 @@ export interface AgentConfig { firstName: string; }
     join(MAESTRO_ROOT, "scripts/cadence/launchd-cadence-wrapper.sh"),
     join(root, "scripts/cadence/launchd-cadence-wrapper.sh"),
   );
+  copyFileSync(
+    join(MAESTRO_ROOT, "scripts/cadence/launchd-socket-mode-wrapper.sh"),
+    join(root, "scripts/cadence/launchd-socket-mode-wrapper.sh"),
+  );
   copyFileSync(
     join(MAESTRO_ROOT, "scripts/cadence/enqueue-cadence-tick.mjs"),
     join(root, "scripts/cadence/enqueue-cadence-tick.mjs"),