@stackmemoryai/stackmemory 1.12.0 → 1.14.0

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

@@ -0,0 +1,109 @@
+import { fileURLToPath as __fileURLToPath } from 'url';
+import { dirname as __pathDirname } from 'path';
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __pathDirname(__filename);
+const SELECTORS = {
+  /** Main conversation/output area */
+  output: '[data-testid="conversation-panel"], .conversation-content, main',
+  /** Input textarea */
+  input: 'textarea[placeholder], [contenteditable="true"], .prompt-input',
+  /** Permission/approval buttons */
+  approveButton: 'button:has-text("Allow"), button:has-text("Approve"), button:has-text("Yes")',
+  /** Loading/working indicators */
+  spinner: '.loading, .spinner, [data-loading="true"]'
+};
+class BrowserAdapter {
+  constructor(page) {
+    this.page = page;
+  }
+  adapterType = "browser";
+  lastContent = "";
+  readScreen() {
+    return this.lastContent;
+  }
+  /** Async version — call before each tick in the runner */
+  async readScreenAsync() {
+    try {
+      const content = await this.page.locator(SELECTORS.output).textContent();
+      this.lastContent = content ?? "";
+    } catch {
+      this.lastContent = "";
+    }
+    return this.lastContent;
+  }
+  readScreenshot() {
+    return void 0;
+  }
+  async readScreenshotAsync() {
+    const buffer = await this.page.screenshot({ fullPage: false });
+    return {
+      base64: buffer.toString("base64"),
+      mediaType: "image/png"
+    };
+  }
+  sendInput(text, opts) {
+    this.sendInputAsync(text, opts).catch(() => {
+    });
+  }
+  async sendInputAsync(text, opts) {
+    try {
+      const inputLocator = this.page.locator(SELECTORS.input);
+      const count = await inputLocator.count();
+      if (count === 0) return;
+      await inputLocator.fill(text);
+      if (!opts?.raw) {
+        await this.page.keyboard.press("Enter");
+      }
+    } catch {
+    }
+  }
+  sendKey(key) {
+    this.sendKeyAsync(key).catch(() => {
+    });
+  }
+  async sendKeyAsync(key) {
+    const keyMap = {
+      Enter: "Enter",
+      "C-c": "Control+c",
+      Escape: "Escape",
+      Tab: "Tab",
+      y: "y",
+      n: "n"
+    };
+    try {
+      if (key === "y") {
+        const approveBtn = this.page.locator(SELECTORS.approveButton);
+        if (await approveBtn.count() > 0) {
+          await approveBtn.click();
+          return;
+        }
+      }
+      await this.page.keyboard.press(keyMap[key] ?? key);
+    } catch {
+    }
+  }
+  isAlive() {
+    try {
+      return !this.page.isClosed();
+    } catch {
+      return false;
+    }
+  }
+  clearHistory() {
+  }
+  /** Check if a spinner/loading indicator is visible */
+  async isWorking() {
+    try {
+      return await this.page.locator(SELECTORS.spinner).isVisible();
+    } catch {
+      return false;
+    }
+  }
+  /** Navigate to Claude Code web app */
+  async navigate(url = "https://claude.ai/code") {
+    await this.page.goto(url, { waitUntil: "networkidle" });
+  }
+}
+export {
+  BrowserAdapter
+};

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

@@ -0,0 +1,125 @@
+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 { readFileSync, existsSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+const SCREENSHOT_PATH = join(tmpdir(), "operator-screenshot.png");
+class DesktopAdapter {
+  constructor(appName = "Claude", llmConfig) {
+    this.appName = appName;
+    this.llmConfig = llmConfig;
+  }
+  adapterType = "desktop";
+  lastClassifiedText = "";
+  readScreen() {
+    this.captureWindow();
+    const screenshot = this.readScreenshotFile();
+    if (!screenshot) return this.lastClassifiedText;
+    try {
+      const result = execSync(
+        `node -e "
+          const { classifyScreenState } = require('${__dirname}/llm-decision.js');
+          classifyScreenState(
+            { base64: '${screenshot.base64.slice(0, 100)}...', mediaType: '${screenshot.mediaType}' },
+            { apiKey: '${this.llmConfig.apiKey}' }
+          ).then(r => process.stdout.write(JSON.stringify(r)));
+        "`,
+        { encoding: "utf-8", timeout: 15e3 }
+      );
+      this.lastClassifiedText = result;
+    } catch {
+    }
+    return this.lastClassifiedText;
+  }
+  readScreenshot() {
+    this.captureWindow();
+    return this.readScreenshotFile();
+  }
+  sendInput(text, opts) {
+    this.activateApp();
+    const escaped = text.replace(/"/g, '\\"').replace(/\\/g, "\\\\");
+    try {
+      execSync(
+        `osascript -e 'tell application "System Events" to keystroke "${escaped}"'`,
+        { stdio: "ignore", timeout: 5e3 }
+      );
+      if (!opts?.raw) {
+        execSync(
+          `osascript -e 'tell application "System Events" to key code 36'`,
+          { stdio: "ignore", timeout: 5e3 }
+        );
+      }
+    } catch {
+    }
+  }
+  sendKey(key) {
+    this.activateApp();
+    const keyMap = {
+      Enter: "key code 36",
+      "C-c": 'keystroke "c" using control down',
+      Escape: "key code 53",
+      Tab: "key code 48",
+      y: 'keystroke "y"',
+      n: 'keystroke "n"'
+    };
+    const action = keyMap[key] ?? `keystroke "${key}"`;
+    try {
+      execSync(`osascript -e 'tell application "System Events" to ${action}'`, {
+        stdio: "ignore",
+        timeout: 5e3
+      });
+    } catch {
+    }
+  }
+  isAlive() {
+    try {
+      const result = execSync(
+        `osascript -e 'tell application "System Events" to (name of processes) contains "${this.appName}"'`,
+        { encoding: "utf-8", timeout: 5e3 }
+      ).trim();
+      return result === "true";
+    } catch {
+      return false;
+    }
+  }
+  clearHistory() {
+  }
+  // ── Private ───────────────────────────────────────────
+  captureWindow() {
+    try {
+      execSync(`screencapture -x -o ${SCREENSHOT_PATH}`, {
+        stdio: "ignore",
+        timeout: 5e3
+      });
+    } catch {
+    }
+  }
+  readScreenshotFile() {
+    if (!existsSync(SCREENSHOT_PATH)) return void 0;
+    try {
+      const data = readFileSync(SCREENSHOT_PATH);
+      return {
+        base64: data.toString("base64"),
+        mediaType: "image/png"
+      };
+    } catch {
+      return void 0;
+    }
+  }
+  activateApp() {
+    try {
+      execSync(
+        `osascript -e 'tell application "${this.appName}" to activate'`,
+        { stdio: "ignore", timeout: 5e3 }
+      );
+      execSync("sleep 0.3", { stdio: "ignore" });
+    } catch {
+    }
+  }
+}
+export {
+  DesktopAdapter
+};

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

@@ -0,0 +1,39 @@
+import { fileURLToPath as __fileURLToPath } from 'url';
+import { dirname as __pathDirname } from 'path';
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __pathDirname(__filename);
+import { TmuxAdapter, ScreenshotAdapter } from "./screen-adapter.js";
+import { DesktopAdapter } from "./desktop-adapter.js";
+import { BrowserAdapter } from "./browser-adapter.js";
+import { createAdapter } from "./adapter-factory.js";
+import {
+  detectState,
+  decideAction,
+  detectCompletion
+} from "./state-machine.js";
+import {
+  classifyScreenState,
+  generateNudge,
+  generateRecoveryPrompt
+} from "./llm-decision.js";
+import { TaskQueue } from "./task-queue.js";
+import { SessionManager } from "./session-manager.js";
+import { OvernightRunner } from "./overnight-runner.js";
+import { OperatorLogger } from "./operator-logger.js";
+export {
+  BrowserAdapter,
+  DesktopAdapter,
+  OperatorLogger,
+  OvernightRunner,
+  ScreenshotAdapter,
+  SessionManager,
+  TaskQueue,
+  TmuxAdapter,
+  classifyScreenState,
+  createAdapter,
+  decideAction,
+  detectCompletion,
+  detectState,
+  generateNudge,
+  generateRecoveryPrompt
+};

package/dist/src/features/operator/llm-decision.js

@@ -0,0 +1,137 @@
+import { fileURLToPath as __fileURLToPath } from 'url';
+import { dirname as __pathDirname } from 'path';
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __pathDirname(__filename);
+const ANTHROPIC_API_URL = "https://api.anthropic.com/v1/messages";
+const CLASSIFY_SYSTEM = `You are a screen state classifier for Claude Code CLI sessions.
+Given screen content (text or screenshot), classify the state as exactly one of:
+IDLE, WORKING, PERMISSION_PROMPT, ERROR, COMPLETE, STUCK, RATE_LIMITED, SESSION_ENDED, UNKNOWN
+
+Respond with ONLY a JSON object:
+{"state": "<STATE>", "confidence": "high"|"medium"|"low", "detail": "<brief reason>"}
+
+Rules:
+- PERMISSION_PROMPT: Claude is asking for user approval (Y/n, Allow, Proceed?)
+- RATE_LIMITED: usage limit, rate limit, 429, "try again"
+- SESSION_ENDED: shell prompt visible, process exited, no Claude session
+- ERROR: error message not inside a code block or file read
+- IDLE: Claude's ">" prompt visible, waiting for input
+- WORKING: Claude is reading files, searching, running commands
+- COMPLETE: task finished, "TASK COMPLETE" visible
+- STUCK: same content repeated, no progress indicators
+- UNKNOWN: cannot determine`;
+async function classifyScreenState(content, config) {
+  const userContent = [];
+  if (typeof content === "string") {
+    userContent.push({
+      type: "text",
+      text: `Screen content:
+${content.slice(-3e3)}`
+    });
+  } else {
+    userContent.push({
+      type: "image",
+      source: {
+        type: "base64",
+        media_type: content.mediaType,
+        data: content.base64
+      }
+    });
+    userContent.push({
+      type: "text",
+      text: "Classify the state of this Claude Code session screenshot."
+    });
+  }
+  try {
+    const response = await callHaiku(config, CLASSIFY_SYSTEM, userContent);
+    const parsed = JSON.parse(response);
+    return {
+      state: parsed.state,
+      confidence: parsed.confidence ?? "medium",
+      detail: parsed.detail
+    };
+  } catch {
+    return {
+      state: "UNKNOWN",
+      confidence: "low",
+      detail: "LLM classification failed"
+    };
+  }
+}
+const NUDGE_SYSTEM = `You are an operator for an autonomous Claude Code session.
+The inner Claude session appears stuck or going in circles.
+
+Given the recent screen content and task context, generate a SHORT nudge message
+(1-3 sentences) to get Claude back on track. Be direct and specific.
+
+Examples of good nudges:
+- "The tests are failing because of a missing import. Try: import { Foo } from './foo.js'"
+- "You've been editing the same file for 5 minutes. Run the tests to check progress."
+- "Stop investigating \u2014 just fix the type error on line 42 and move on."
+
+Respond with ONLY the nudge text, no JSON wrapper.`;
+async function generateNudge(screenContent, taskDescription, config) {
+  const prompt = `Task: ${taskDescription}
+
+Recent screen:
+${screenContent.slice(-2e3)}`;
+  try {
+    return await callHaiku(config, NUDGE_SYSTEM, [
+      { type: "text", text: prompt }
+    ]);
+  } catch {
+    return void 0;
+  }
+}
+const RECOVERY_SYSTEM = `You are an operator for an autonomous Claude Code session.
+The session has encountered an error or is blocked.
+
+Given the error context, generate a recovery prompt that Claude can use to fix the issue.
+Be specific: name files, error messages, and concrete next steps.
+
+Respond with ONLY the recovery prompt text.`;
+async function generateRecoveryPrompt(screenContent, errorDetail, checkpoint, config) {
+  const context = [
+    `Error: ${errorDetail}`,
+    `Current task: ${checkpoint.currentTaskId ?? "none"}`,
+    `Restarts so far: ${checkpoint.totalRestarts}`,
+    `
+Recent screen:
+${screenContent.slice(-2e3)}`
+  ].join("\n");
+  try {
+    return await callHaiku(config, RECOVERY_SYSTEM, [
+      { type: "text", text: context }
+    ]);
+  } catch {
+    return void 0;
+  }
+}
+async function callHaiku(config, system, content) {
+  const model = config.model ?? "claude-haiku-4-5-20251001";
+  const maxTokens = config.maxTokens ?? 256;
+  const response = await fetch(ANTHROPIC_API_URL, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "x-api-key": config.apiKey,
+      "anthropic-version": "2023-06-01"
+    },
+    body: JSON.stringify({
+      model,
+      max_tokens: maxTokens,
+      system,
+      messages: [{ role: "user", content }]
+    })
+  });
+  if (!response.ok) {
+    throw new Error(`Haiku API ${response.status}: ${await response.text()}`);
+  }
+  const data = await response.json();
+  return data.content[0]?.text ?? "";
+}
+export {
+  classifyScreenState,
+  generateNudge,
+  generateRecoveryPrompt
+};

package/dist/src/features/operator/operator-logger.js

@@ -0,0 +1,92 @@
+import { fileURLToPath as __fileURLToPath } from 'url';
+import { dirname as __pathDirname } from 'path';
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __pathDirname(__filename);
+import {
+  mkdirSync,
+  appendFileSync,
+  writeFileSync,
+  existsSync,
+  readFileSync
+} from "fs";
+import { join } from "path";
+class OperatorLogger {
+  constructor(logDir, checkpointDir) {
+    this.checkpointDir = checkpointDir;
+    mkdirSync(logDir, { recursive: true });
+    mkdirSync(checkpointDir, { recursive: true });
+    const ts = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+    this.logFile = join(logDir, `operator-${ts}.jsonl`);
+    this.checkpointFile = join(checkpointDir, "checkpoint.json");
+  }
+  logFile;
+  checkpointFile;
+  /** Log a tick (called each poll cycle) */
+  logTick(entry) {
+    const tick = { timestamp: Date.now(), ...entry };
+    this.appendLine(tick);
+  }
+  /** Log a named event */
+  logEvent(event, data) {
+    const entry = { timestamp: Date.now(), event, data };
+    this.appendLine(entry);
+    const msg = data ? `[operator] ${event}: ${JSON.stringify(data)}` : `[operator] ${event}`;
+    process.stderr.write(msg + "\n");
+  }
+  /** Write checkpoint file for status reads */
+  writeCheckpoint(checkpoint) {
+    writeFileSync(
+      this.checkpointFile,
+      JSON.stringify(checkpoint, null, 2),
+      "utf-8"
+    );
+  }
+  /** Read checkpoint from disk (for status command) */
+  static readCheckpoint(checkpointDir) {
+    const file = join(checkpointDir, "checkpoint.json");
+    if (!existsSync(file)) return void 0;
+    try {
+      return JSON.parse(readFileSync(file, "utf-8"));
+    } catch {
+      return void 0;
+    }
+  }
+  /** Print summary to stderr */
+  printSummary(summary) {
+    const runtime = formatDuration(summary.totalRuntimeMs);
+    const lines = [
+      "",
+      "=== Operator Summary ===",
+      `Runtime:      ${runtime}`,
+      `Completed:    ${summary.tasksCompleted}`,
+      `Blocked:      ${summary.tasksBlocked}`,
+      `Remaining:    ${summary.tasksRemaining}`,
+      `Restarts:     ${summary.totalRestarts}`,
+      `Approvals:    ${summary.totalPermissionApprovals}`,
+      `Rate limits:  ${summary.totalRateLimitHits}`,
+      `Log file:     ${this.logFile}`,
+      `Checkpoint:   ${this.checkpointFile}`,
+      "========================",
+      ""
+    ];
+    process.stderr.write(lines.join("\n"));
+  }
+  getLogFile() {
+    return this.logFile;
+  }
+  // ── Private ───────────────────────────────────────────
+  appendLine(entry) {
+    appendFileSync(this.logFile, JSON.stringify(entry) + "\n", "utf-8");
+  }
+}
+function formatDuration(ms) {
+  const secs = Math.floor(ms / 1e3);
+  const mins = Math.floor(secs / 60);
+  const hrs = Math.floor(mins / 60);
+  if (hrs > 0) return `${hrs}h ${mins % 60}m`;
+  if (mins > 0) return `${mins}m ${secs % 60}s`;
+  return `${secs}s`;
+}
+export {
+  OperatorLogger
+};