zmemory 0.1.0

package/src/mcp/server.js

@@ -0,0 +1,420 @@
+import fs from "fs";
+import { assertValidRunId, getRunFile, isValidRunId } from "../lib/run.js";
+import { ensureZMemory } from "../integrations/auto-bootstrap.js";
+import { addTask, listTasks, claimTask, completeTask } from "../lib/tasks.js";
+import { listAgents, registerAgent } from "../lib/agents.js";
+import { listLocks } from "../lib/fileLocks.js";
+import { execCommand } from "../commands/exec.js";
+import { planCommand } from "../commands/plan.js";
+import { routeRun } from "../commands/route.js";
+import { readJSON, writeJSON } from "../lib/fs.js";
+import { acquireLock, releaseLock } from "../lib/lock.js";
+const EVENTS_FILE = `.zmemory/logs/events.jsonl`;
+const ARCHIVE_DIR = `.zmemory/logs/archive`;
+const MAX_ACTIVE_EVENTS = 5000;
+const ARCHIVE_BATCH = 2000;
+import { claimPattern, listClaims, releaseClaims } from "../lib/coordination/claims.js";
+import { who as whoLookup } from "../lib/coordination/who.js";
+
+// ---- Tool Contracts (source of truth) ----
+const toolContracts = {
+  zmemory_tools_list: { description: "List MCP tool schemas", input: { required: {}, optional: {} } },
+  zmemory_get_context: { description: "Get run context", input: { required: { run_id: "run_id" }, optional: { role: "nonempty:string" } } },
+  zmemory_append_event: { description: "Append event", input: { required: { role: "nonempty:string", type: "nonempty:string", summary: "nonempty:string" }, optional: { run_id: "run_id", ts: "nonempty:string", files: "array:string", evidence: "nonempty:string", error_signature: "nonempty:string" } } },
+  zmemory_get_run_state: { description: "Read run state", input: { required: { run_id: "run_id" }, optional: {} } },
+  zmemory_update_run_state: { description: "Update run state", input: { required: { run_id: "run_id" }, optional: { status: "nonempty:string", current_step: "number", next_action: "nonempty:string" } } },
+  zmemory_create_handoff: { description: "Create run handoff", input: { required: { run_id: "run_id" }, optional: {} } },
+  zmemory_record_decision: { description: "Record architectural decision", input: { required: { decision: "nonempty:string" }, optional: { reason: "nonempty:string" } } },
+  zmemory_record_failure: { description: "Record failure pattern", input: { required: { symptom: "nonempty:string" }, optional: { root_cause: "nonempty:string", fix: "nonempty:string" } } },
+  zmemory_search: { description: "Search zmemory files", input: { required: { query: "nonempty:string" }, optional: {} } },
+  zmemory_stream_events: { description: "Get recent activity events", input: { required: {}, optional: { limit: "number", since: "nonempty:string" } } },
+  zmemory_tasks_list: { description: "List tasks", input: { required: {}, optional: {} } },
+  zmemory_tasks_add: { description: "Add task", input: { required: { title: "nonempty:string" }, optional: {} } },
+  zmemory_tasks_claim: { description: "Claim task", input: { required: { id: "nonempty:string", worker: "nonempty:string" }, optional: {} } },
+  zmemory_tasks_complete: { description: "Complete task", input: { required: { id: "nonempty:string" }, optional: {} } },
+  zmemory_agents_list: { description: "List agents", input: { required: {}, optional: {} } },
+  zmemory_agents_register: { description: "Register agent", input: { required: { name: "nonempty:string", role: "nonempty:string" }, optional: {} } },
+  zmemory_filelocks_list: { description: "List file locks", input: { required: {}, optional: {} } },
+  zmemory_claim: { description: "Claim file pattern", input: { required: { pattern: "nonempty:string", session: "nonempty:string" }, optional: { task: "nonempty:string" } } },
+  zmemory_claims: { description: "List claims", input: { required: {}, optional: {} } },
+  zmemory_release: { description: "Release claims for session", input: { required: { session: "nonempty:string" }, optional: {} } },
+  zmemory_who: { description: "Who is working on file", input: { required: { file: "nonempty:string" }, optional: {} } },
+  zmemory_plan: { description: "Generate plan", input: { required: { goal: "nonempty:string" }, optional: {} } },
+  zmemory_route: { description: "Route run", input: { required: { run: "run_id" }, optional: {} } },
+  zmemory_exec: { description: "Execute command (gated)", input: { required: { command: "nonempty:string" }, optional: {} } }
+};
+
+function checkType(val, type) {
+  if (type === "string") return typeof val === "string";
+  if (type === "nonempty:string") return typeof val === "string" && val.trim() !== "";
+  if (type === "number") return typeof val === "number" && Number.isFinite(val);
+  if (type === "boolean") return typeof val === "boolean";
+  if (type === "array:string") return Array.isArray(val) && val.every(v => typeof v === "string" && v.trim() !== "");
+  if (type === "run_id") return typeof val === "string" && isValidRunId(val);
+  return true;
+}
+
+function validateInput(tool, input) {
+  const spec = toolContracts[tool];
+  if (!spec) return;
+  const req = spec.input.required || {};
+  const opt = spec.input.optional || {};
+  const allowed = new Set([...Object.keys(req), ...Object.keys(opt)]);
+
+  for (const k of Object.keys(req)) {
+    if (!(k in input)) throw new Error(`invalid input: missing ${k}`);
+    if (!checkType(input[k], req[k])) throw new Error(`invalid input: expected ${k} ${req[k]}`);
+  }
+
+  for (const k of Object.keys(input)) {
+    if (!allowed.has(k)) throw new Error(`invalid input: unknown field ${k}`);
+    const t = req[k] || opt[k];
+    if (t && !checkType(input[k], t)) throw new Error(`invalid input: expected ${k} ${t}`);
+  }
+}
+
+function appendEvent(evt) {
+  if (!evt.ts) {
+    evt.ts = new Date().toISOString();
+  }
+  if (evt.run_id) {
+    assertValidRunId(evt.run_id);
+  }
+  const line = JSON.stringify(evt) + "\n";
+  if (evt.run_id) {
+    try {
+      acquireLock(evt.run_id);
+    } catch {
+      throw new Error("run locked by another agent");
+    }
+    try {
+      fs.appendFileSync(EVENTS_FILE, line);
+      fs.appendFileSync(getRunFile(evt.run_id, "events.jsonl"), line);
+      rotateEventsIfNeeded();
+    } finally {
+      releaseLock(evt.run_id);
+    }
+  } else {
+    fs.appendFileSync(EVENTS_FILE, line);
+    rotateEventsIfNeeded();
+  }
+}
+
+function rotateEventsIfNeeded() {
+  try {
+    if (!fs.existsSync(EVENTS_FILE)) return;
+    const lines = fs.readFileSync(EVENTS_FILE, "utf8").split("\n").filter(Boolean);
+    if (lines.length <= MAX_ACTIVE_EVENTS) return;
+
+    fs.mkdirSync(ARCHIVE_DIR, { recursive: true });
+
+    const archive = lines.slice(0, ARCHIVE_BATCH);
+    const keep = lines.slice(ARCHIVE_BATCH);
+
+    const existing = fs.readdirSync(ARCHIVE_DIR).filter(f => f.startsWith("events-") && f.endsWith(".jsonl"));
+    const next = String(existing.length + 1).padStart(5, "0");
+    const archivePath = `${ARCHIVE_DIR}/events-${next}.jsonl`;
+
+    fs.writeFileSync(archivePath, archive.join("\n") + "\n");
+    fs.writeFileSync(EVENTS_FILE, keep.join("\n") + (keep.length ? "\n" : ""));
+  } catch {}
+}
+
+function getContext({ run_id, role }) {
+  assertValidRunId(run_id);
+  const state = readJSON(getRunFile(run_id, "state.json"));
+  const task = fs.readFileSync(getRunFile(run_id, "task.md"), "utf8");
+
+  return {
+    role,
+    task,
+    status: state?.status,
+    step: state?.current_step,
+    next_action: state?.next_action
+  };
+}
+
+function updateRunState(input) {
+  assertValidRunId(input.run_id);
+  const path = getRunFile(input.run_id, "state.json");
+  try {
+    acquireLock(input.run_id);
+  } catch {
+    throw new Error("run locked by another agent");
+  }
+  try {
+    const state = readJSON(path);
+    if (!state) return null;
+
+    if (input.status) state.status = input.status;
+    if (input.current_step !== undefined) state.current_step = input.current_step;
+    if (input.next_action) state.next_action = input.next_action;
+
+    writeJSON(path, state);
+    return state;
+  } finally {
+    releaseLock(input.run_id);
+  }
+}
+
+function createHandoff({ run_id }) {
+  assertValidRunId(run_id);
+  const state = readJSON(getRunFile(run_id, "state.json"));
+  const task = fs.readFileSync(getRunFile(run_id, "task.md"), "utf8");
+
+  return {
+    task,
+    status: state?.status,
+    next_action: state?.next_action
+  };
+}
+
+function recordDecision({ decision, reason }) {
+  const entry = `\n## ${new Date().toISOString()}\n${decision}\nReason: ${reason || ""}\n`;
+  fs.appendFileSync(`.zmemory/decisions.md`, entry);
+  return { ok: true };
+}
+
+function recordFailure({ symptom, root_cause, fix }) {
+  const entry = `\n## ${new Date().toISOString()}\nSymptom: ${symptom}\nRoot cause: ${root_cause || ""}\nFix: ${fix || ""}\n`;
+  fs.appendFileSync(`.zmemory/failures.md`, entry);
+  return { ok: true };
+}
+
+function search({ query }) {
+  const base = ".zmemory";
+  const results = [];
+
+  function scan(dir) {
+    const items = fs.readdirSync(dir, { withFileTypes: true });
+    for (const it of items) {
+      const p = `${dir}/${it.name}`;
+      if (it.isDirectory()) scan(p);
+      else {
+        const txt = fs.readFileSync(p, "utf8");
+        if (txt.toLowerCase().includes(query.toLowerCase())) results.push(p);
+      }
+    }
+  }
+
+  scan(base);
+  return results;
+}
+
+const tools = {
+  zmemory_tools_list: () => toolContracts,
+  zmemory_get_context: getContext,
+  zmemory_append_event: appendEvent,
+  zmemory_get_run_state: ({ run_id }) => {
+    assertValidRunId(run_id);
+    return readJSON(getRunFile(run_id, "state.json"));
+  },
+  zmemory_update_run_state: updateRunState,
+  zmemory_create_handoff: createHandoff,
+  zmemory_record_decision: recordDecision,
+  zmemory_record_failure: recordFailure,
+  zmemory_search: search,
+  zmemory_stream_events: ({ limit, since }) => {
+    const file = `.zmemory/logs/events.jsonl`;
+    const n = typeof limit === "number" && limit > 0 ? limit : 20;
+    if (!fs.existsSync(file)) return [];
+
+    const lines = fs
+      .readFileSync(file, "utf8")
+      .split("\n")
+      .filter(Boolean)
+      .slice(-Math.max(n, 5));
+
+    const events = [];
+    for (const l of lines) {
+      try {
+        events.push(JSON.parse(l));
+      } catch {}
+    }
+
+    // Always include last 5 events to guard against context loss
+    const lastFive = events.slice(-5);
+
+    if (!since) return events;
+
+    const newer = events.filter(e => {
+      if (!e?.ts) return true;
+      return e.ts > since;
+    });
+
+    // Merge unique events (by ts+summary heuristic)
+    const merged = [...newer];
+    for (const e of lastFive) {
+      if (!merged.find(x => x.ts === e.ts && x.summary === e.summary)) {
+        merged.push(e);
+      }
+    }
+
+    return merged;
+  },
+
+  // Task graph tools
+  zmemory_tasks_list: () => listTasks(),
+  zmemory_tasks_add: ({ title }) => addTask(title),
+  zmemory_tasks_claim: ({ id, worker }) => claimTask(id, worker),
+  zmemory_tasks_complete: ({ id }) => completeTask(id),
+
+  // Agent registry
+  zmemory_agents_list: () => listAgents(),
+  zmemory_agents_register: ({ name, role }) => registerAgent(name, role),
+
+  // Locks
+  zmemory_filelocks_list: () => listLocks()
+  ,
+  // Claims / coordination
+  zmemory_claim: ({ pattern, session, task }) => claimPattern(pattern, { session, task }),
+  zmemory_claims: () => listClaims(),
+  zmemory_release: ({ session }) => {
+    releaseClaims(session);
+    return { ok: true };
+  },
+  zmemory_who: ({ file }) => whoLookup(file),
+  // planner + routing
+  zmemory_plan: ({ goal }) => planCommand([goal]),
+  zmemory_route: ({ run }) => routeRun(["--run", run]),
+
+  // command execution wrapper
+  zmemory_exec: ({ command }) => {
+    const cfgPath = `.zmemory/config.json`;
+    let allow = false;
+    if (fs.existsSync(cfgPath)) {
+      try {
+        const cfg = JSON.parse(fs.readFileSync(cfgPath, "utf8"));
+        allow = cfg.allow_mcp_exec === true;
+      } catch {}
+    }
+    if (!allow) {
+      throw new Error("zmemory_exec disabled; set allow_mcp_exec true to enable");
+    }
+    return execCommand((command || "").split(" "));
+  }
+};
+
+// Ensure runtime + skill exist whenever MCP starts
+ensureZMemory();
+
+// ---- contract drift check (toolContracts vs tools) ----
+{
+  const contractKeys = Object.keys(toolContracts).slice().sort();
+  const toolKeys = Object.keys(tools).slice().sort();
+  if (JSON.stringify(contractKeys) !== JSON.stringify(toolKeys)) {
+    throw new Error("tool contract mismatch");
+  }
+}
+
+// ---- tools.json drift check ----
+try {
+  const p = new URL("./tools.json", import.meta.url);
+  const json = JSON.parse(fs.readFileSync(p, "utf8"));
+  const fileTools = (json.tools || []).slice().sort();
+  const serverTools = Object.keys(tools).slice().sort();
+  if (JSON.stringify(fileTools) !== JSON.stringify(serverTools)) {
+    throw new Error("tools.json mismatch with server tools");
+  }
+} catch (e) {
+  console.error(e.message);
+  throw e;
+}
+
+let buffer = "";
+let lineQueue = Promise.resolve();
+
+
+
+async function handleLine(line) {
+  if (!line.trim()) return;
+
+  let msg;
+  try {
+    msg = JSON.parse(line);
+  } catch {
+    process.stdout.write(JSON.stringify({ error: "malformed json" }) + "\n");
+    return;
+  }
+
+  const id = msg?.id;
+  if (!msg || typeof msg !== "object" || Array.isArray(msg)) {
+    const out = { error: "invalid message" };
+    if (id !== undefined) out.id = id;
+    process.stdout.write(JSON.stringify(out) + "\n");
+    return;
+  }
+
+  if (typeof msg.tool !== "string" || !msg.tool.trim()) {
+    const out = { error: "invalid message: tool" };
+    if (id !== undefined) out.id = id;
+    process.stdout.write(JSON.stringify(out) + "\n");
+    return;
+  }
+
+  if (msg.input !== undefined && (msg.input === null || typeof msg.input !== "object" || Array.isArray(msg.input))) {
+    const out = { error: "invalid message: input" };
+    if (id !== undefined) out.id = id;
+    process.stdout.write(JSON.stringify(out) + "\n");
+    return;
+  }
+  const toolName = msg.tool.trim();
+  const fn = tools[toolName];
+  if (!fn) {
+    const out = { error: "unknown tool" };
+    if (id !== undefined) out.id = id;
+    process.stdout.write(JSON.stringify(out) + "\n");
+    return;
+  }
+
+  let capturedOut = "";
+  let capturedErr = "";
+
+  const origLog = console.log;
+  const origErr = console.error;
+
+  console.log = (...a) => {
+    capturedOut += a.map(v => String(v)).join(" ") + "\n";
+  };
+  console.error = (...a) => {
+    capturedErr += a.map(v => String(v)).join(" ") + "\n";
+  };
+
+  try {
+    const input = msg.input || {};
+    validateInput(toolName, input);
+    const raw = await fn(input);
+    const result = raw === undefined ? null : raw;
+    const out = { result };
+    if (id !== undefined) out.id = id;
+    if (capturedOut) out.stdout = capturedOut;
+    if (capturedErr) out.stderr = capturedErr;
+    process.stdout.write(JSON.stringify(out) + "\n");
+  } catch (e) {
+    const out = { error: e?.message || String(e) };
+    if (id !== undefined) out.id = id;
+    if (capturedOut) out.stdout = capturedOut;
+    if (capturedErr) out.stderr = capturedErr;
+    process.stdout.write(JSON.stringify(out) + "\n");
+  } finally {
+    console.log = origLog;
+    console.error = origErr;
+  }
+}
+
+process.stdin.on("data", (chunk) => {
+  buffer += chunk.toString();
+  let idx;
+  while ((idx = buffer.indexOf("\n")) >= 0) {
+    const line = buffer.slice(0, idx);
+    buffer = buffer.slice(idx + 1);
+    lineQueue = lineQueue.then(() => handleLine(line)).catch(() => {});
+  }
+});
+
+process.stdin.on("end", () => {
+  const remaining = buffer.trim();
+  if (remaining) {
+    lineQueue = lineQueue.then(() => handleLine(remaining)).catch(() => {});
+  }
+});

package/src/mcp/tools.json

@@ -0,0 +1,28 @@
+{
+  "tools": [
+    "zmemory_tools_list",
+    "zmemory_get_context",
+    "zmemory_append_event",
+    "zmemory_get_run_state",
+    "zmemory_update_run_state",
+    "zmemory_create_handoff",
+    "zmemory_record_decision",
+    "zmemory_record_failure",
+    "zmemory_search",
+    "zmemory_stream_events",
+    "zmemory_tasks_list",
+    "zmemory_tasks_add",
+    "zmemory_tasks_claim",
+    "zmemory_tasks_complete",
+    "zmemory_agents_list",
+    "zmemory_agents_register",
+    "zmemory_filelocks_list",
+    "zmemory_claim",
+    "zmemory_claims",
+    "zmemory_release",
+    "zmemory_who",
+    "zmemory_plan",
+    "zmemory_route",
+    "zmemory_exec"
+  ]
+}