@stackmemoryai/stackmemory 1.12.0 → 1.14.0

package/dist/src/core/tasks/md-task-parser.js

@@ -0,0 +1,138 @@
+import { fileURLToPath as __fileURLToPath } from 'url';
+import { dirname as __pathDirname } from 'path';
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __pathDirname(__filename);
+import { readFileSync, writeFileSync } from "fs";
+const HEADER_RE = /^\|\s*id\s*\|/i;
+const SEPARATOR_RE = /^\|[\s-|]+\|$/;
+const PRIORITIES = ["P0", "P1", "P2", "P3"];
+const STATUSES = ["todo", "active", "done", "blocked", "cut"];
+const SYNCS = ["local", "linear", "gh"];
+function parseMasterTasks(content) {
+  const lines = content.split("\n");
+  const tasks = [];
+  let inTable = false;
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("|")) {
+      if (inTable) break;
+      continue;
+    }
+    if (HEADER_RE.test(trimmed)) {
+      inTable = true;
+      continue;
+    }
+    if (SEPARATOR_RE.test(trimmed)) continue;
+    if (!inTable) continue;
+    const cells = trimmed.split("|").slice(1, -1).map((c) => c.trim());
+    if (cells.length < 8) continue;
+    const [id, priority, status, owner, sync, task, branchPr, notes] = cells;
+    if (!id || !PRIORITIES.includes(priority)) continue;
+    tasks.push({
+      id,
+      priority,
+      status: STATUSES.includes(status) ? status : "todo",
+      owner: owner || "@me",
+      sync: SYNCS.includes(sync) ? sync : "local",
+      task: task || "",
+      branchPr: branchPr || "",
+      notes: notes || ""
+    });
+  }
+  return tasks;
+}
+function serializeTaskRows(tasks) {
+  return tasks.map(
+    (t) => `| ${t.id} | ${t.priority} | ${t.status} | ${t.owner} | ${t.sync} | ${t.task} | ${t.branchPr} | ${t.notes} |`
+  ).join("\n");
+}
+function updateTaskInFile(filePath, taskId, updates) {
+  const content = readFileSync(filePath, "utf-8");
+  const lines = content.split("\n");
+  let found = false;
+  const updated = lines.map((line) => {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("|") || HEADER_RE.test(trimmed) || SEPARATOR_RE.test(trimmed)) {
+      return line;
+    }
+    const cells = trimmed.split("|").slice(1, -1).map((c) => c.trim());
+    if (cells.length < 8 || cells[0] !== taskId) return line;
+    found = true;
+    const task = {
+      id: cells[0],
+      priority: updates.priority ?? cells[1],
+      status: updates.status ?? cells[2],
+      owner: updates.owner ?? cells[3],
+      sync: updates.sync ?? cells[4],
+      task: updates.task ?? cells[5],
+      branchPr: updates.branchPr ?? cells[6],
+      notes: updates.notes ?? cells[7]
+    };
+    return `| ${task.id} | ${task.priority} | ${task.status} | ${task.owner} | ${task.sync} | ${task.task} | ${task.branchPr} | ${task.notes} |`;
+  });
+  if (!found) throw new Error(`Task ${taskId} not found in ${filePath}`);
+  writeFileSync(filePath, updated.join("\n"), "utf-8");
+}
+function addTaskToFile(filePath, task) {
+  const content = readFileSync(filePath, "utf-8");
+  const existing = parseMasterTasks(content);
+  const maxNum = existing.reduce((max, t) => {
+    const n = parseInt(t.id.replace(/^T/, ""), 10);
+    return isNaN(n) ? max : Math.max(max, n);
+  }, 0);
+  const id = `T${String(maxNum + 1).padStart(2, "0")}`;
+  const newRow = `| ${id} | ${task.priority} | ${task.status} | ${task.owner} | ${task.sync} | ${task.task} | ${task.branchPr} | ${task.notes} |`;
+  const lines = content.split("\n");
+  let insertIdx = -1;
+  let inTable = false;
+  for (let i = 0; i < lines.length; i++) {
+    const trimmed = lines[i].trim();
+    if (HEADER_RE.test(trimmed)) {
+      inTable = true;
+      continue;
+    }
+    if (inTable && trimmed.startsWith("|") && !SEPARATOR_RE.test(trimmed)) {
+      insertIdx = i;
+    }
+    if (inTable && !trimmed.startsWith("|") && trimmed !== "") {
+      break;
+    }
+  }
+  if (insertIdx === -1) {
+    for (let i = 0; i < lines.length; i++) {
+      if (SEPARATOR_RE.test(lines[i].trim())) {
+        insertIdx = i;
+        break;
+      }
+    }
+  }
+  lines.splice(insertIdx + 1, 0, newRow);
+  writeFileSync(filePath, lines.join("\n"), "utf-8");
+  return id;
+}
+function getNextTask(tasks) {
+  const actionable = tasks.filter(
+    (t) => t.status === "todo" || t.status === "active"
+  );
+  if (actionable.length === 0) return void 0;
+  const ownerRank = {
+    "@agent": 0,
+    "@me": 1,
+    "@defer": 2
+  };
+  actionable.sort((a, b) => {
+    const pDiff = PRIORITIES.indexOf(a.priority) - PRIORITIES.indexOf(b.priority);
+    if (pDiff !== 0) return pDiff;
+    const aRank = ownerRank[a.owner] ?? 1;
+    const bRank = ownerRank[b.owner] ?? 1;
+    return aRank - bRank;
+  });
+  return actionable[0];
+}
+export {
+  addTaskToFile,
+  getNextTask,
+  parseMasterTasks,
+  serializeTaskRows,
+  updateTaskInFile
+};

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

@@ -0,0 +1,27 @@
+import { fileURLToPath as __fileURLToPath } from 'url';
+import { dirname as __pathDirname } from 'path';
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __pathDirname(__filename);
+export * from "./types.js";
+import {
+  parseVision,
+  loadVision,
+  setObjectiveDone,
+  scaffoldVision,
+  objectiveId,
+  VISION_TEMPLATE
+} from "./vision-file.js";
+import { SignalInbox } from "./signals.js";
+import {
+  VisionLoop
+} from "./vision-loop.js";
+export {
+  SignalInbox,
+  VISION_TEMPLATE,
+  VisionLoop,
+  loadVision,
+  objectiveId,
+  parseVision,
+  scaffoldVision,
+  setObjectiveDone
+};

package/dist/src/core/vision/signals.js

@@ -0,0 +1,79 @@
+import { fileURLToPath as __fileURLToPath } from 'url';
+import { dirname as __pathDirname } from 'path';
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __pathDirname(__filename);
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  appendFileSync
+} from "fs";
+import { dirname } from "path";
+import { randomUUID } from "crypto";
+class SignalInbox {
+  constructor(path) {
+    this.path = path;
+  }
+  ensureDir() {
+    const dir = dirname(this.path);
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  }
+  add(input) {
+    this.ensureDir();
+    const signal = {
+      id: randomUUID(),
+      source: input.source ?? "manual",
+      severity: input.severity ?? "medium",
+      text: input.text,
+      createdAt: Date.now(),
+      ...input.refs ? { refs: input.refs } : {}
+    };
+    appendFileSync(this.path, JSON.stringify(signal) + "\n");
+    return signal;
+  }
+  all() {
+    if (!existsSync(this.path)) return [];
+    return readFileSync(this.path, "utf-8").split(/\r?\n/).filter(Boolean).map((l) => {
+      try {
+        return JSON.parse(l);
+      } catch {
+        return null;
+      }
+    }).filter((s) => !!s);
+  }
+  /** Unresolved signals, most severe + oldest first. */
+  pending() {
+    const rank = {
+      low: 1,
+      medium: 2,
+      high: 3,
+      critical: 4
+    };
+    return this.all().filter((s) => !s.resolvedAt).sort(
+      (a, b) => rank[b.severity] - rank[a.severity] || a.createdAt - b.createdAt
+    );
+  }
+  /** Rewrite the file marking a signal resolved (compacts the log). */
+  resolve(id) {
+    const signals = this.all();
+    let changed = false;
+    for (const s of signals) {
+      if (s.id === id && !s.resolvedAt) {
+        s.resolvedAt = Date.now();
+        changed = true;
+      }
+    }
+    if (changed) {
+      this.ensureDir();
+      writeFileSync(
+        this.path,
+        signals.map((s) => JSON.stringify(s)).join("\n") + "\n"
+      );
+    }
+    return changed;
+  }
+}
+export {
+  SignalInbox
+};

package/dist/src/core/vision/types.js

@@ -0,0 +1,22 @@
+import { fileURLToPath as __fileURLToPath } from 'url';
+import { dirname as __pathDirname } from 'path';
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __pathDirname(__filename);
+const DEFAULT_LIMITS = {
+  maxIterations: 10,
+  maxIterationsPerDay: 50,
+  maxConsecutiveFailures: 3,
+  tickIntervalSec: 60,
+  requireApproval: false,
+  stopWhenComplete: true
+};
+const SEVERITY_RANK = {
+  low: 1,
+  medium: 2,
+  high: 3,
+  critical: 4
+};
+export {
+  DEFAULT_LIMITS,
+  SEVERITY_RANK
+};

package/dist/src/core/vision/vision-file.js

@@ -0,0 +1,146 @@
+import { fileURLToPath as __fileURLToPath } from 'url';
+import { dirname as __pathDirname } from 'path';
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __pathDirname(__filename);
+import { existsSync, readFileSync, writeFileSync } from "fs";
+import { createHash } from "crypto";
+import {
+  DEFAULT_LIMITS
+} from "./types.js";
+function objectiveId(text) {
+  return createHash("sha1").update(text.trim()).digest("hex").slice(0, 10);
+}
+function splitSections(text) {
+  const lines = text.split(/\r?\n/);
+  const sections = /* @__PURE__ */ new Map();
+  const preamble = [];
+  let current = null;
+  for (const line of lines) {
+    const h2 = line.match(/^##\s+(.+?)\s*$/);
+    if (h2?.[1]) {
+      current = { body: [] };
+      sections.set(h2[1].toLowerCase(), current);
+      continue;
+    }
+    if (/^#\s+/.test(line)) continue;
+    if (current) {
+      current.body.push(line);
+    } else {
+      preamble.push(line);
+    }
+  }
+  return { preamble, sections };
+}
+function bulletLines(body) {
+  return body.map((l) => l.match(/^\s*[-*]\s+(.*\S)\s*$/)?.[1]?.trim()).filter((s) => !!s).filter((s) => !/^\[[ xX]\]/.test(s));
+}
+function parseObjectives(body) {
+  const objectives = [];
+  for (const line of body) {
+    const m = line.match(/^\s*[-*]\s+\[([ xX])\]\s+(.*\S)\s*$/);
+    if (!m?.[2]) continue;
+    const text = m[2].trim();
+    objectives.push({
+      id: objectiveId(text),
+      text,
+      done: (m[1] ?? "").toLowerCase() === "x"
+    });
+  }
+  return objectives;
+}
+function parseLimits(body) {
+  const limits = { ...DEFAULT_LIMITS };
+  for (const line of body) {
+    const m = line.match(/^\s*([a-zA-Z]+)\s*:\s*(.+?)\s*$/);
+    if (!m?.[1] || m[2] === void 0) continue;
+    const key = m[1];
+    const raw = m[2];
+    if (!(key in limits)) continue;
+    if (key === "requireApproval" || key === "stopWhenComplete") {
+      limits[key] = /^(true|yes|1)$/i.test(raw);
+    } else {
+      const n = parseInt(raw, 10);
+      if (Number.isFinite(n)) limits[key] = n;
+    }
+  }
+  return limits;
+}
+function parseVision(text) {
+  const { preamble, sections } = splitSections(text);
+  const body = (name) => sections.get(name)?.body ?? [];
+  const mission = preamble.map((l) => l.trim()).filter(Boolean).join(" ").trim();
+  return {
+    mission,
+    guardrails: bulletLines(body("guardrails")),
+    scope: bulletLines(body("scope")),
+    objectives: parseObjectives(body("objectives")),
+    limits: sections.has("limits") ? parseLimits(body("limits")) : { ...DEFAULT_LIMITS }
+  };
+}
+function loadVision(path) {
+  if (!existsSync(path)) return null;
+  return parseVision(readFileSync(path, "utf-8"));
+}
+function setObjectiveDone(path, objId, done) {
+  if (!existsSync(path)) return false;
+  const lines = readFileSync(path, "utf-8").split(/\r?\n/);
+  let changed = false;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line === void 0) continue;
+    const m = line.match(/^(\s*[-*]\s+)\[([ xX])\]\s+(.*\S)\s*$/);
+    if (!m?.[3]) continue;
+    if (objectiveId(m[3].trim()) === objId) {
+      lines[i] = `${m[1] ?? ""}[${done ? "x" : " "}] ${m[3].trim()}`;
+      changed = true;
+      break;
+    }
+  }
+  if (changed) writeFileSync(path, lines.join("\n"));
+  return changed;
+}
+const VISION_TEMPLATE = `# Vision
+
+State the single north-star mission this autonomous loop serves. Keep it to a
+sentence or two \u2014 concrete enough to judge whether a piece of work belongs.
+
+## Guardrails
+
+- Stay within the scope below; do not touch anything outside it.
+- Never modify secrets, production credentials, or deploy/publish.
+- Open a PR for review; never merge to the default branch autonomously.
+- If an objective is ambiguous or risky, stop and ask a human.
+
+## Scope
+
+- src/**
+- docs/**
+
+## Objectives
+
+- [ ] First concrete objective the loop should pursue
+- [ ] Second objective
+- [ ] Third objective
+
+## Limits
+
+maxIterations: 10
+maxIterationsPerDay: 50
+maxConsecutiveFailures: 3
+tickIntervalSec: 60
+requireApproval: false
+stopWhenComplete: true
+`;
+function scaffoldVision(path, force = false) {
+  if (existsSync(path) && !force) return false;
+  writeFileSync(path, VISION_TEMPLATE);
+  return true;
+}
+export {
+  VISION_TEMPLATE,
+  loadVision,
+  objectiveId,
+  parseVision,
+  scaffoldVision,
+  setObjectiveDone
+};

package/dist/src/core/vision/vision-loop.js

@@ -0,0 +1,220 @@
+import { fileURLToPath as __fileURLToPath } from 'url';
+import { dirname as __pathDirname } from 'path';
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __pathDirname(__filename);
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { dirname } from "path";
+import { loadVision, setObjectiveDone } from "./vision-file.js";
+import { SignalInbox } from "./signals.js";
+import {
+  SEVERITY_RANK
+} from "./types.js";
+function today() {
+  return (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+}
+const realSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+class VisionLoop {
+  opts;
+  inbox;
+  constructor(options) {
+    this.opts = { sleep: realSleep, ...options };
+    this.inbox = new SignalInbox(options.signalsPath);
+  }
+  readState() {
+    const base = {
+      day: today(),
+      iterationsToday: 0,
+      consecutiveFailures: 0,
+      lastTickAt: 0
+    };
+    if (!existsSync(this.opts.statePath)) return base;
+    try {
+      const s = JSON.parse(
+        readFileSync(this.opts.statePath, "utf-8")
+      );
+      if (s.day !== today()) return { ...s, day: today(), iterationsToday: 0 };
+      return s;
+    } catch {
+      return base;
+    }
+  }
+  writeState(s) {
+    const dir = dirname(this.opts.statePath);
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    writeFileSync(this.opts.statePath, JSON.stringify(s, null, 2));
+  }
+  /** Pick the next unit of work: pending signals outrank pending objectives. */
+  selectCandidate(vision) {
+    const signal = this.inbox.pending()[0];
+    if (signal) {
+      return {
+        kind: "signal",
+        id: signal.id,
+        text: signal.text,
+        priority: 100 + SEVERITY_RANK[signal.severity],
+        refs: signal.refs ?? []
+      };
+    }
+    const idx = vision.objectives.findIndex((o2) => !o2.done);
+    const o = idx >= 0 ? vision.objectives[idx] : void 0;
+    if (o) {
+      return {
+        kind: "objective",
+        id: o.id,
+        text: o.text,
+        priority: 50 - idx,
+        refs: []
+      };
+    }
+    return null;
+  }
+  checkGuardrails(state, vision, iterationThisRun) {
+    const l = vision.limits;
+    if (iterationThisRun >= l.maxIterations) {
+      return {
+        ok: false,
+        reason: `reached maxIterations (${l.maxIterations}) for this run`
+      };
+    }
+    if (state.iterationsToday >= l.maxIterationsPerDay) {
+      return {
+        ok: false,
+        reason: `reached maxIterationsPerDay (${l.maxIterationsPerDay})`
+      };
+    }
+    if (state.consecutiveFailures >= l.maxConsecutiveFailures) {
+      return {
+        ok: false,
+        reason: `circuit breaker: ${state.consecutiveFailures} consecutive failures (limit ${l.maxConsecutiveFailures})`
+      };
+    }
+    return { ok: true };
+  }
+  /** Has the brain already concluded this exact piece of work? */
+  priorConclusion(text) {
+    const hits = this.brainRecall(text);
+    const match = hits.find(
+      (e) => e.title.trim() === text.trim() && e.conclusion.trim().length > 0
+    );
+    return match?.conclusion;
+  }
+  brainRecall(text) {
+    return this.opts.brain.recall({ text, limit: 5 });
+  }
+  async tick(iterationThisRun, dryRun = false) {
+    const vision = loadVision(this.opts.visionPath);
+    if (!vision) {
+      return {
+        candidate: null,
+        guardrail: { ok: false, reason: "no VISION.md found" },
+        skippedAsKnown: false,
+        delegated: false
+      };
+    }
+    const state = this.readState();
+    const guardrail = this.checkGuardrails(state, vision, iterationThisRun);
+    if (!guardrail.ok) {
+      return {
+        candidate: null,
+        guardrail,
+        skippedAsKnown: false,
+        delegated: false
+      };
+    }
+    const candidate = this.selectCandidate(vision);
+    if (!candidate) {
+      return {
+        candidate: null,
+        guardrail: { ok: true },
+        skippedAsKnown: false,
+        delegated: false
+      };
+    }
+    const prior = this.priorConclusion(candidate.text);
+    if (prior) {
+      if (candidate.kind === "objective") {
+        setObjectiveDone(this.opts.visionPath, candidate.id, true);
+      } else {
+        this.inbox.resolve(candidate.id);
+      }
+      return {
+        candidate,
+        guardrail: { ok: true },
+        skippedAsKnown: true,
+        priorConclusion: prior,
+        delegated: false
+      };
+    }
+    if (dryRun || vision.limits.requireApproval) {
+      return {
+        candidate,
+        guardrail: { ok: true },
+        skippedAsKnown: false,
+        delegated: false
+      };
+    }
+    const outcome = await this.opts.delegate(candidate, vision);
+    this.opts.brain.record({
+      title: candidate.text,
+      summary: `Vision loop handled a ${candidate.kind} toward: ${vision.mission}`,
+      conclusion: outcome.conclusion,
+      kind: "experiment",
+      agent: "vision",
+      tags: ["vision", candidate.kind, outcome.success ? "success" : "failure"],
+      refs: [...candidate.refs, ...outcome.refs ?? []],
+      confidence: outcome.success ? 0.8 : 0.4
+    });
+    const next = this.readState();
+    if (outcome.success) {
+      next.iterationsToday += 1;
+      next.consecutiveFailures = 0;
+      if (candidate.kind === "objective") {
+        setObjectiveDone(this.opts.visionPath, candidate.id, true);
+      } else {
+        this.inbox.resolve(candidate.id);
+      }
+    } else {
+      next.consecutiveFailures += 1;
+    }
+    next.lastTickAt = Date.now();
+    this.writeState(next);
+    return {
+      candidate,
+      guardrail: { ok: true },
+      skippedAsKnown: false,
+      delegated: true,
+      outcome
+    };
+  }
+  /** Run ticks until a guardrail stops the loop or there's nothing left. */
+  async run(opts = {}) {
+    const vision = loadVision(this.opts.visionPath);
+    const max = opts.maxIterations ?? vision?.limits.maxIterations ?? 1;
+    const tickInterval = (vision?.limits.tickIntervalSec ?? 60) * 1e3;
+    const decisions = [];
+    let delegated = 0;
+    let skipped = 0;
+    let stopped = "completed run";
+    for (let i = 0; i < max; i++) {
+      const d = await this.tick(i, opts.dryRun);
+      decisions.push(d);
+      if (!d.guardrail.ok) {
+        stopped = d.guardrail.reason ?? "guardrail stop";
+        break;
+      }
+      if (!d.candidate) {
+        stopped = "no work remaining";
+        break;
+      }
+      if (d.skippedAsKnown) skipped++;
+      if (d.delegated) delegated++;
+      if (!opts.dryRun && i < max - 1) {
+        await this.opts.sleep(tickInterval);
+      }
+    }
+    return { decisions, stopped, delegated, skipped };
+  }
+}
+export {
+  VisionLoop
+};