@stackmemoryai/stackmemory 1.12.0 → 1.14.0

package/dist/src/features/operator/overnight-runner.js

@@ -0,0 +1,327 @@
+import { fileURLToPath as __fileURLToPath } from 'url';
+import { dirname as __pathDirname } from 'path';
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __pathDirname(__filename);
+import { existsSync, unlinkSync } from "fs";
+import { execSync } from "child_process";
+import { join } from "path";
+import { homedir } from "os";
+import {
+  detectState,
+  decideAction,
+  detectCompletion
+} from "./state-machine.js";
+import { TaskQueue } from "./task-queue.js";
+import { SessionManager } from "./session-manager.js";
+import { OperatorLogger } from "./operator-logger.js";
+import {
+  classifyScreenState,
+  generateNudge
+} from "./llm-decision.js";
+const STOP_SIGNAL_DIR = join(homedir(), ".stackmemory", "operator");
+const STOP_SIGNAL_FILE = join(STOP_SIGNAL_DIR, "stop-signal");
+class OvernightRunner {
+  queue;
+  session;
+  logger;
+  config;
+  adapter;
+  llmConfig;
+  checkpoint;
+  lastScreen = "";
+  lastChangeAt = Date.now();
+  stopped = false;
+  constructor(config) {
+    this.config = config;
+    this.queue = new TaskQueue(config.taskFilePath);
+    this.session = new SessionManager({
+      sessionName: config.sessionName,
+      cwd: config.cwd,
+      model: config.model
+    });
+    this.logger = new OperatorLogger(config.logDir, STOP_SIGNAL_DIR);
+    this.llmConfig = config.anthropicApiKey ? { apiKey: config.anthropicApiKey, model: config.llmModel } : void 0;
+    this.checkpoint = this.freshCheckpoint();
+  }
+  /** Main entry point — runs until queue drained or stopped */
+  async run() {
+    this.session.preflight();
+    if (this.queue.isEmpty()) {
+      process.stderr.write(
+        "[operator] No actionable tasks in queue. Nothing to do.\n"
+      );
+      return;
+    }
+    const onSignal = () => {
+      this.stopped = true;
+    };
+    process.on("SIGINT", onSignal);
+    process.on("SIGTERM", onSignal);
+    this.logger.logEvent("start", {
+      taskFile: this.config.taskFilePath,
+      cwd: this.config.cwd,
+      session: this.config.sessionName,
+      tasksRemaining: this.queue.remaining()
+    });
+    try {
+      this.adapter = this.session.start();
+      this.lastChangeAt = Date.now();
+      while (!this.stopped) {
+        await this.tick();
+        if (existsSync(STOP_SIGNAL_FILE)) {
+          this.logger.logEvent("shutdown", { reason: "stop signal" });
+          try {
+            unlinkSync(STOP_SIGNAL_FILE);
+          } catch {
+          }
+          this.stopped = true;
+          break;
+        }
+        if (!this.checkpoint.currentTaskId && this.queue.isEmpty()) {
+          this.logger.logEvent("queue_drained");
+          break;
+        }
+        await this.sleep(this.config.pollIntervalMs);
+      }
+    } finally {
+      this.session.stop();
+      process.off("SIGINT", onSignal);
+      process.off("SIGTERM", onSignal);
+      this.logger.printSummary({
+        totalRuntimeMs: Date.now() - this.checkpoint.startedAt,
+        tasksCompleted: this.checkpoint.tasksCompleted.length,
+        tasksBlocked: this.checkpoint.tasksBlocked.length,
+        tasksRemaining: this.queue.remaining(),
+        totalRestarts: this.checkpoint.totalRestarts,
+        totalPermissionApprovals: this.checkpoint.totalPermissionApprovals,
+        totalRateLimitHits: this.checkpoint.totalRateLimitHits
+      });
+    }
+  }
+  // ── Tick ─────────────────────────────────────────────
+  async tick() {
+    if (!this.adapter) return;
+    const screen = this.adapter.readScreen();
+    if (screen !== this.lastScreen) {
+      this.lastChangeAt = Date.now();
+      this.lastScreen = screen;
+    }
+    const detection = detectState(
+      screen,
+      this.checkpoint.currentState,
+      this.lastChangeAt,
+      this.config.stuckTimeoutMs
+    );
+    if (detection.state === "IDLE" && this.checkpoint.currentTaskId) {
+      const completion = detectCompletion(screen);
+      if (completion.completed) {
+        this.handleTaskComplete(this.checkpoint.currentTaskId);
+        return;
+      }
+      if (completion.blocked) {
+        this.handleTaskBlocked(
+          this.checkpoint.currentTaskId,
+          completion.blockedReason ?? "unknown"
+        );
+        return;
+      }
+    }
+    if (detection.state === "UNKNOWN" && this.llmConfig) {
+      const screenshot = this.adapter.readScreenshot?.();
+      const llmResult = await classifyScreenState(
+        screenshot ?? screen,
+        this.llmConfig
+      );
+      if (llmResult.state !== "UNKNOWN") {
+        detection.state = llmResult.state;
+        detection.confidence = llmResult.confidence;
+        detection.detail = `llm: ${llmResult.detail}`;
+      }
+    }
+    if (detection.state === "STUCK" && this.llmConfig && this.checkpoint.currentTaskId) {
+      const taskContent = this.queue.dequeue();
+      const nudge = await generateNudge(
+        screen,
+        taskContent?.task ?? this.checkpoint.currentTaskId,
+        this.llmConfig
+      );
+      if (nudge) {
+        this.adapter.sendInput(nudge);
+        this.lastChangeAt = Date.now();
+        this.logger.logEvent("stuck_detected", { action: "nudge", nudge });
+        return;
+      }
+    }
+    const nextTask = this.checkpoint.currentTaskId ? void 0 : this.queue.dequeue();
+    const action = decideAction(detection, this.checkpoint, nextTask);
+    this.logger.logTick({
+      state: detection.state,
+      confidence: detection.confidence,
+      action: action.type,
+      currentTask: this.checkpoint.currentTaskId ?? void 0,
+      screenSnippet: screen.slice(-200)
+    });
+    this.executeAction(action);
+    this.checkpoint.currentState = detection.state;
+    this.checkpoint.lastTickAt = Date.now();
+    this.logger.writeCheckpoint(this.checkpoint);
+  }
+  // ── Action Execution ────────────────────────────────
+  executeAction(action) {
+    if (!this.adapter) return;
+    switch (action.type) {
+      case "INJECT_TASK":
+        this.injectTask(action.task);
+        break;
+      case "AUTO_APPROVE":
+        this.adapter.sendKey("y");
+        this.adapter.sendKey("Enter");
+        this.checkpoint.totalPermissionApprovals++;
+        this.logger.logEvent("permission_approved");
+        break;
+      case "NUDGE":
+        this.adapter.sendInput(action.message);
+        this.lastChangeAt = Date.now();
+        this.checkpoint.nudgeCount++;
+        this.logger.logEvent("stuck_detected", {
+          action: "nudge",
+          nudgeCount: this.checkpoint.nudgeCount,
+          message: action.message
+        });
+        break;
+      case "BACKOFF":
+        this.checkpoint.totalRateLimitHits++;
+        this.checkpoint.consecutiveRateLimitHits++;
+        this.logger.logEvent("rate_limit_backoff", {
+          durationMs: action.durationMs
+        });
+        this.sleepSync(action.durationMs);
+        break;
+      case "RESTART_SESSION":
+        this.checkpoint.totalRestarts++;
+        this.checkpoint.consecutiveRestarts++;
+        this.logger.logEvent("session_restarted", {
+          consecutive: this.checkpoint.consecutiveRestarts
+        });
+        this.adapter = this.session.restart();
+        this.lastChangeAt = Date.now();
+        this.lastScreen = "";
+        break;
+      case "KILL_AND_RESTART":
+        this.adapter.sendKey("C-c");
+        this.sleepSync(2e3);
+        this.checkpoint.totalRestarts++;
+        this.logger.logEvent("stuck_detected");
+        this.adapter = this.session.restart();
+        this.lastChangeAt = Date.now();
+        this.lastScreen = "";
+        break;
+      case "MARK_COMPLETE":
+        this.handleTaskComplete(action.taskId);
+        break;
+      case "MARK_BLOCKED":
+        this.handleTaskBlocked(action.taskId, action.reason);
+        break;
+      case "LOG_ERROR":
+        this.logger.logEvent("error", { error: action.error });
+        if (action.error.includes("max consecutive restarts")) {
+          this.stopped = true;
+        }
+        break;
+      case "WAIT":
+        this.sleepSync(action.durationMs);
+        break;
+      case "NOOP":
+        if (this.checkpoint.currentState === "WORKING") {
+          this.checkpoint.consecutiveRateLimitHits = 0;
+          this.checkpoint.consecutiveRestarts = 0;
+        }
+        break;
+    }
+  }
+  // ── Task Lifecycle ──────────────────────────────────
+  injectTask(task) {
+    if (!this.adapter) return;
+    this.adapter.clearHistory();
+    const prompt = this.queue.buildTaskPrompt(task);
+    this.adapter.sendInput(prompt);
+    this.queue.markActive(task.id);
+    this.checkpoint.currentTaskId = task.id;
+    this.checkpoint.nudgeCount = 0;
+    this.lastChangeAt = Date.now();
+    this.logger.logEvent("task_injected", {
+      taskId: task.id,
+      priority: task.priority,
+      task: task.task
+    });
+  }
+  handleTaskComplete(taskId) {
+    this.queue.markDone(taskId);
+    this.checkpoint.tasksCompleted.push(taskId);
+    this.checkpoint.currentTaskId = null;
+    this.checkpoint.consecutiveRestarts = 0;
+    this.logger.logEvent("task_completed", { taskId });
+    if (this.config.autoCommit) {
+      this.autoCommit(taskId);
+    }
+  }
+  handleTaskBlocked(taskId, reason) {
+    this.queue.markBlocked(taskId, reason);
+    this.checkpoint.tasksBlocked.push({ id: taskId, reason });
+    this.checkpoint.currentTaskId = null;
+    this.logger.logEvent("task_blocked", { taskId, reason });
+  }
+  autoCommit(taskId) {
+    try {
+      const status = execSync("git status --porcelain", {
+        cwd: this.config.cwd,
+        encoding: "utf-8",
+        timeout: 1e4
+      }).trim();
+      if (!status) return;
+      execSync("git add -A", {
+        cwd: this.config.cwd,
+        stdio: "ignore",
+        timeout: 1e4
+      });
+      execSync(`git commit -m "operator: complete ${taskId}"`, {
+        cwd: this.config.cwd,
+        stdio: "ignore",
+        timeout: 3e4
+      });
+    } catch {
+    }
+  }
+  // ── Helpers ─────────────────────────────────────────
+  freshCheckpoint() {
+    return {
+      startedAt: Date.now(),
+      lastTickAt: Date.now(),
+      currentState: "UNKNOWN",
+      currentTaskId: null,
+      tasksCompleted: [],
+      tasksBlocked: [],
+      totalRestarts: 0,
+      consecutiveRestarts: 0,
+      totalPermissionApprovals: 0,
+      totalRateLimitHits: 0,
+      consecutiveRateLimitHits: 0,
+      nudgeCount: 0
+    };
+  }
+  sleep(ms) {
+    return new Promise((resolve) => {
+      const timer = setTimeout(resolve, ms);
+      timer.unref();
+    });
+  }
+  sleepSync(ms) {
+    try {
+      execSync(`sleep ${ms / 1e3}`, { stdio: "ignore" });
+    } catch {
+    }
+  }
+}
+export {
+  OvernightRunner
+};

package/dist/src/features/operator/screen-adapter.js

@@ -0,0 +1,91 @@
+import { fileURLToPath as __fileURLToPath } from 'url';
+import { dirname as __pathDirname } from 'path';
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __pathDirname(__filename);
+import { execSync } from "child_process";
+function shellEscape(str) {
+  return "'" + str.replace(/'/g, "'\\''") + "'";
+}
+class TmuxAdapter {
+  constructor(session, pane = "0") {
+    this.session = session;
+    this.pane = pane;
+  }
+  adapterType = "tmux";
+  readScreen() {
+    try {
+      return execSync(
+        `tmux capture-pane -t ${this.session}:${this.pane} -p -S -200`,
+        { encoding: "utf-8", timeout: 5e3 }
+      ).trimEnd();
+    } catch {
+      return "";
+    }
+  }
+  sendInput(text, opts) {
+    try {
+      if (opts?.raw) {
+        execSync(
+          `tmux send-keys -t ${this.session}:${this.pane} -l ${shellEscape(text)}`,
+          { stdio: "ignore", timeout: 5e3 }
+        );
+      } else {
+        execSync(
+          `tmux send-keys -t ${this.session}:${this.pane} ${shellEscape(text)} Enter`,
+          { stdio: "ignore", timeout: 5e3 }
+        );
+      }
+    } catch {
+    }
+  }
+  sendKey(key) {
+    try {
+      execSync(`tmux send-keys -t ${this.session}:${this.pane} ${key}`, {
+        stdio: "ignore",
+        timeout: 5e3
+      });
+    } catch {
+    }
+  }
+  isAlive() {
+    try {
+      execSync(`tmux has-session -t ${this.session}`, { stdio: "ignore" });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  clearHistory() {
+    try {
+      execSync(`tmux clear-history -t ${this.session}:${this.pane}`, {
+        stdio: "ignore",
+        timeout: 5e3
+      });
+    } catch {
+    }
+  }
+}
+class ScreenshotAdapter {
+  adapterType = "desktop";
+  readScreen() {
+    throw new Error(
+      "ScreenshotAdapter not implemented \u2014 use TmuxAdapter for CLI mode"
+    );
+  }
+  sendInput(_text, _opts) {
+    throw new Error("ScreenshotAdapter not implemented");
+  }
+  sendKey(_key) {
+    throw new Error("ScreenshotAdapter not implemented");
+  }
+  isAlive() {
+    throw new Error("ScreenshotAdapter not implemented");
+  }
+  clearHistory() {
+    throw new Error("ScreenshotAdapter not implemented");
+  }
+}
+export {
+  ScreenshotAdapter,
+  TmuxAdapter
+};

package/dist/src/features/operator/session-manager.js

@@ -0,0 +1,127 @@
+import { fileURLToPath as __fileURLToPath } from 'url';
+import { dirname as __pathDirname } from 'path';
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __pathDirname(__filename);
+import { execSync } from "child_process";
+import {
+  isTmuxAvailable,
+  sessionExists,
+  killTmuxSession,
+  sendCtrlC
+} from "../workers/tmux-manager.js";
+import { TmuxAdapter } from "./screen-adapter.js";
+class SessionManager {
+  constructor(config) {
+    this.config = config;
+  }
+  restartCount = 0;
+  /** Preflight: check tmux is available */
+  preflight() {
+    if (!isTmuxAvailable()) {
+      throw new Error(
+        "tmux is required but not found. Install with: brew install tmux"
+      );
+    }
+  }
+  /** Start a new Claude Code session in tmux. Returns a ScreenAdapter. */
+  start() {
+    const { sessionName, cwd } = this.config;
+    if (sessionExists(sessionName)) {
+      try {
+        killTmuxSession(sessionName);
+      } catch {
+      }
+    }
+    execSync(`tmux new-session -d -s ${sessionName} -c ${shellEscape(cwd)}`, {
+      stdio: "ignore",
+      timeout: 1e4
+    });
+    const claudeCmd = this.buildClaudeCommand();
+    execSync(
+      `tmux send-keys -t ${sessionName}:0 ${shellEscape(claudeCmd)} Enter`,
+      { stdio: "ignore", timeout: 5e3 }
+    );
+    const adapter = new TmuxAdapter(sessionName, "0");
+    this.waitForReady(adapter, 3e4);
+    this.restartCount = 0;
+    return adapter;
+  }
+  /** Stop the Claude session gracefully */
+  stop() {
+    const { sessionName } = this.config;
+    if (!sessionExists(sessionName)) return;
+    try {
+      sendCtrlC(sessionName, "0");
+      this.sleep(2e3);
+      execSync(`tmux send-keys -t ${sessionName}:0 '/exit' Enter`, {
+        stdio: "ignore",
+        timeout: 5e3
+      });
+      this.sleep(1e3);
+    } catch {
+    }
+    try {
+      killTmuxSession(sessionName);
+    } catch {
+    }
+  }
+  /** Restart with exponential cooldown */
+  restart() {
+    this.restartCount++;
+    const cooldownMs = Math.min(
+      5e3 * Math.pow(2, this.restartCount - 1),
+      3e5
+    );
+    this.sleep(cooldownMs);
+    this.stop();
+    return this.start();
+  }
+  /** Get consecutive restart count */
+  getRestartCount() {
+    return this.restartCount;
+  }
+  /** Reset restart counter (called when work succeeds) */
+  resetRestartCount() {
+    this.restartCount = 0;
+  }
+  /** Attach user terminal to the tmux session for live observation */
+  attach() {
+    const { sessionName } = this.config;
+    if (!sessionExists(sessionName)) {
+      throw new Error(
+        `No operator session '${sessionName}' running. Start one first.`
+      );
+    }
+    execSync(`tmux attach-session -t ${sessionName}`, { stdio: "inherit" });
+  }
+  // ── Private ───────────────────────────────────────────
+  buildClaudeCommand() {
+    const parts = ["claude"];
+    if (this.config.model) {
+      parts.push("--model", this.config.model);
+    }
+    return parts.join(" ");
+  }
+  waitForReady(adapter, timeoutMs) {
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+      const screen = adapter.readScreen();
+      if (/^>\s*$/m.test(screen) || /How can I help/i.test(screen)) {
+        return;
+      }
+      this.sleep(500);
+    }
+  }
+  sleep(ms) {
+    try {
+      execSync(`sleep ${ms / 1e3}`, { stdio: "ignore" });
+    } catch {
+    }
+  }
+}
+function shellEscape(str) {
+  return "'" + str.replace(/'/g, "'\\''") + "'";
+}
+export {
+  SessionManager
+};