@stackmemoryai/stackmemory 1.10.4 → 1.12.0

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

@@ -13,6 +13,11 @@ 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";
+import {
+  startDeterminismWatcher,
+  stopDeterminismWatcher
+} from "./utils/determinism-watcher.js";
 const DEFAULT_SM_CONFIG = {
   defaultWorktree: false,
   defaultTracing: true
@@ -43,6 +48,7 @@ class OpencodeSM {
   config;
   stackmemoryPath;
   smConfig;
+  determinismWatcher;
   constructor() {
     this.smConfig = loadSMConfig();
     this.config = {
@@ -54,6 +60,7 @@ class OpencodeSM {
       sessionStartTime: Date.now()
     };
     this.stackmemoryPath = this.findStackMemory();
+    this.determinismWatcher = null;
   }
   getRepoRoot() {
     try {
@@ -127,27 +134,16 @@ class OpencodeSM {
     }
   }
   resolveOpencodeBin() {
-    if (this.config.opencodeBin && this.config.opencodeBin.trim()) {
-      return this.config.opencodeBin.trim();
-    }
-    const envBin = process.env["OPENCODE_BIN"];
-    if (envBin && envBin.trim()) return envBin.trim();
-    const possiblePaths = [
-      path.join(os.homedir(), ".opencode", "bin", "opencode"),
-      "/usr/local/bin/opencode",
-      "/opt/homebrew/bin/opencode"
-    ];
-    for (const binPath of possiblePaths) {
-      if (fs.existsSync(binPath)) {
-        return binPath;
-      }
-    }
-    try {
-      execSync("which opencode", { stdio: "ignore" });
-      return "opencode";
-    } catch {
-    }
-    return null;
+    return resolveRealCliBin({
+      explicitBin: this.config.opencodeBin,
+      envBin: process.env["OPENCODE_BIN"],
+      preferredPaths: [
+        path.join(os.homedir(), ".opencode", "bin", "opencode"),
+        "/usr/local/bin/opencode",
+        "/opt/homebrew/bin/opencode"
+      ],
+      pathCommands: ["opencode"]
+    });
   }
   setupWorktree() {
     if (!this.config.useWorktree || !this.isGitRepo()) {
@@ -251,6 +247,23 @@ class OpencodeSM {
       );
     }
   }
+  startDeterminismWatcher() {
+    this.determinismWatcher = startDeterminismWatcher({
+      stackmemoryBin: this.stackmemoryPath,
+      cwd: process.cwd(),
+      task: this.config.task,
+      instanceId: this.config.instanceId,
+      tool: "opencode"
+    });
+    if (this.determinismWatcher) {
+      const modeLabel = this.determinismWatcher.mode === "targeted" ? "targeted" : "repo-root fallback";
+      console.log(chalk.gray(`Determinism: ${modeLabel}`));
+    }
+  }
+  stopDeterminismWatcher() {
+    stopDeterminismWatcher(this.determinismWatcher);
+    this.determinismWatcher = null;
+  }
   async run(args) {
     const opencodeArgs = [];
     let i = 0;
@@ -354,6 +367,7 @@ class OpencodeSM {
     if (this.config.worktreePath) {
       process.env["OPENCODE_WORKTREE_PATH"] = this.config.worktreePath;
     }
+    this.startDeterminismWatcher();
     console.log(chalk.gray(`Instance: ${this.config.instanceId}`));
     console.log(chalk.gray(`Working in: ${process.cwd()}`));
     if (this.config.tracingEnabled) {
@@ -391,6 +405,7 @@ class OpencodeSM {
       process.exit(1);
     });
     opencode.on("exit", async (code) => {
+      this.stopDeterminismWatcher();
       this.saveContext("OpenCode session ended", {
         action: "session_end",
         exitCode: code
@@ -411,12 +426,14 @@ class OpencodeSM {
       process.exit(code || 0);
     });
     process.on("SIGINT", () => {
+      this.stopDeterminismWatcher();
       this.saveContext("OpenCode session interrupted", {
         action: "session_interrupt"
       });
       opencode.kill("SIGINT");
     });
     process.on("SIGTERM", () => {
+      this.stopDeterminismWatcher();
       this.saveContext("OpenCode session terminated", {
         action: "session_terminate"
       });

package/dist/src/cli/utils/determinism-watcher.js

@@ -0,0 +1,66 @@
+import { fileURLToPath as __fileURLToPath } from 'url';
+import { dirname as __pathDirname } from 'path';
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __pathDirname(__filename);
+import { spawn } from "child_process";
+import * as fs from "fs";
+import * as path from "path";
+import { getDeterminismWatchTargets } from "../../orchestrators/multimodal/determinism.js";
+function shouldAutoStartDeterminismWatcher(cwd) {
+  if (process.env["STACKMEMORY_DETERMINISM_AUTO"] === "0") {
+    return false;
+  }
+  return fs.existsSync(path.join(cwd, ".git"));
+}
+function startDeterminismWatcher(options) {
+  if (!shouldAutoStartDeterminismWatcher(options.cwd)) {
+    return null;
+  }
+  const runs = process.env["STACKMEMORY_DETERMINISM_RUNS"] || "3";
+  const task = options.task || process.env["STACKMEMORY_DETERMINISM_TASK"] || "Determinism probe";
+  const targets = getDeterminismWatchTargets(options.cwd);
+  const mode = targets.length === 1 && targets[0] === "." ? "repo-root" : "targeted";
+  const child = spawn(
+    options.stackmemoryBin,
+    [
+      "bench",
+      "determinism",
+      "--task",
+      task,
+      "--runs",
+      runs,
+      "--watch",
+      "--json"
+    ],
+    {
+      cwd: options.cwd,
+      stdio: "ignore",
+      env: {
+        ...process.env,
+        STACKMEMORY_DETERMINISM_PARENT_TOOL: options.tool,
+        STACKMEMORY_DETERMINISM_PARENT_INSTANCE: options.instanceId || "",
+        STACKMEMORY_DETERMINISM_PARENT_SESSION: options.sessionId || ""
+      }
+    }
+  );
+  return {
+    child,
+    mode,
+    targets
+  };
+}
+function stopDeterminismWatcher(handle) {
+  const child = handle?.child ?? null;
+  if (!child || child.killed) {
+    return;
+  }
+  try {
+    child.kill("SIGTERM");
+  } catch {
+  }
+}
+export {
+  shouldAutoStartDeterminismWatcher,
+  startDeterminismWatcher,
+  stopDeterminismWatcher
+};

package/dist/src/cli/utils/real-cli-bin.js

@@ -0,0 +1,44 @@
+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 * as fs from "fs";
+const DEFAULT_WRAPPER_PATH_SNIPPETS = [
+  "/Applications/cmux.app/Contents/Resources/bin/"
+];
+function isWrapperPath(candidate, wrapperPathSnippets) {
+  const normalized = candidate.trim();
+  return wrapperPathSnippets.some((snippet) => normalized.includes(snippet));
+}
+function resolveRealCliBin(options) {
+  if (options.explicitBin?.trim()) {
+    return options.explicitBin.trim();
+  }
+  if (options.envBin?.trim()) {
+    return options.envBin.trim();
+  }
+  const wrapperPathSnippets = options.wrapperPathSnippets || DEFAULT_WRAPPER_PATH_SNIPPETS;
+  for (const candidate of options.preferredPaths || []) {
+    if (fs.existsSync(candidate) && !isWrapperPath(candidate, wrapperPathSnippets)) {
+      return candidate;
+    }
+  }
+  for (const command of options.pathCommands) {
+    try {
+      const output = execSync(`which -a ${command}`, {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"]
+      });
+      const resolved = output.split("\n").map((line) => line.trim()).filter(Boolean).find((candidate) => !isWrapperPath(candidate, wrapperPathSnippets));
+      if (resolved) {
+        return resolved;
+      }
+    } catch {
+    }
+  }
+  return null;
+}
+export {
+  resolveRealCliBin
+};

package/dist/src/core/cache/content-cache.js

@@ -0,0 +1,238 @@
+import { fileURLToPath as __fileURLToPath } from 'url';
+import { dirname as __pathDirname } from 'path';
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __pathDirname(__filename);
+import { logger } from "../monitoring/logger.js";
+import { estimateTokens, hashContent } from "./token-estimator.js";
+class ContentCache {
+  db;
+  constructor(db) {
+    this.db = db;
+    this.initializeSchema();
+  }
+  // ------------------------------------------------------------------
+  // Schema
+  // ------------------------------------------------------------------
+  initializeSchema() {
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS content_cache (
+        hash TEXT PRIMARY KEY,
+        content TEXT NOT NULL,
+        token_count INTEGER NOT NULL,
+        hit_count INTEGER NOT NULL DEFAULT 0,
+        first_seen INTEGER NOT NULL,
+        last_seen INTEGER NOT NULL,
+        source TEXT NOT NULL DEFAULT '',
+        metadata TEXT
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_cache_source ON content_cache(source);
+      CREATE INDEX IF NOT EXISTS idx_cache_last_seen ON content_cache(last_seen);
+    `);
+    const hasFts = this.db.prepare(
+      `SELECT name FROM sqlite_master WHERE type='table' AND name='content_cache_fts'`
+    ).get();
+    if (!hasFts) {
+      this.db.exec(`
+        CREATE VIRTUAL TABLE content_cache_fts
+        USING fts5(content, hash UNINDEXED, content_rowid='rowid');
+      `);
+    }
+    logger.debug("ContentCache: schema initialized");
+  }
+  // ------------------------------------------------------------------
+  // Core operations
+  // ------------------------------------------------------------------
+  /**
+   * Look up content by hash. If it exists, increments hit_count and
+   * returns the saved tokens. Otherwise returns a miss.
+   */
+  lookup(content, source) {
+    const hash = hashContent(content);
+    const row = this.db.prepare("SELECT * FROM content_cache WHERE hash = ?").get(hash);
+    if (!row) {
+      return { hit: false, hash, tokensSaved: 0 };
+    }
+    const now = Math.floor(Date.now() / 1e3);
+    this.db.prepare(
+      "UPDATE content_cache SET hit_count = hit_count + 1, last_seen = ? WHERE hash = ?"
+    ).run(now, hash);
+    if (source && source !== row.source) {
+      this.db.prepare("UPDATE content_cache SET source = ? WHERE hash = ?").run(source, hash);
+    }
+    const entry = this.rowToEntry({
+      ...row,
+      hit_count: row.hit_count + 1,
+      last_seen: now,
+      source: source ?? row.source
+    });
+    return {
+      hit: true,
+      hash,
+      entry,
+      tokensSaved: entry.tokenCount
+    };
+  }
+  /**
+   * Insert or update a cache entry. Returns the entry.
+   */
+  put(content, source, metadata) {
+    const hash = hashContent(content);
+    const tokenCount = estimateTokens(content);
+    const now = Math.floor(Date.now() / 1e3);
+    const src = source ?? "";
+    const meta = metadata ? JSON.stringify(metadata) : null;
+    const existing = this.db.prepare("SELECT hash FROM content_cache WHERE hash = ?").get(hash);
+    if (existing) {
+      this.db.prepare(
+        "UPDATE content_cache SET hit_count = hit_count + 1, last_seen = ?, source = ?, metadata = ? WHERE hash = ?"
+      ).run(now, src, meta, hash);
+    } else {
+      this.db.prepare(
+        `INSERT INTO content_cache (hash, content, token_count, hit_count, first_seen, last_seen, source, metadata)
+           VALUES (?, ?, ?, 0, ?, ?, ?, ?)`
+      ).run(hash, content, tokenCount, now, now, src, meta);
+      this.db.prepare(`INSERT INTO content_cache_fts (content, hash) VALUES (?, ?)`).run(content, hash);
+    }
+    return this.getEntry(hash);
+  }
+  /**
+   * Retrieve a single entry by hash.
+   */
+  getEntry(hash) {
+    const row = this.db.prepare("SELECT * FROM content_cache WHERE hash = ?").get(hash);
+    return row ? this.rowToEntry(row) : void 0;
+  }
+  /**
+   * Aggregate cache statistics.
+   */
+  getStats() {
+    const agg = this.db.prepare(
+      `SELECT
+           COUNT(*) as total_entries,
+           COALESCE(SUM(token_count), 0) as total_tokens_cached,
+           COALESCE(SUM(hit_count * token_count), 0) as total_tokens_saved,
+           COALESCE(SUM(hit_count), 0) as total_hits,
+           COUNT(*) as total_lookups
+         FROM content_cache`
+    ).get();
+    const totalHits = agg.total_hits;
+    const totalEntries = agg.total_entries;
+    const hitRate = totalHits + totalEntries > 0 ? totalHits / (totalHits + totalEntries) : 0;
+    const topRows = this.db.prepare(
+      `SELECT source, SUM(hit_count * token_count) as tokens_saved
+         FROM content_cache
+         WHERE source != ''
+         GROUP BY source
+         ORDER BY tokens_saved DESC
+         LIMIT 10`
+    ).all();
+    return {
+      totalEntries,
+      totalTokensCached: agg.total_tokens_cached,
+      totalTokensSaved: agg.total_tokens_saved,
+      hitRate,
+      topSources: topRows.map((r) => ({
+        source: r.source,
+        tokensSaved: r.tokens_saved
+      }))
+    };
+  }
+  /**
+   * Remove entries older than the given unix timestamp.
+   * Returns the number of evicted entries.
+   */
+  evict(olderThan) {
+    const cutoff = olderThan ?? Math.floor(Date.now() / 1e3);
+    this.db.prepare(
+      `DELETE FROM content_cache_fts
+         WHERE hash IN (SELECT hash FROM content_cache WHERE last_seen < ?)`
+    ).run(cutoff);
+    const result = this.db.prepare("DELETE FROM content_cache WHERE last_seen < ?").run(cutoff);
+    if (result.changes > 0) {
+      logger.debug(`ContentCache: evicted ${result.changes} entries`);
+    }
+    return result.changes;
+  }
+  /**
+   * Search cached content via FTS5.
+   */
+  search(query, limit = 20) {
+    if (!query.trim()) return [];
+    const sanitized = this.sanitizeFtsQuery(query);
+    const rows = this.db.prepare(
+      `SELECT cc.*
+         FROM content_cache_fts fts
+         JOIN content_cache cc ON cc.hash = fts.hash
+         WHERE content_cache_fts MATCH ?
+         LIMIT ?`
+    ).all(sanitized, limit);
+    return rows.map((r) => this.rowToEntry(r));
+  }
+  /**
+   * Remove all entries.
+   */
+  clear() {
+    this.db.exec("DELETE FROM content_cache_fts");
+    this.db.exec("DELETE FROM content_cache");
+    logger.debug("ContentCache: cleared");
+  }
+  // ------------------------------------------------------------------
+  // Key-based operations (for input-addressed caching, e.g., tool+args → result)
+  // ------------------------------------------------------------------
+  /**
+   * Look up cached result by an explicit key (e.g., "tool:args-hash").
+   * The key is hashed to produce the cache entry hash.
+   */
+  lookupByKey(key, source) {
+    return this.lookup(key, source);
+  }
+  /**
+   * Store a result under an explicit key.
+   * The key is hashed for addressing; the value is stored as content.
+   */
+  putByKey(key, value, source, metadata) {
+    const hash = hashContent(key);
+    const tokenCount = estimateTokens(value);
+    const now = Math.floor(Date.now() / 1e3);
+    const src = source ?? "";
+    const meta = metadata ? JSON.stringify(metadata) : null;
+    const existing = this.db.prepare("SELECT hash FROM content_cache WHERE hash = ?").get(hash);
+    if (existing) {
+      this.db.prepare(
+        "UPDATE content_cache SET content = ?, token_count = ?, hit_count = hit_count + 1, last_seen = ?, source = ?, metadata = ? WHERE hash = ?"
+      ).run(value, tokenCount, now, src, meta, hash);
+    } else {
+      this.db.prepare(
+        `INSERT INTO content_cache (hash, content, token_count, hit_count, first_seen, last_seen, source, metadata)
+           VALUES (?, ?, ?, 0, ?, ?, ?, ?)`
+      ).run(hash, value, tokenCount, now, now, src, meta);
+      this.db.prepare(`INSERT INTO content_cache_fts (content, hash) VALUES (?, ?)`).run(value, hash);
+    }
+    return this.getEntry(hash);
+  }
+  // ------------------------------------------------------------------
+  // Helpers
+  // ------------------------------------------------------------------
+  rowToEntry(row) {
+    return {
+      hash: row.hash,
+      content: row.content,
+      tokenCount: row.token_count,
+      hitCount: row.hit_count,
+      firstSeen: row.first_seen,
+      lastSeen: row.last_seen,
+      source: row.source,
+      metadata: row.metadata ? JSON.parse(row.metadata) : void 0
+    };
+  }
+  sanitizeFtsQuery(query) {
+    const cleaned = query.replace(/['"()*~^{}\[\]]/g, "");
+    const terms = cleaned.split(/\s+/).filter((t) => t && !/^(AND|OR|NOT|NEAR)$/i.test(t));
+    if (terms.length === 0) return '""';
+    return terms.map((t) => `"${t}"`).join(" ");
+  }
+}
+export {
+  ContentCache
+};

package/dist/src/core/cache/index.js

@@ -0,0 +1,11 @@
+import { fileURLToPath as __fileURLToPath } from 'url';
+import { dirname as __pathDirname } from 'path';
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __pathDirname(__filename);
+import { ContentCache } from "./content-cache.js";
+import { estimateTokens, hashContent } from "./token-estimator.js";
+export {
+  ContentCache,
+  estimateTokens,
+  hashContent
+};

package/dist/src/core/cache/token-estimator.js

@@ -0,0 +1,16 @@
+import { fileURLToPath as __fileURLToPath } from 'url';
+import { dirname as __pathDirname } from 'path';
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __pathDirname(__filename);
+import { createHash } from "crypto";
+function estimateTokens(content) {
+  if (!content) return 0;
+  return Math.ceil(content.length / 4);
+}
+function hashContent(content) {
+  return createHash("sha256").update(content).digest("hex");
+}
+export {
+  estimateTokens,
+  hashContent
+};

package/dist/src/core/context/frame-database.js

@@ -97,6 +97,26 @@ class FrameDatabase {
         );
       } catch {
       }
+      const provenanceCols = [
+        { table: "frames", col: "prov_source", def: "TEXT DEFAULT ''" },
+        { table: "frames", col: "prov_derivation", def: "TEXT DEFAULT '[]'" },
+        { table: "frames", col: "prov_confidence", def: "REAL DEFAULT 1.0" },
+        { table: "frames", col: "prov_superseded_by", def: "TEXT" },
+        {
+          table: "frames",
+          col: "prov_program_version",
+          def: "TEXT DEFAULT ''"
+        },
+        { table: "anchors", col: "prov_source", def: "TEXT DEFAULT ''" },
+        { table: "anchors", col: "prov_confidence", def: "REAL DEFAULT 1.0" },
+        { table: "anchors", col: "prov_superseded_by", def: "TEXT" }
+      ];
+      for (const { table, col, def } of provenanceCols) {
+        try {
+          this.db.exec(`ALTER TABLE ${table} ADD COLUMN ${col} ${def}`);
+        } catch {
+        }
+      }
       this.db.exec(`
         CREATE INDEX IF NOT EXISTS idx_frames_run ON frames(run_id);
         CREATE INDEX IF NOT EXISTS idx_frames_project ON frames(project_id);
@@ -188,30 +208,6 @@ class FrameDatabase {
         CREATE INDEX IF NOT EXISTS idx_entity_temporal
           ON entity_states(entity_name, valid_from DESC);
       `);
-      this.db.exec(`
-        CREATE TABLE IF NOT EXISTS cord_tasks (
-          task_id TEXT PRIMARY KEY,
-          parent_id TEXT,
-          project_id TEXT NOT NULL,
-          run_id TEXT NOT NULL,
-          goal TEXT NOT NULL,
-          prompt TEXT NOT NULL DEFAULT '',
-          result TEXT,
-          status TEXT NOT NULL DEFAULT 'pending'
-            CHECK (status IN ('pending','active','completed','blocked','asked')),
-          context_mode TEXT NOT NULL DEFAULT 'spawn'
-            CHECK (context_mode IN ('spawn','fork','ask')),
-          blocked_by TEXT NOT NULL DEFAULT '[]',
-          depth INTEGER NOT NULL DEFAULT 0,
-          created_at INTEGER NOT NULL DEFAULT (unixepoch()),
-          completed_at INTEGER,
-          FOREIGN KEY (parent_id) REFERENCES cord_tasks(task_id)
-        );
-        CREATE INDEX IF NOT EXISTS idx_cord_tasks_project ON cord_tasks(project_id);
-        CREATE INDEX IF NOT EXISTS idx_cord_tasks_parent ON cord_tasks(parent_id);
-        CREATE INDEX IF NOT EXISTS idx_cord_tasks_status ON cord_tasks(status);
-        CREATE INDEX IF NOT EXISTS idx_cord_tasks_project_status ON cord_tasks(project_id, status);
-      `);
       logger.info("Frame database schema initialized");
     } catch (error) {
       throw new DatabaseError(
@@ -228,8 +224,8 @@ class FrameDatabase {
   insertFrame(frame) {
     try {
       const stmt = this.db.prepare(`
-        INSERT INTO frames (frame_id, run_id, project_id, parent_frame_id, depth, type, name, state, inputs, outputs, digest_json)
-        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        INSERT INTO frames (frame_id, run_id, project_id, parent_frame_id, depth, type, name, state, inputs, outputs, digest_json, prov_source, prov_derivation, prov_confidence, prov_program_version)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
       `);
       const result = stmt.run(
         frame.frame_id,
@@ -242,7 +238,15 @@ class FrameDatabase {
         frame.state,
         JSON.stringify(frame.inputs),
         JSON.stringify(frame.outputs),
-        JSON.stringify(frame.digest_json)
+        JSON.stringify(frame.digest_json),
+        frame.type,
+        // prov_source: frame type as source
+        JSON.stringify([`frame:${frame.type}`]),
+        // prov_derivation
+        1,
+        // prov_confidence: default full confidence
+        process.env["npm_package_version"] || ""
+        // prov_program_version
       );
       if (result.changes === 0) {
         throw new DatabaseError(
@@ -473,8 +477,8 @@ class FrameDatabase {
   insertAnchor(anchor) {
     try {
       const stmt = this.db.prepare(`
-        INSERT INTO anchors (anchor_id, frame_id, project_id, type, text, priority, metadata)
-        VALUES (?, ?, ?, ?, ?, ?, ?)
+        INSERT INTO anchors (anchor_id, frame_id, project_id, type, text, priority, metadata, prov_source, prov_confidence)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
       `);
       const result = stmt.run(
         anchor.anchor_id,
@@ -483,7 +487,11 @@ class FrameDatabase {
         anchor.type,
         anchor.text,
         anchor.priority,
-        JSON.stringify(anchor.metadata)
+        JSON.stringify(anchor.metadata),
+        anchor.type,
+        // prov_source: anchor type (DECISION, EVENT, etc.)
+        1
+        // prov_confidence: default full confidence
       );
       if (result.changes === 0) {
         throw new DatabaseError(