@stackmemoryai/stackmemory 1.10.5 → 1.14.0

package/dist/src/cli/commands/vision.js

@@ -0,0 +1,221 @@
+import { fileURLToPath as __fileURLToPath } from 'url';
+import { dirname as __pathDirname } from 'path';
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __pathDirname(__filename);
+import { Command } from "commander";
+import chalk from "chalk";
+import { spawnSync } from "child_process";
+import { join } from "path";
+import { openBrain } from "../../core/brain/index.js";
+import {
+  VisionLoop,
+  SignalInbox,
+  loadVision,
+  scaffoldVision
+} from "../../core/vision/index.js";
+function paths(cwd) {
+  return {
+    visionPath: join(cwd, "VISION.md"),
+    statePath: join(cwd, ".stackmemory", "vision", "state.json"),
+    signalsPath: join(cwd, ".stackmemory", "vision", "signals.jsonl")
+  };
+}
+function shellDelegate(template, timeoutMs) {
+  return async (candidate) => {
+    const cmd = template.replaceAll("{{OBJECTIVE}}", candidate.text).replaceAll("{{KIND}}", candidate.kind).replaceAll("{{REFS}}", candidate.refs.join(","));
+    const res = spawnSync("sh", ["-c", cmd], {
+      encoding: "utf-8",
+      timeout: timeoutMs,
+      maxBuffer: 32 * 1024 * 1024
+    });
+    const success = res.status === 0 && !res.error;
+    const out = (res.stdout || "").trim().split(/\r?\n/).filter(Boolean);
+    const errTail = (res.stderr || "").trim().split(/\r?\n/).filter(Boolean).pop();
+    const conclusion = success ? out.pop() || "completed" : `failed (${res.error?.message || `exit ${res.status}`}): ${errTail ?? ""}`.trim();
+    return { success, conclusion: conclusion.slice(0, 300) };
+  };
+}
+function fmtDecision(d) {
+  if (!d.guardrail.ok) return chalk.red(`\u26D4 stop: ${d.guardrail.reason}`);
+  if (!d.candidate) return chalk.dim("\xB7 nothing to do");
+  const tag = d.candidate.kind === "signal" ? chalk.yellow("[signal]") : chalk.cyan("[objective]");
+  const head = `${tag} ${d.candidate.text}`;
+  if (d.skippedAsKnown)
+    return `${head}
+   ${chalk.gray("\u21A9 already concluded:")} ${d.priorConclusion}`;
+  if (!d.delegated)
+    return `${head}
+   ${chalk.gray("\xB7 planned (not delegated)")}`;
+  const mark = d.outcome?.success ? chalk.green("\u2713") : chalk.red("\u2717");
+  return `${head}
+   ${mark} ${d.outcome?.conclusion}`;
+}
+function createVisionCommand() {
+  const cmd = new Command("vision").description("VISION.md-driven meta-loop above the conductor").addHelpText(
+    "after",
+    `
+Examples:
+  stackmemory conductor vision init               Scaffold a VISION.md
+  stackmemory conductor vision status             Mission, objectives, limits
+  stackmemory conductor vision signal "500s on /sync" --severity high
+  stackmemory conductor vision plan               Dry-run: what it WOULD do
+  stackmemory conductor vision run --once --dry-run
+  stackmemory conductor vision run --delegate-cmd 'claude -p "{{OBJECTIVE}}"'
+
+VISION.md is the guardrail: north-star mission, scope, objectives, and hard
+limits (maxIterations, maxConsecutiveFailures, \u2026). See docs/guides/VISION.md.
+`
+  );
+  cmd.command("init").description("Scaffold a VISION.md in the current repo").option("--force", "Overwrite an existing VISION.md").action((options) => {
+    const { visionPath } = paths(process.cwd());
+    if (scaffoldVision(visionPath, !!options.force)) {
+      console.log(chalk.green("\u2713 created"), visionPath);
+      console.log(
+        chalk.gray("  Edit the mission, guardrails, and objectives, then:")
+      );
+      console.log(chalk.gray("  stackmemory conductor vision plan"));
+    } else {
+      console.log(
+        chalk.yellow("VISION.md already exists (use --force to overwrite).")
+      );
+    }
+  });
+  cmd.command("status").description("Show the vision, objective progress, signals, and limits").option("--json", "Output as JSON").action((options) => {
+    const p = paths(process.cwd());
+    const vision = loadVision(p.visionPath);
+    if (!vision) {
+      console.log(
+        chalk.yellow("No VISION.md. Run: stackmemory conductor vision init")
+      );
+      return;
+    }
+    const inbox = new SignalInbox(p.signalsPath);
+    const pending = inbox.pending();
+    const done = vision.objectives.filter((o) => o.done).length;
+    if (options.json) {
+      console.log(
+        JSON.stringify({ vision, pendingSignals: pending }, null, 2)
+      );
+      return;
+    }
+    console.log(chalk.bold("Mission"));
+    console.log("  " + (vision.mission || chalk.dim("(none set)")));
+    console.log(
+      chalk.bold(`
+Objectives (${done}/${vision.objectives.length})`)
+    );
+    for (const o of vision.objectives) {
+      console.log(
+        `  ${o.done ? chalk.green("[x]") : chalk.dim("[ ]")} ${o.text}`
+      );
+    }
+    console.log(chalk.bold(`
+Guardrails (${vision.guardrails.length})`));
+    for (const g of vision.guardrails)
+      console.log(`  ${chalk.gray("\u2022")} ${g}`);
+    console.log(chalk.bold(`
+Pending signals (${pending.length})`));
+    for (const s of pending.slice(0, 10)) {
+      console.log(`  ${chalk.yellow(s.severity.padEnd(8))} ${s.text}`);
+    }
+    console.log(chalk.bold("\nLimits"));
+    console.log(
+      chalk.gray(
+        `  maxIterations=${vision.limits.maxIterations} perDay=${vision.limits.maxIterationsPerDay} maxConsecutiveFailures=${vision.limits.maxConsecutiveFailures} requireApproval=${vision.limits.requireApproval}`
+      )
+    );
+  });
+  cmd.command("signal").description("Add a signal to the monitored inbox").argument("<text>", "What happened (bug, CI failure, request)").option("--severity <level>", "low | medium | high | critical", "medium").option(
+    "--source <name>",
+    "Where it came from (bug, ci, github, \u2026)",
+    "manual"
+  ).option("--refs <refs>", "Comma-separated refs (issue, run id, commit)").action((text, options) => {
+    const p = paths(process.cwd());
+    const inbox = new SignalInbox(p.signalsPath);
+    const refs = options.refs ? String(options.refs).split(",").map((r) => r.trim()) : void 0;
+    const s = inbox.add({
+      text,
+      severity: options.severity,
+      source: options.source,
+      ...refs ? { refs } : {}
+    });
+    console.log(
+      chalk.green("\u2713 signal queued"),
+      chalk.dim(s.id.slice(0, 8)),
+      `[${s.severity}]`
+    );
+  });
+  cmd.command("plan").description("Dry-run: show what the loop would do next, without acting").option("--max <n>", "Max ticks to plan (default 1 \u2014 the next action)").action(async (options) => {
+    await runLoop({
+      dryRun: true,
+      max: options.max ? parseInt(options.max, 10) : 1
+    });
+  });
+  cmd.command("run").description(
+    "Run the vision loop (plan-only unless --delegate-cmd is given)"
+  ).option("--once", "Run a single tick").option("--max <n>", "Max ticks this run").option("--dry-run", "Plan without delegating").option(
+    "--delegate-cmd <template>",
+    "Shell command per objective; {{OBJECTIVE}} {{KIND}} {{REFS}} are substituted"
+  ).option("--timeout <sec>", "Per-delegation timeout (seconds)", "1800").action(async (options) => {
+    const dryRun = !!options.dryRun || !options.delegateCmd;
+    if (!options.dryRun && !options.delegateCmd) {
+      console.log(
+        chalk.yellow(
+          `No --delegate-cmd given \u2014 running plan-only. Provide one to act, e.g.:
+  --delegate-cmd 'claude -p "{{OBJECTIVE}}"'`
+        )
+      );
+    }
+    const max = options.once ? 1 : options.max ? parseInt(options.max, 10) : void 0;
+    await runLoop({
+      dryRun,
+      timeoutMs: parseInt(options.timeout, 10) * 1e3,
+      ...max !== void 0 ? { max } : {},
+      ...options.delegateCmd ? { delegateCmd: options.delegateCmd } : {}
+    });
+  });
+  return cmd;
+}
+async function runLoop(opts) {
+  const p = paths(process.cwd());
+  const vision = loadVision(p.visionPath);
+  if (!vision) {
+    console.error(
+      chalk.red("No VISION.md. Run: stackmemory conductor vision init")
+    );
+    process.exit(1);
+  }
+  const ctx = openBrain();
+  try {
+    const delegate = opts.delegateCmd ? shellDelegate(opts.delegateCmd, opts.timeoutMs ?? 18e5) : async (c) => ({
+      success: false,
+      conclusion: `no delegate configured for: ${c.text}`
+    });
+    const loop = new VisionLoop({
+      visionPath: p.visionPath,
+      statePath: p.statePath,
+      signalsPath: p.signalsPath,
+      brain: ctx.store,
+      delegate
+    });
+    console.log(
+      chalk.bold(opts.dryRun ? "Vision plan (dry-run)" : "Vision run")
+    );
+    console.log(
+      chalk.gray("  " + (vision.mission || "(no mission set)")) + "\n"
+    );
+    const result = await loop.run({
+      dryRun: opts.dryRun,
+      ...opts.max !== void 0 ? { maxIterations: opts.max } : {}
+    });
+    for (const d of result.decisions) console.log(fmtDecision(d));
+    console.log(
+      "\n" + chalk.bold("Summary: ") + chalk.green(`${result.delegated} delegated`) + ", " + chalk.gray(`${result.skipped} skipped`) + " \u2014 " + chalk.dim(result.stopped)
+    );
+  } finally {
+    ctx.close();
+  }
+}
+export {
+  createVisionCommand
+};

package/dist/src/cli/gemini-sm.js

@@ -13,6 +13,7 @@ import { program } from "commander";
 import { v4 as uuidv4 } from "uuid";
 import chalk from "chalk";
 import { initializeTracing, trace } from "../core/trace/index.js";
+import { resolveRealCliBin } from "./utils/real-cli-bin.js";
 const DEFAULT_SM_CONFIG = {
   defaultWorktree: false,
   defaultTracing: true
@@ -125,35 +126,24 @@ class GeminiSM {
     }
   }
   resolveGeminiBin() {
-    if (this.config.geminiBin && this.config.geminiBin.trim()) {
-      return this.config.geminiBin.trim();
-    }
-    const envBin = process.env["GEMINI_BIN"];
-    if (envBin && envBin.trim()) return envBin.trim();
-    const possiblePaths = [
-      path.join(
-        os.homedir(),
-        ".nvm",
-        "versions",
-        "node",
-        "v22.22.0",
-        "bin",
-        "gemini"
-      ),
-      "/usr/local/bin/gemini",
-      "/opt/homebrew/bin/gemini"
-    ];
-    for (const binPath of possiblePaths) {
-      if (fs.existsSync(binPath)) {
-        return binPath;
-      }
-    }
-    try {
-      execSync("which gemini", { stdio: "ignore" });
-      return "gemini";
-    } catch {
-    }
-    return null;
+    return resolveRealCliBin({
+      explicitBin: this.config.geminiBin,
+      envBin: process.env["GEMINI_BIN"],
+      preferredPaths: [
+        path.join(
+          os.homedir(),
+          ".nvm",
+          "versions",
+          "node",
+          "v22.22.0",
+          "bin",
+          "gemini"
+        ),
+        "/usr/local/bin/gemini",
+        "/opt/homebrew/bin/gemini"
+      ],
+      pathCommands: ["gemini"]
+    });
   }
   setupWorktree() {
     if (!this.config.useWorktree || !this.isGitRepo()) {

package/dist/src/cli/hermes-sm.js

@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+import { fileURLToPath as __fileURLToPath } from 'url';
+import { dirname as __pathDirname } from 'path';
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __pathDirname(__filename);
+import { spawn, execSync } from "child_process";
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+import { program } from "commander";
+import { v4 as uuidv4 } from "uuid";
+import chalk from "chalk";
+import { initializeTracing, trace } from "../core/trace/index.js";
+import {
+  startDeterminismWatcher,
+  stopDeterminismWatcher
+} from "./utils/determinism-watcher.js";
+import {
+  canonicalStateStore,
+  projectIdFromIdentifier
+} from "../core/shared-state/canonical-store.js";
+const SM_DIR = path.join(os.homedir(), ".stackmemory");
+const HERMES_CONFIG_PATH = path.join(SM_DIR, "hermes-sm.json");
+const DEFAULT_CONFIG = {
+  defaultTracing: true,
+  defaultContext: true
+};
+function loadConfig() {
+  try {
+    if (fs.existsSync(HERMES_CONFIG_PATH)) {
+      return {
+        ...DEFAULT_CONFIG,
+        ...JSON.parse(fs.readFileSync(HERMES_CONFIG_PATH, "utf8"))
+      };
+    }
+  } catch {
+  }
+  return { ...DEFAULT_CONFIG };
+}
+function resolveHermesBin() {
+  const candidates = [
+    path.join(os.homedir(), ".local", "bin", "hermes"),
+    "/usr/local/bin/hermes",
+    "/opt/homebrew/bin/hermes"
+  ];
+  for (const bin of candidates) {
+    if (fs.existsSync(bin)) return bin;
+  }
+  try {
+    const which = execSync("which hermes", { encoding: "utf8" }).trim();
+    if (which) return which;
+  } catch {
+  }
+  throw new Error(
+    "hermes not found. Install: pip install hermes-agent or check ~/.local/bin/hermes"
+  );
+}
+function ensureDaemon() {
+  const pidFile = path.join(SM_DIR, "daemon", "daemon.pid");
+  try {
+    if (fs.existsSync(pidFile)) {
+      const pid = parseInt(fs.readFileSync(pidFile, "utf8").trim(), 10);
+      try {
+        process.kill(pid, 0);
+        return;
+      } catch {
+        fs.unlinkSync(pidFile);
+      }
+    }
+  } catch {
+  }
+  try {
+    execSync("stackmemory daemon start", { stdio: "ignore", timeout: 5e3 });
+    console.log(chalk.dim("  \u21B3 StackMemory daemon started"));
+  } catch {
+  }
+}
+function writeSessionHeartbeat(instanceId) {
+  const sessionsDir = path.join(SM_DIR, "sessions");
+  if (!fs.existsSync(sessionsDir))
+    fs.mkdirSync(sessionsDir, { recursive: true });
+  const heartbeatFile = path.join(
+    sessionsDir,
+    `session-${Date.now()}.heartbeat`
+  );
+  fs.writeFileSync(heartbeatFile, instanceId);
+  const interval = setInterval(() => {
+    try {
+      const now = /* @__PURE__ */ new Date();
+      fs.utimesSync(heartbeatFile, now, now);
+    } catch {
+    }
+  }, 6e4);
+  interval.unref();
+  return interval;
+}
+class HermesSM {
+  config;
+  detWatcher;
+  heartbeatInterval;
+  constructor(config) {
+    this.config = config;
+  }
+  async run() {
+    const { instanceId, tracingEnabled, verboseTracing } = this.config;
+    console.log(chalk.cyan("\u256D\u2500 hermes-sm \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256E"));
+    console.log(
+      chalk.cyan(
+        `\u2502 Instance: ${instanceId.slice(0, 8)}                        \u2502`
+      )
+    );
+    console.log(chalk.cyan("\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256F"));
+    ensureDaemon();
+    if (tracingEnabled) {
+      initializeTracing({
+        serviceName: "hermes-sm",
+        verbose: verboseTracing
+      });
+      trace("session_start", { instanceId, tool: "hermes" });
+    }
+    this.heartbeatInterval = writeSessionHeartbeat(instanceId);
+    if (this.config.contextEnabled) {
+      try {
+        this.detWatcher = startDeterminismWatcher({
+          projectId: projectIdFromIdentifier(process.cwd()),
+          sessionId: instanceId
+        });
+      } catch {
+      }
+    }
+    let handoffContext = "";
+    if (this.config.contextEnabled) {
+      try {
+        const projectId = projectIdFromIdentifier(process.cwd());
+        const store = canonicalStateStore();
+        const handoff = store.getLatestHandoff(projectId);
+        if (handoff) {
+          handoffContext = handoff.content || "";
+          console.log(
+            chalk.dim(
+              `  \u21B3 Restored handoff: ${handoff.summary?.slice(0, 60) || "previous session"}`
+            )
+          );
+        }
+      } catch {
+      }
+    }
+    const hermesBin = this.config.hermesBin || resolveHermesBin();
+    const args = [];
+    if (this.config.resume) {
+      args.push("--resume", this.config.resume);
+    } else if (this.config.task) {
+      args.push("-z", this.config.task);
+    }
+    if (this.config.model) {
+      args.push("-m", this.config.model);
+    }
+    if (this.config.provider) {
+      args.push("--provider", this.config.provider);
+    }
+    args.push("--pass-session-id");
+    const env = {
+      ...process.env,
+      STACKMEMORY_SESSION: instanceId,
+      STACKMEMORY_TOOL: "hermes",
+      STACKMEMORY_PROJECT: process.cwd()
+    };
+    if (handoffContext) {
+      env.HERMES_SYSTEM_PREFIX = handoffContext.slice(0, 2e3);
+    }
+    console.log(chalk.dim(`  \u21B3 ${hermesBin} ${args.join(" ")}`));
+    const child = spawn(hermesBin, args, {
+      stdio: "inherit",
+      env,
+      cwd: process.cwd()
+    });
+    child.on("exit", (code) => {
+      this.cleanup();
+      if (tracingEnabled) {
+        trace("session_end", {
+          instanceId,
+          exitCode: code,
+          duration: Date.now() - this.config.sessionStartTime
+        });
+      }
+      process.exit(code || 0);
+    });
+    const handleSignal = (signal) => {
+      child.kill(signal);
+    };
+    process.on("SIGINT", () => handleSignal("SIGINT"));
+    process.on("SIGTERM", () => handleSignal("SIGTERM"));
+  }
+  cleanup() {
+    if (this.detWatcher) {
+      stopDeterminismWatcher(this.detWatcher);
+    }
+    if (this.heartbeatInterval) {
+      clearInterval(this.heartbeatInterval);
+    }
+  }
+}
+const smConfig = loadConfig();
+program.name("hermes-smd").description(
+  "Hermes with StackMemory context persistence, daemon auto-start, and desire-path tracking"
+).argument("[prompt...]", "Initial prompt for hermes").option("--resume <session>", "Resume a Hermes session by ID").option("-m, --model <model>", "Model to use").option("--provider <provider>", "Model provider").option("--no-context", "Disable context persistence").option("--no-tracing", "Disable tracing").option("--verbose-trace", "Verbose tracing output").option("--hermes-bin <path>", "Path to hermes binary").action(async (prompt, options) => {
+  const instanceId = uuidv4();
+  const task = prompt.length > 0 ? prompt.join(" ") : void 0;
+  const config = {
+    instanceId,
+    contextEnabled: options.context !== false && smConfig.defaultContext,
+    task,
+    tracingEnabled: options.tracing !== false && smConfig.defaultTracing,
+    verboseTracing: options.verboseTrace || false,
+    hermesBin: options.hermesBin,
+    sessionStartTime: Date.now(),
+    model: options.model,
+    provider: options.provider,
+    resume: options.resume
+  };
+  const sm = new HermesSM(config);
+  await sm.run();
+});
+program.parse();