@stackmemoryai/stackmemory 1.12.0 → 1.14.0

package/dist/src/features/operator/state-machine.js

@@ -0,0 +1,227 @@
+import { fileURLToPath as __fileURLToPath } from 'url';
+import { dirname as __pathDirname } from 'path';
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __pathDirname(__filename);
+const RATE_LIMIT_PATTERNS = [
+  /usage limits?/i,
+  /rate limit/i,
+  /too many requests/i,
+  /\b429\b/,
+  /over(?:loaded|capacity)/i,
+  /try again (?:in|after)/i,
+  /exceeded.*quota/i,
+  /max plan.*limit/i,
+  /you've reached/i,
+  /please wait/i
+];
+const PERMISSION_PATTERNS = [
+  /Do you want to proceed\?/i,
+  /Allow\s+(?:this|once|always)/i,
+  /\([Yy]\/[Nn]\)/,
+  /\([Yy]es\/[Nn]o\)/,
+  /Press Enter to allow/i,
+  /Allow .* to run/i,
+  /Do you want to allow/i,
+  /approve.*tool/i,
+  /Would you like to/i
+];
+const ERROR_PATTERNS = [
+  /^Error:/m,
+  /\bFATAL\b/,
+  /\bpanic:/,
+  /Traceback \(most recent/,
+  /Unhandled.*exception/i,
+  /cannot.*connect/i,
+  /\bECONNREFUSED\b/,
+  /\bENOENT\b/,
+  /SIGKILL/,
+  /out of memory/i
+];
+const ERROR_ANTI_PATTERNS = [
+  /Reading file/i,
+  /Searching/i,
+  /grep.*Error/i,
+  /Grep.*pattern/i,
+  /cat.*Error/i,
+  /```/
+];
+const SESSION_ENDED_PATTERNS = [
+  /Process exited/i,
+  /Connection closed/i,
+  /Session ended/i,
+  /claude.*exited/i
+];
+const IDLE_PATTERNS = [
+  /^>\s*$/m,
+  /What would you like/i,
+  /How can I help/i,
+  /What do you want/i
+];
+const WORKING_PATTERNS = [
+  /Reading file/i,
+  /Writing to/i,
+  /Searching/i,
+  /Running/i,
+  /Executing/i,
+  /Analyzing/i,
+  /Creating/i,
+  /Editing/i,
+  /\.\.\./,
+  /Glob|Grep|Read|Write|Edit|Bash/
+];
+const COMPLETION_PATTERNS = [
+  /TASK COMPLETE/,
+  /completed successfully/i,
+  /all tasks? (?:are )?(?:done|completed)/i
+];
+const BLOCKED_PATTERN = /TASK BLOCKED:\s*(.+)/;
+function tailLines(content, n) {
+  const lines = content.split("\n");
+  return lines.slice(-n).join("\n");
+}
+function looksLikeShellPrompt(tail) {
+  const last = tail.split("\n").filter(Boolean).pop() ?? "";
+  return /(?:\$\s*$|%\s*$|bash-\d|zsh|❯\s*$)/.test(last) && !IDLE_PATTERNS.some((p) => p.test(last));
+}
+function detectState(screenContent, previousState, lastChangeTimestamp, stuckTimeoutMs) {
+  const tail = tailLines(screenContent, 50);
+  const recentTail = tailLines(screenContent, 10);
+  if (screenContent === "") {
+    return {
+      state: "SESSION_ENDED",
+      confidence: "high",
+      detail: "empty screen buffer"
+    };
+  }
+  if (SESSION_ENDED_PATTERNS.some((p) => p.test(tail))) {
+    return {
+      state: "SESSION_ENDED",
+      confidence: "high",
+      detail: "exit pattern matched"
+    };
+  }
+  if (looksLikeShellPrompt(recentTail)) {
+    return {
+      state: "SESSION_ENDED",
+      confidence: "medium",
+      detail: "shell prompt detected"
+    };
+  }
+  for (const pattern of RATE_LIMIT_PATTERNS) {
+    if (pattern.test(recentTail)) {
+      return {
+        state: "RATE_LIMITED",
+        confidence: "high",
+        detail: pattern.source
+      };
+    }
+  }
+  for (const pattern of PERMISSION_PATTERNS) {
+    if (pattern.test(recentTail)) {
+      return {
+        state: "PERMISSION_PROMPT",
+        confidence: "high",
+        detail: pattern.source
+      };
+    }
+  }
+  const hasAntiPattern = ERROR_ANTI_PATTERNS.some((p) => p.test(recentTail));
+  if (!hasAntiPattern) {
+    for (const pattern of ERROR_PATTERNS) {
+      if (pattern.test(recentTail)) {
+        return { state: "ERROR", confidence: "medium", detail: pattern.source };
+      }
+    }
+  }
+  if (IDLE_PATTERNS.some((p) => p.test(recentTail))) {
+    return { state: "IDLE", confidence: "high" };
+  }
+  if (WORKING_PATTERNS.some((p) => p.test(recentTail))) {
+    return { state: "WORKING", confidence: "high" };
+  }
+  const elapsed = Date.now() - lastChangeTimestamp;
+  if (elapsed > stuckTimeoutMs && previousState === "WORKING") {
+    return {
+      state: "STUCK",
+      confidence: "high",
+      detail: `no change for ${Math.round(elapsed / 1e3)}s`
+    };
+  }
+  return { state: "UNKNOWN", confidence: "low" };
+}
+function decideAction(detection, checkpoint, nextTask) {
+  const { state } = detection;
+  switch (state) {
+    case "PERMISSION_PROMPT":
+      return { type: "AUTO_APPROVE" };
+    case "RATE_LIMITED": {
+      const hits = checkpoint.consecutiveRateLimitHits + 1;
+      const backoff = Math.min(6e4 * Math.pow(2, hits - 1), 9e5);
+      return { type: "BACKOFF", durationMs: backoff };
+    }
+    case "SESSION_ENDED": {
+      if (checkpoint.consecutiveRestarts >= 10) {
+        return {
+          type: "LOG_ERROR",
+          error: "max consecutive restarts exceeded \u2014 stopping"
+        };
+      }
+      return { type: "RESTART_SESSION" };
+    }
+    case "STUCK":
+      if (checkpoint.currentTaskId) {
+        if (checkpoint.nudgeCount < 2) {
+          return {
+            type: "NUDGE",
+            message: "You appear stuck. Try a different approach or run the tests to check progress."
+          };
+        }
+        return {
+          type: "MARK_BLOCKED",
+          taskId: checkpoint.currentTaskId,
+          reason: detection.detail ?? "stuck \u2014 no output after nudges"
+        };
+      }
+      return { type: "KILL_AND_RESTART" };
+    case "ERROR":
+      return { type: "LOG_ERROR", error: detection.detail ?? "unknown error" };
+    case "WORKING":
+      return { type: "NOOP" };
+    case "IDLE": {
+      if (checkpoint.currentTaskId) {
+        return { type: "WAIT", durationMs: 2e3 };
+      }
+      if (nextTask) {
+        return { type: "INJECT_TASK", task: nextTask };
+      }
+      return { type: "NOOP" };
+    }
+    case "COMPLETE":
+      if (checkpoint.currentTaskId) {
+        return { type: "MARK_COMPLETE", taskId: checkpoint.currentTaskId };
+      }
+      return { type: "NOOP" };
+    default:
+      return { type: "WAIT", durationMs: 2e3 };
+  }
+}
+function detectCompletion(screenContent) {
+  const tail = tailLines(screenContent, 15);
+  if (COMPLETION_PATTERNS.some((p) => p.test(tail))) {
+    return { completed: true, blocked: false };
+  }
+  const blockedMatch = BLOCKED_PATTERN.exec(tail);
+  if (blockedMatch?.[1]) {
+    return {
+      completed: false,
+      blocked: true,
+      blockedReason: blockedMatch[1].trim()
+    };
+  }
+  return { completed: false, blocked: false };
+}
+export {
+  decideAction,
+  detectCompletion,
+  detectState
+};

package/dist/src/features/operator/task-queue.js

@@ -0,0 +1,81 @@
+import { fileURLToPath as __fileURLToPath } from 'url';
+import { dirname as __pathDirname } from 'path';
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __pathDirname(__filename);
+import { readFileSync } from "fs";
+import {
+  parseMasterTasks,
+  getNextTask,
+  updateTaskInFile
+} from "../../core/tasks/md-task-parser.js";
+class TaskQueue {
+  constructor(filePath) {
+    this.filePath = filePath;
+  }
+  /** Get the highest-priority actionable task */
+  dequeue() {
+    const content = readFileSync(this.filePath, "utf-8");
+    const tasks = parseMasterTasks(content);
+    return getNextTask(tasks);
+  }
+  /** Mark a task as active with @operator owner */
+  markActive(taskId) {
+    updateTaskInFile(this.filePath, taskId, {
+      status: "active",
+      owner: "@operator"
+    });
+  }
+  /** Mark a task as done */
+  markDone(taskId, notes) {
+    const updates = { status: "done" };
+    if (notes) updates.notes = notes;
+    updateTaskInFile(this.filePath, taskId, updates);
+  }
+  /** Mark a task as blocked with reason */
+  markBlocked(taskId, reason) {
+    updateTaskInFile(this.filePath, taskId, {
+      status: "blocked",
+      notes: reason
+    });
+  }
+  /** Count of remaining actionable tasks */
+  remaining() {
+    const content = readFileSync(this.filePath, "utf-8");
+    const tasks = parseMasterTasks(content);
+    return tasks.filter((t) => t.status === "todo" || t.status === "active").length;
+  }
+  /** True when no more actionable tasks */
+  isEmpty() {
+    return this.remaining() === 0;
+  }
+  /** Format a task into a Claude-friendly prompt with completion sentinels */
+  buildTaskPrompt(task) {
+    const parts = [
+      `# Task: ${task.task}`,
+      "",
+      `Priority: ${task.priority}`,
+      `ID: ${task.id}`
+    ];
+    if (task.notes) {
+      parts.push(`Notes: ${task.notes}`);
+    }
+    parts.push(
+      "",
+      "## Instructions",
+      "- Complete this task fully before moving on",
+      "- Run tests, lint, and build to verify your work",
+      "- Commit your changes with a descriptive message",
+      "",
+      "## Completion",
+      "When you have fully completed this task, output exactly:",
+      "TASK COMPLETE",
+      "",
+      "If you are blocked and cannot proceed, output exactly:",
+      "TASK BLOCKED: <reason>"
+    );
+    return parts.join("\n");
+  }
+}
+export {
+  TaskQueue
+};

package/dist/src/features/portal/index.js

@@ -0,0 +1,26 @@
+import { fileURLToPath as __fileURLToPath } from 'url';
+import { dirname as __pathDirname } from 'path';
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __pathDirname(__filename);
+import {
+  PortalServer,
+  resolveConfig,
+  ensureToken,
+  readStatus,
+  stopRunning,
+  getPortalDir
+} from "./server.js";
+import { renderPortalPage } from "./ui.js";
+import {
+  DEFAULT_PORTAL_CONFIG
+} from "./types.js";
+export {
+  DEFAULT_PORTAL_CONFIG,
+  PortalServer,
+  ensureToken,
+  getPortalDir,
+  readStatus,
+  renderPortalPage,
+  resolveConfig,
+  stopRunning
+};

package/dist/src/features/portal/server.js

@@ -0,0 +1,240 @@
+import { fileURLToPath as __fileURLToPath } from 'url';
+import { dirname as __pathDirname } from 'path';
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __pathDirname(__filename);
+import express from "express";
+import { createServer } from "http";
+import { Server as SocketServer } from "socket.io";
+import { execFileSync } from "child_process";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  unlinkSync
+} from "fs";
+import { join } from "path";
+import { randomBytes } from "crypto";
+import { renderPortalPage } from "./ui.js";
+import {
+  DEFAULT_PORTAL_CONFIG
+} from "./types.js";
+const HOME = process.env["HOME"] || "/tmp";
+function getPortalDir() {
+  const dir = process.env["PORTAL_STATE_DIR"] || join(HOME, ".stackmemory", "portal");
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  return dir;
+}
+function tokenPath() {
+  return join(getPortalDir(), "token");
+}
+function pidPath() {
+  return join(getPortalDir(), "portal.json");
+}
+function ensureToken() {
+  const p = tokenPath();
+  if (existsSync(p)) {
+    const t = readFileSync(p, "utf-8").trim();
+    if (t) return t;
+  }
+  const token = randomBytes(24).toString("hex");
+  writeFileSync(p, token + "\n", { mode: 384 });
+  return token;
+}
+function tmuxAvailable() {
+  try {
+    execFileSync("tmux", ["-V"], { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function resolveConfig(overrides = {}) {
+  const token = overrides.token ?? (overrides.noAuth ? "" : ensureToken());
+  return {
+    ...DEFAULT_PORTAL_CONFIG,
+    cwd: process.cwd(),
+    token,
+    ...overrides
+  };
+}
+class PortalServer {
+  config;
+  httpServer = null;
+  io = null;
+  ptys = /* @__PURE__ */ new Set();
+  constructor(config = {}) {
+    this.config = resolveConfig(config);
+  }
+  getConfig() {
+    return this.config;
+  }
+  authOk(token) {
+    if (this.config.noAuth) return true;
+    return typeof token === "string" && token === this.config.token;
+  }
+  async start() {
+    if (!tmuxAvailable()) {
+      throw new Error(
+        "tmux is not installed. Install it first (e.g. `apt install tmux` / `brew install tmux`)."
+      );
+    }
+    const app = express();
+    const page = renderPortalPage({ session: this.config.session });
+    app.get("/", (req, res) => {
+      if (!this.config.noAuth && !this.authOk(req.query["token"])) {
+        res.status(401).type("text/plain").send("Unauthorized: missing or invalid ?token");
+        return;
+      }
+      res.type("html").send(page);
+    });
+    app.get("/healthz", (_req, res) => {
+      res.json({ ok: true, session: this.config.session });
+    });
+    const httpServer = createServer(app);
+    const io = new SocketServer(httpServer, { cors: { origin: true } });
+    io.use((socket, next) => {
+      const token = socket.handshake.auth?.token ?? socket.handshake.query["token"];
+      if (this.authOk(token)) return next();
+      next(new Error("Invalid access token"));
+    });
+    io.on("connection", (socket) => {
+      void this.attachSession(socket);
+    });
+    this.httpServer = httpServer;
+    this.io = io;
+    await new Promise((resolve, reject) => {
+      httpServer.once("error", reject);
+      httpServer.listen(this.config.port, this.config.host, () => resolve());
+    });
+    const status = {
+      running: true,
+      pid: process.pid,
+      port: this.config.port,
+      host: this.config.host,
+      session: this.config.session,
+      startedAt: Date.now()
+    };
+    writeFileSync(pidPath(), JSON.stringify(status, null, 2));
+    return status;
+  }
+  async attachSession(socket) {
+    let pty;
+    try {
+      pty = await import("node-pty");
+    } catch {
+      socket.emit(
+        "portal:error",
+        "node-pty is not installed on the server. Run: npm install node-pty"
+      );
+      return;
+    }
+    const proc = pty.spawn(
+      "tmux",
+      ["new-session", "-A", "-s", this.config.session, this.config.command],
+      {
+        name: "xterm-256color",
+        cols: 80,
+        rows: 24,
+        cwd: this.config.cwd,
+        env: { ...process.env, TERM: "xterm-256color" }
+      }
+    );
+    this.ptys.add(proc);
+    proc.onData((data) => socket.emit("output", data));
+    proc.onExit(() => {
+      this.ptys.delete(proc);
+      socket.emit(
+        "output",
+        "\r\n\x1B[33m[portal] session detached]\x1B[0m\r\n"
+      );
+    });
+    socket.on("input", (data) => {
+      if (typeof data === "string") proc.write(data);
+    });
+    socket.on("resize", (size) => {
+      const s = size;
+      if (s && Number.isFinite(s.cols) && Number.isFinite(s.rows)) {
+        try {
+          proc.resize(
+            Math.max(2, s.cols),
+            Math.max(2, s.rows)
+          );
+        } catch {
+        }
+      }
+    });
+    socket.on("disconnect", () => {
+      this.ptys.delete(proc);
+      try {
+        proc.kill();
+      } catch {
+      }
+    });
+  }
+  async stop() {
+    for (const p of this.ptys) {
+      try {
+        p.kill();
+      } catch {
+      }
+    }
+    this.ptys.clear();
+    if (this.io) {
+      this.io.close();
+      this.io = null;
+    }
+    await new Promise((resolve) => {
+      if (!this.httpServer) return resolve();
+      this.httpServer.close(() => resolve());
+    });
+    this.httpServer = null;
+    clearPidFile();
+  }
+}
+function readStatus() {
+  const p = pidPath();
+  if (!existsSync(p)) return { running: false };
+  try {
+    const status = JSON.parse(readFileSync(p, "utf-8"));
+    if (status.pid && !isProcessAlive(status.pid)) {
+      clearPidFile();
+      return { running: false };
+    }
+    return status;
+  } catch {
+    return { running: false };
+  }
+}
+function stopRunning() {
+  const status = readStatus();
+  if (!status.running || !status.pid) return false;
+  try {
+    process.kill(status.pid, "SIGTERM");
+  } catch {
+  }
+  clearPidFile();
+  return true;
+}
+function clearPidFile() {
+  try {
+    if (existsSync(pidPath())) unlinkSync(pidPath());
+  } catch {
+  }
+}
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+export {
+  PortalServer,
+  ensureToken,
+  getPortalDir,
+  readStatus,
+  resolveConfig,
+  stopRunning
+};

package/dist/src/features/portal/types.js

@@ -0,0 +1,14 @@
+import { fileURLToPath as __fileURLToPath } from 'url';
+import { dirname as __pathDirname } from 'path';
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __pathDirname(__filename);
+const DEFAULT_PORTAL_CONFIG = {
+  port: 7799,
+  host: "0.0.0.0",
+  session: "claude",
+  command: "claude",
+  noAuth: false
+};
+export {
+  DEFAULT_PORTAL_CONFIG
+};