@yugabytedb/meko-mcp 2.2.0 → 2.3.0

package/assets/hooks-handlers/lib/opencode-handler.js

@@ -0,0 +1,620 @@
+#!/usr/bin/env node
+"use strict";
+const childProcess = require("child_process");
+const crypto = require("crypto");
+const fs = require("fs");
+const path = require("path");
+const captureState = require("./capture-state");
+const journalBridge = require("./journal-bridge");
+const DEFAULT_ENV_PATH = path.join(__dirname, "..", "..", "opencode-hook-env.json");
+const EVENT_SUBDIR = "opencode-events";
+const DEFAULT_RECOVERY_MAX_TIMERS = 16;
+function captureLib() {
+  return require("./capture");
+}
+function loadHookEnvironment(filePath) {
+  const target = filePath || process.env.MEKO_OPENCODE_ENV_FILE || DEFAULT_ENV_PATH;
+  try {
+    const parsed = JSON.parse(fs.readFileSync(target, "utf8"));
+    for (const key of [
+      "MEKO_MCP_URL",
+      "MEKO_API_KEY",
+      "MEKO_AGENT_ID",
+      "MEKO_MCP_SERVER_NAME",
+      "MEKO_WATERMARK_DIR",
+      "MEKO_DATAPACK_ID",
+      "MEKO_DATAPACK_NAME",
+    ]) {
+      if (typeof parsed[key] === "string" && parsed[key] !== "") {
+        process.env[key] = parsed[key];
+      } else if (key === "MEKO_API_KEY" && parsed[key] === "") {
+        delete process.env[key];
+      }
+    }
+  } catch (err) {
+    if (!err || err.code !== "ENOENT") {
+      process.stderr.write(`[meko-opencode] Could not read hook environment: ${err.message}\n`);
+    }
+  }
+  process.env.MEKO_HOOK_CLIENT = "opencode";
+  return target;
+}
+function sha(value) {
+  return crypto.createHash("sha256").update(String(value)).digest("hex");
+}
+function safeSessionId(value) {
+  const raw = String(value || "").trim();
+  if (/^[A-Za-z0-9_.-]+$/.test(raw)) return raw;
+  const base = raw.replace(/[^A-Za-z0-9_.-]+/g, "_").replace(/^_+|_+$/g, "") || "opencode";
+  return `${base.slice(0, 80)}-${sha(raw).slice(0, 12)}`;
+}
+function eventDir() {
+  return path.join(captureState.watermarkDir(), EVENT_SUBDIR);
+}
+function eventPaths(sessionId, dir) {
+  const id = safeSessionId(sessionId);
+  const d = dir || eventDir();
+  return {
+    journal: path.join(d, `${id}.jsonl`),
+    state: path.join(d, `${id}.state.json`),
+    lock: path.join(d, `${id}.lock`),
+  };
+}
+function userRecord(sessionId, cwd, exchange, observedAtMs) {
+  return {
+    type: "user",
+    uuid: exchange.userId,
+    source_message_id: exchange.userId,
+    session_id: sessionId,
+    cwd,
+    timestamp: exchange.timestamp,
+    message: { role: "user", content: [{ type: "text", text: exchange.input }] },
+    opencode: { source: "snapshot" },
+    meko: { observed_at_ms: observedAtMs },
+  };
+}
+function assistantRecord(sessionId, cwd, exchange, interrupted = false) {
+  const marker = captureLib().INTERRUPTED_ASSISTANT_OUTPUT;
+  const prior = typeof exchange.output === "string" ? exchange.output : "";
+  const text = interrupted
+    ? (prior && !prior.includes("assistant response was interrupted")
+      ? `${prior}\n\n${marker}`
+      : (prior || marker))
+    : exchange.output;
+  const assistantId = exchange.assistantId || `opencode-assistant-${sha(`${sessionId}:${exchange.userId}`).slice(0, 24)}`;
+  return {
+    type: "assistant",
+    uuid: assistantId,
+    source_message_id: assistantId,
+    session_id: sessionId,
+    cwd,
+    timestamp: exchange.timestamp,
+    message: { role: "assistant", content: [{ type: "text", text }] },
+    opencode: { source: "snapshot", interrupted },
+  };
+}
+// session.error holds a partial; idle completes it only if that assistant
+// message is rewritten in place. Otherwise interrupt on a later user or settle.
+const DEFAULT_SETTLE_MS = 30 * 60 * 1000;
+function settleDeadlineMs() {
+  // Same-process test override. Other clients' timers keep 30 minutes.
+  const raw = Number(process.env.MEKO_OPENCODE_SETTLE_MS);
+  return Number.isFinite(raw) && raw >= 0 ? raw : DEFAULT_SETTLE_MS;
+}
+
+function appendCanonicalExchanges(sessionId, cwd, exchanges, opts = {}) {
+  sessionId = safeSessionId(sessionId);
+  const fromError = Boolean(opts.fromErrorObservation);
+  const nowMs = Number.isFinite(opts.nowMs) ? Number(opts.nowMs) : Date.now();
+  const dir = opts.eventDir || eventDir();
+  const paths = eventPaths(sessionId, dir);
+  journalBridge.acquireEventLock(paths.lock, dir);
+  try {
+    let sessionCreated = false;
+    if (journalBridge.journalEmpty(paths.journal)) {
+      journalBridge.appendJournal(paths.journal, {
+        type: "opencode_session",
+        session_id: sessionId,
+        cwd,
+        timestamp: new Date(nowMs).toISOString(),
+        client: "opencode",
+      }, dir);
+      sessionCreated = true;
+    }
+    const state = journalBridge.readEventState(paths.state, paths.journal, sessionId, dir);
+    if (state.pending && !Number.isFinite(state.pending.first_observed_at_ms)) {
+      try {
+        state.pending.first_observed_at_ms = fs.statSync(paths.journal).mtimeMs;
+      } catch { /* leave null */ }
+    }
+    const seen = new Set(state.seen_source_ids || []);
+    let appended = 0;
+
+    const finalizeTentativeAsInterrupted = (timestamp) => {
+      if (!state.pending) return false;
+      const tentative = state.tentative_observation;
+      journalBridge.appendJournal(
+        paths.journal,
+        assistantRecord(
+          sessionId,
+          cwd,
+          {
+            userId: state.pending.user_uuid,
+            assistantId: tentative ? (tentative.assistant_id || null) : null,
+            output: tentative ? (tentative.assistant_text || "") : "",
+            timestamp:
+              timestamp ||
+              (tentative && tentative.observed_at) ||
+              new Date(nowMs).toISOString(),
+          },
+          true,
+        ),
+        dir,
+      );
+      if (tentative && tentative.assistant_id) seen.add(tentative.assistant_id);
+      state.pending = null;
+      state.tentative_observation = null;
+      return true;
+    };
+
+    const settleMs = settleDeadlineMs();
+    const pendingObservedAtMs =
+      state.pending && Number.isFinite(state.pending.first_observed_at_ms)
+        ? state.pending.first_observed_at_ms
+        : null;
+    const tentativeObservedAtMs =
+      state.tentative_observation &&
+      Number.isFinite(state.tentative_observation.observed_at_ms)
+        ? state.tentative_observation.observed_at_ms
+        : null;
+
+    // Pre-pass: finalize an aged pending turn before the rest of the batch.
+    const deadlineBase =
+      tentativeObservedAtMs == null ? pendingObservedAtMs
+      : pendingObservedAtMs == null ? tentativeObservedAtMs
+      : Math.min(tentativeObservedAtMs, pendingObservedAtMs);
+    const incomingCompletesPending = Boolean(
+      state.pending &&
+      exchanges.some((ex) => {
+        if (!ex || ex.userId !== state.pending.user_uuid || fromError) return false;
+        if (!(ex.output || ex.interrupted)) return false;
+        const t = state.tentative_observation;
+        if (
+          t &&
+          (ex.assistantId || null) === (t.assistant_id || null) &&
+          (ex.output || "") === (t.assistant_text || "")
+        ) {
+          return false;
+        }
+        return true;
+      }),
+    );
+    if (
+      state.pending &&
+      deadlineBase != null &&
+      nowMs - deadlineBase >= settleMs &&
+      !incomingCompletesPending
+    ) {
+      if (finalizeTentativeAsInterrupted()) appended += 1;
+    }
+
+    for (let i = 0; i < exchanges.length; i++) {
+      const exchange = exchanges[i];
+      if (!exchange?.userId) continue;
+      const userId = exchange.userId;
+      const hasAssistantContent = Boolean(exchange.output) || Boolean(exchange.interrupted);
+      const isPending = state.pending && state.pending.user_uuid === userId;
+      const errorHoldsAssistant = fromError && i === exchanges.length - 1;
+
+      if (!isPending && seen.has(userId)) continue;
+
+      if (isPending) {
+        if (!hasAssistantContent) {
+          if (!Number.isFinite(state.pending.first_observed_at_ms)) {
+            state.pending.first_observed_at_ms = nowMs;
+          }
+          continue;
+        }
+        if (errorHoldsAssistant) {
+          const priorObservedAtMs =
+            state.tentative_observation &&
+            Number.isFinite(state.tentative_observation.observed_at_ms)
+              ? state.tentative_observation.observed_at_ms
+              : Number.isFinite(state.pending.first_observed_at_ms)
+                ? state.pending.first_observed_at_ms
+                : nowMs;
+          state.tentative_observation = {
+            assistant_id: exchange.assistantId || null,
+            assistant_text: exchange.output || "",
+            observed_at: exchange.timestamp || new Date(nowMs).toISOString(),
+            observed_at_ms: priorObservedAtMs,
+          };
+          continue;
+        }
+        const t = state.tentative_observation;
+        if (
+          t &&
+          (exchange.assistantId || null) === (t.assistant_id || null) &&
+          (exchange.output || "") === (t.assistant_text || "")
+        ) {
+          continue;
+        }
+        journalBridge.appendJournal(
+          paths.journal,
+          assistantRecord(sessionId, cwd, exchange, Boolean(exchange.interrupted)),
+          dir,
+        );
+        if (exchange.assistantId) seen.add(exchange.assistantId);
+        state.pending = null;
+        state.tentative_observation = null;
+        appended += 1;
+        continue;
+      }
+
+      // Next user interrupts the prior pending (omitted, or held as a matching session.error partial).
+      if (state.pending && state.pending.user_uuid !== userId) {
+        finalizeTentativeAsInterrupted(exchange.timestamp);
+      }
+
+      journalBridge.appendJournal(paths.journal, userRecord(sessionId, cwd, exchange, nowMs), dir);
+      seen.add(userId);
+      state.turn_index += 1;
+      state.tentative_observation = null;
+      state.pending = {
+        user_uuid: userId,
+        source_message_id: userId,
+        turn_index: state.turn_index,
+        first_observed_at_ms: nowMs,
+      };
+      if (hasAssistantContent) {
+        if (errorHoldsAssistant) {
+          state.tentative_observation = {
+            assistant_id: exchange.assistantId || null,
+            assistant_text: exchange.output || "",
+            observed_at: exchange.timestamp || new Date(nowMs).toISOString(),
+            observed_at_ms: nowMs,
+          };
+        } else {
+          journalBridge.appendJournal(
+            paths.journal,
+            assistantRecord(sessionId, cwd, exchange, Boolean(exchange.interrupted)),
+            dir,
+          );
+          if (exchange.assistantId) seen.add(exchange.assistantId);
+          state.pending = null;
+          state.tentative_observation = null;
+        }
+      }
+      appended += 1;
+    }
+
+    state.seen_source_ids = [...seen];
+    state.updated_at = new Date(nowMs).toISOString();
+    journalBridge.atomicWriteJson(paths.state, state, dir);
+    return { paths, state, appended, sessionCreated };
+  } finally {
+    journalBridge.releaseEventLock(paths.lock);
+  }
+}
+
+function finalizeExpiredSettleForSession(sessionId, opts = {}) {
+  const dir = opts.eventDir || eventDir();
+  const journalPath = eventPaths(sessionId, dir).journal;
+  if (journalBridge.journalEmpty(journalPath)) return { appended: 0 };
+  let cwd = "";
+  try {
+    const rec = JSON.parse(fs.readFileSync(journalPath, "utf8").split("\n").find((l) => l.trim()));
+    if (rec && typeof rec.cwd === "string") cwd = rec.cwd;
+  } catch { /* keep "" */ }
+  return appendCanonicalExchanges(sessionId, cwd, [], opts);
+}
+
+// Peek without a lock. Rebuild if missing, corrupt, or the journal is newer.
+function peekPendingObservation(sessionId, dir) {
+  const statePath = path.join(dir, `${sessionId}.state.json`);
+  const journalPath = path.join(dir, `${sessionId}.jsonl`);
+  let sidecar = null;
+  try {
+    sidecar = JSON.parse(fs.readFileSync(statePath, "utf8"));
+  } catch { /* sidecar lost or corrupt; fall through to journal */ }
+  if (sidecar && sidecar.schema_version === 1) {
+    try {
+      if (fs.statSync(journalPath).mtimeMs > fs.statSync(statePath).mtimeMs) {
+        sidecar = null;
+      }
+    } catch { /* missing journal; trust sidecar */ }
+  }
+  if (sidecar && sidecar.schema_version === 1) {
+    if (!sidecar.pending) return null;
+    const tentative = sidecar.tentative_observation;
+    const t = tentative && Number.isFinite(tentative.observed_at_ms)
+      ? tentative.observed_at_ms : null;
+    const p = Number.isFinite(sidecar.pending.first_observed_at_ms)
+      ? sidecar.pending.first_observed_at_ms : null;
+    if (t != null && p != null) return Math.min(t, p);
+    if (t != null) return t;
+    if (p != null) return p;
+  }
+  const rebuilt = journalBridge.rebuildEventState(journalPath, sessionId);
+  if (rebuilt.pending && Number.isFinite(rebuilt.pending.first_observed_at_ms)) {
+    return rebuilt.pending.first_observed_at_ms;
+  }
+  if (rebuilt.pending) {
+    try { return fs.statSync(journalPath).mtimeMs; } catch { return null; }
+  }
+  return null;
+}
+
+// Skip a current completed sidecar. Rebuild if missing, corrupt, or stale.
+function sweepExpiredSettles(opts = {}) {
+  const dir = opts.eventDir || eventDir();
+  const nowMs = Number.isFinite(opts.nowMs) ? Number(opts.nowMs) : Date.now();
+  const deadline = settleDeadlineMs();
+  const ids = new Set();
+  try {
+    for (const file of fs.readdirSync(dir)) {
+      if (file.endsWith(".state.json")) {
+        ids.add(file.slice(0, -".state.json".length));
+      } else if (file.endsWith(".jsonl")) {
+        ids.add(file.slice(0, -".jsonl".length));
+      }
+    }
+  } catch { return { swept: 0, promoted: 0, finalized: 0 }; }
+  let finalized = 0;
+  let promoted = 0;
+  for (const sessionId of ids) {
+    const observedAtMs = peekPendingObservation(sessionId, dir);
+    if (observedAtMs == null) continue;
+    if (nowMs - observedAtMs < deadline) continue;
+    promoted += 1;
+    try {
+      const out = finalizeExpiredSettleForSession(sessionId, { ...opts, nowMs });
+      if (out && out.appended > 0) finalized += 1;
+    } catch (err) {
+      process.stderr.write(
+        `[meko-opencode] Could not finalize expired settle for ${sessionId}: ${err.message}\n`,
+      );
+    }
+  }
+  return { swept: ids.size, promoted, finalized };
+}
+function ensureCaptureIntent(sessionId, journalPath, cwd) {
+  const agentId = captureLib().deriveAgentId({
+    client: "opencode",
+    cwd,
+    envOverride: process.env.MEKO_AGENT_ID,
+  });
+  return captureState.writeSessionIntent(sessionId, {
+    client: "opencode",
+    agent_id: agentId,
+    agent_id_source: (process.env.MEKO_AGENT_ID || "").trim() ? "explicit" : "derived",
+    transcript_path: journalPath,
+    datapack_id: process.env.MEKO_DATAPACK_ID || null,
+    datapack_name: process.env.MEKO_DATAPACK_NAME || null,
+    pending_turn_policy: "resumable",
+  });
+}
+function launchCapture(mode, payload) {
+  const captureScript = path.join(__dirname, "capture.js");
+  const child = childProcess.spawn(process.execPath, [captureScript, mode], {
+    detached: true,
+    windowsHide: true,
+    stdio: ["pipe", "ignore", "ignore"],
+    env: { ...process.env, MEKO_HOOK_CLIENT: "opencode" },
+  });
+  child.stdin.on("error", () => {});
+  child.stdin.end(JSON.stringify(payload));
+  child.unref();
+}
+function launchRecoveryTimer(journalPath) {
+  const timerScript = path.join(__dirname, "checkpoint-timer.js");
+  const child = childProcess.spawn(process.execPath, [timerScript, journalPath], {
+    detached: true,
+    windowsHide: true,
+    stdio: "ignore",
+    env: { ...process.env, MEKO_HOOK_CLIENT: "opencode" },
+  });
+  child.unref();
+}
+function stagingDir() {
+  return path.join(captureState.watermarkDir(), "opencode-snapshots");
+}
+function legacyStagingDir() {
+  return path.join(__dirname, "..", "..", "snapshots");
+}
+function listStagedSnapshotFiles(root) {
+  try {
+    return fs.readdirSync(root)
+      .filter((file) => file.endsWith(".json"))
+      .map((file) => {
+        try {
+          return {
+            file,
+            root,
+            mtimeMs: fs.statSync(path.join(root, file)).mtimeMs,
+          };
+        } catch {
+          return null;
+        }
+      })
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+async function scanRecovery(options = {}) {
+  const snapshotsRoot = options.stagingDir || stagingDir();
+  const legacyRoot =
+    options.legacyStagingDir !== undefined
+      ? options.legacyStagingDir
+      : options.stagingDir
+        ? null
+        : legacyStagingDir();
+  const listed = listStagedSnapshotFiles(snapshotsRoot);
+  if (legacyRoot) listed.push(...listStagedSnapshotFiles(legacyRoot));
+  const snapshots = listed
+    .sort((a, b) => a.mtimeMs - b.mtimeMs || a.file.localeCompare(b.file) || a.root.localeCompare(b.root))
+    .map(({ file, root }) => ({ file, root }));
+  const replay = options.handleStagedRequest || handleStagedRequest;
+  for (const { file, root } of snapshots) {
+    const snapshotPath = path.join(root, file);
+    try {
+      await replay({ snapshotPath }, options);
+    } catch (err) {
+      process.stderr.write(
+        `[meko-opencode] Could not replay staged snapshot ${file}: ${err.message}\n`,
+      );
+    }
+  }
+  const dir = options.eventDir || eventDir();
+  sweepExpiredSettles({ eventDir: dir });
+  const startRecoveryTimer =
+    options.launchRecoveryTimer || launchRecoveryTimer;
+  let files;
+  try {
+    files = fs.readdirSync(dir).filter((f) => f.endsWith(".jsonl"));
+  } catch {
+    return;
+  }
+  const shouldRecover = options.shouldRecoverJournal || journalNeedsRecovery;
+  const maxTimers = Number.isInteger(options.maxRecoveryTimers)
+    ? Math.max(0, options.maxRecoveryTimers)
+    : DEFAULT_RECOVERY_MAX_TIMERS;
+  files = files
+    .map((file) => {
+      try { return { file, mtimeMs: fs.statSync(path.join(dir, file)).mtimeMs }; }
+      catch { return null; }
+    })
+    .filter(Boolean)
+    .filter(({ file }) => shouldRecover(path.join(dir, file)))
+    .sort((a, b) => a.mtimeMs - b.mtimeMs)
+    .slice(0, maxTimers);
+  for (const { file } of files) {
+    startRecoveryTimer(path.join(dir, file));
+  }
+}
+function journalNeedsRecovery(journalPath) {
+  const sessionId = path.basename(journalPath, ".jsonl");
+  const read = captureState.readState(sessionId);
+  return !read.ok || captureState.sessionHealthBucket(read) !== "healthy";
+}
+async function handleSnapshot(payload, options = {}) {
+  const normalize = options.normalize || require("./opencode-normalizer.js").normalizeOpenCodeSession;
+  // session.error is an observation. A pending user stays until a later
+  // snapshot completes it, a later user interrupts, or MEKO_OPENCODE_SETTLE_MS.
+  const normalized = normalize(payload.export || payload, {
+    emitPendingAsExchange: true,
+  });
+  const sessionId = safeSessionId(normalized.sessionId);
+  const journaled = appendCanonicalExchanges(
+    sessionId,
+    normalized.cwd,
+    normalized.exchanges,
+    { fromErrorObservation: Boolean(payload.terminalError) },
+  );
+  const intent = ensureCaptureIntent(
+    sessionId,
+    journaled.paths.journal,
+    normalized.cwd,
+  );
+  if (!intent.ok) {
+    return { ok: false, error: intent.error, journaled };
+  }
+  const checkpointPayload = {
+    session_id: sessionId,
+    transcript_path: journaled.paths.journal,
+    lifecycle: "active",
+  };
+  const startCapture = options.launchCapture || launchCapture;
+  const startRecoveryTimer = options.launchRecoveryTimer || launchRecoveryTimer;
+  if (journaled.sessionCreated || journaled.appended > 0) {
+    startCapture("checkpoint", checkpointPayload);
+    startRecoveryTimer(journaled.paths.journal);
+  }
+  return { ok: true, journaled, intent, normalized };
+}
+async function handleStagedRequest(request, options = {}) {
+  const snapshotPath =
+    typeof request?.snapshotPath === "string" ? request.snapshotPath : "";
+  let payload = request;
+  if (snapshotPath) {
+    let staged;
+    try {
+      staged = JSON.parse(fs.readFileSync(snapshotPath, "utf8"));
+    } catch (err) {
+      quarantineSnapshot(snapshotPath);
+      throw new Error(`invalid staged snapshot JSON: ${err.message}`);
+    }
+    const snapshot = staged?.export ?? staged;
+    if (!isValidStagedSnapshot(snapshot)) {
+      quarantineSnapshot(snapshotPath);
+      throw new Error("invalid staged snapshot shape");
+    }
+    payload = {
+      export: snapshot,
+      terminalError: staged?.export
+        ? Boolean(staged.terminalError)
+        : Boolean(request.terminalError),
+    };
+  }
+  const handler = options.handleSnapshot || handleSnapshot;
+  const result = await handler(payload, options);
+  if (snapshotPath && result?.ok === true) {
+    try { fs.unlinkSync(snapshotPath); } catch { /* already acknowledged */ }
+  }
+  return result;
+}
+function isValidStagedSnapshot(snapshot) {
+  if (!snapshot || typeof snapshot !== "object") return false;
+  if (!snapshot.info || typeof snapshot.info !== "object") return false;
+  const sessionId =
+    snapshot.info.id || snapshot.info.sessionID || snapshot.info.sessionId;
+  return (
+    typeof sessionId === "string" &&
+    sessionId.length > 0 &&
+    Array.isArray(snapshot.messages)
+  );
+}
+function quarantineSnapshot(snapshotPath) {
+  const quarantineDir = path.join(path.dirname(snapshotPath), "quarantine");
+  fs.mkdirSync(quarantineDir, { recursive: true, mode: 0o700 });
+  try { fs.chmodSync(quarantineDir, 0o700); } catch { /* best effort */ }
+  const target = path.join(
+    quarantineDir,
+    `${path.basename(snapshotPath)}.${Date.now()}.invalid`,
+  );
+  fs.renameSync(snapshotPath, target);
+  return target;
+}
+async function main() {
+  loadHookEnvironment();
+  if (process.argv.includes("--recovery-scan")) {
+    await scanRecovery();
+    return;
+  }
+  let request = {};
+  try {
+    request = JSON.parse(fs.readFileSync(0, "utf8") || "{}");
+  } catch (err) {
+    process.stderr.write(`[meko-opencode] Invalid handler input: ${err.message}\n`);
+    return;
+  }
+  await handleStagedRequest(request);
+}
+module.exports = {
+  loadHookEnvironment,
+  eventPaths,
+  appendCanonicalExchanges,
+  finalizeExpiredSettleForSession,
+  sweepExpiredSettles,
+  handleSnapshot,
+  handleStagedRequest,
+  scanRecovery,
+  launchCapture,
+  launchRecoveryTimer,
+};
+if (require.main === module) {
+  main().catch((err) => {
+    process.stderr.write(`[meko-opencode] Handler failed: ${err.message}\n`);
+  });
+}