@chrysb/alphaclaw 0.4.5 → 0.4.6-beta.0

package/lib/server/doctor/service.js

@@ -0,0 +1,392 @@
+const { buildDoctorPrompt } = require("./prompt");
+const { normalizeDoctorResult } = require("./normalize");
+const { calculateWorkspaceDelta, computeWorkspaceSnapshot } = require("./workspace-fingerprint");
+const {
+  kDoctorEngine,
+  kDoctorMeaningfulChangeScoreThreshold,
+  kDoctorPromptVersion,
+  kDoctorRunStatus,
+  kDoctorRunTimeoutMs,
+  kDoctorStaleThresholdMs,
+} = require("./constants");
+
+const shellEscapeArg = (value) => {
+  const safeValue = String(value || "");
+  return `'${safeValue.replace(/'/g, `'\\''`)}'`;
+};
+
+const hasValidIsoTime = (value) => {
+  const timestamp = Date.parse(String(value || ""));
+  return Number.isFinite(timestamp);
+};
+
+const formatElapsedSince = (isoTime) => {
+  if (!hasValidIsoTime(isoTime)) return "the last scan";
+  const elapsedMs = Math.max(0, Date.now() - Date.parse(isoTime));
+  const elapsedMinutes = Math.max(1, Math.round(elapsedMs / 60000));
+  if (elapsedMinutes < 60) {
+    return `${elapsedMinutes} minute${elapsedMinutes === 1 ? "" : "s"} ago`;
+  }
+  const elapsedHours = Math.round(elapsedMinutes / 60);
+  if (elapsedHours < 24) {
+    return `${elapsedHours} hour${elapsedHours === 1 ? "" : "s"} ago`;
+  }
+  const elapsedDays = Math.round(elapsedHours / 24);
+  return `${elapsedDays} day${elapsedDays === 1 ? "" : "s"} ago`;
+};
+
+const buildDoctorSessionKey = (runId) => `agent:main:doctor:${Number(runId || 0)}`;
+const buildDoctorSessionId = (runId) => buildDoctorSessionKey(runId);
+const buildDoctorIdempotencyKey = (runId) => `doctor-run-${Number(runId || 0)}`;
+
+const createDoctorService = ({
+  clawCmd,
+  listDoctorRuns,
+  listDoctorCards,
+  getInitialWorkspaceBaseline,
+  setInitialWorkspaceBaseline,
+  createDoctorRun,
+  completeDoctorRun,
+  insertDoctorCards,
+  getDoctorRun,
+  getDoctorCardsByRunId,
+  getDoctorCard,
+  updateDoctorCardStatus,
+  workspaceRoot,
+  managedRoot,
+  protectedPaths = [],
+  lockedPaths = [],
+}) => {
+  const state = {
+    activeRunId: 0,
+    activeRunPromise: null,
+    snapshotCache: null,
+  };
+
+  const getLatestCompletedRun = () =>
+    listDoctorRuns({ limit: 25 }).find((run) => run.status === kDoctorRunStatus.completed) || null;
+
+  const getCurrentWorkspaceSnapshot = () => {
+    const now = Date.now();
+    if (state.snapshotCache && now - state.snapshotCache.computedAt < 5000) {
+      return state.snapshotCache.snapshot;
+    }
+    const snapshot = computeWorkspaceSnapshot(workspaceRoot);
+    state.snapshotCache = {
+      computedAt: now,
+      snapshot,
+    };
+    return snapshot;
+  };
+
+  const getOrCreateInitialBaseline = () => {
+    const existingBaseline = getInitialWorkspaceBaseline?.();
+    if (existingBaseline?.fingerprint && existingBaseline?.manifest) {
+      return existingBaseline;
+    }
+    const snapshot = getCurrentWorkspaceSnapshot();
+    const nextBaseline = {
+      fingerprint: snapshot.fingerprint,
+      manifest: snapshot.manifest,
+      capturedAt: new Date().toISOString(),
+    };
+    return setInitialWorkspaceBaseline?.(nextBaseline) || nextBaseline;
+  };
+
+  const cloneRunCards = ({ sourceRunId, targetRunId }) => {
+    const sourceCards = getDoctorCardsByRunId(sourceRunId);
+    insertDoctorCards({
+      runId: targetRunId,
+      cards: sourceCards,
+    });
+  };
+
+  const buildStatus = () => {
+    const recentRuns = listDoctorRuns({ limit: 10 });
+    const latestRun = recentRuns[0] || null;
+    const latestCompletedRun =
+      recentRuns.find((run) => run.status === kDoctorRunStatus.completed) || null;
+    const lastRunAt =
+      latestCompletedRun?.completedAt || latestCompletedRun?.startedAt || null;
+    const lastRunAgeMs = hasValidIsoTime(lastRunAt) ? Date.now() - Date.parse(lastRunAt) : null;
+    const stale = lastRunAgeMs == null || lastRunAgeMs >= kDoctorStaleThresholdMs;
+    const baselineRun = latestCompletedRun;
+    const initialBaseline = !baselineRun ? getOrCreateInitialBaseline() : null;
+    const currentSnapshot = baselineRun || initialBaseline ? getCurrentWorkspaceSnapshot() : null;
+    const baselineManifest =
+      baselineRun?.workspaceManifest && typeof baselineRun.workspaceManifest === "object"
+        ? baselineRun.workspaceManifest
+        : initialBaseline?.manifest && typeof initialBaseline.manifest === "object"
+          ? initialBaseline.manifest
+          : null;
+    const hasManifestBaseline = !!baselineManifest;
+    const delta =
+      hasManifestBaseline && currentSnapshot
+        ? calculateWorkspaceDelta({
+            previousManifest: baselineManifest,
+            currentManifest: currentSnapshot.manifest,
+          })
+        : {
+            addedFilesCount: 0,
+            removedFilesCount: 0,
+            modifiedFilesCount: 0,
+            changedFilesCount: 0,
+            deltaScore: 0,
+            changedPaths: [],
+          };
+    const hasMeaningfulChanges =
+      !!latestCompletedRun &&
+      delta.deltaScore >= kDoctorMeaningfulChangeScoreThreshold;
+    return {
+      activeRunId: state.activeRunId || 0,
+      runInProgress: !!state.activeRunPromise,
+      lastRunAt,
+      lastRunAgeMs,
+      needsInitialRun: !latestCompletedRun,
+      stale,
+      changeSummary: {
+        ...delta,
+        hasBaseline: hasManifestBaseline,
+        baselineSource: baselineRun ? "last_run" : initialBaseline ? "initial_install" : "none",
+        hasMeaningfulChanges,
+      },
+      latestRun,
+    };
+  };
+
+  const executeDoctorRun = async (runId) => {
+    try {
+      const prompt = buildDoctorPrompt({
+        workspaceRoot,
+        managedRoot,
+        protectedPaths,
+        lockedPaths,
+        promptVersion: kDoctorPromptVersion,
+      });
+      const gatewayTimeoutMs = kDoctorRunTimeoutMs + 30000;
+      const gatewayParams = {
+        agentId: "main",
+        idempotencyKey: buildDoctorIdempotencyKey(runId),
+        message: prompt,
+        sessionKey: buildDoctorSessionKey(runId),
+        thinking: "medium",
+        timeout: Math.round(kDoctorRunTimeoutMs / 1000),
+      };
+      const result = await clawCmd(
+        `gateway call agent --expect-final --json --timeout ${gatewayTimeoutMs} --params ${shellEscapeArg(
+          JSON.stringify(gatewayParams),
+        )}`,
+        {
+          quiet: true,
+          timeoutMs: gatewayTimeoutMs,
+        },
+      );
+      if (!result?.ok) {
+        throw new Error(result?.stderr || "Doctor analysis command failed");
+      }
+      const stdoutText = String(result.stdout || "");
+      const stderrText = String(result.stderr || "");
+      console.log(
+        `[doctor] run ${runId} command result ok=${result.ok} code=${result.code ?? 0} stdout_chars=${stdoutText.length} stderr_chars=${stderrText.length}`,
+      );
+      let normalizedResult = null;
+      try {
+        normalizedResult = normalizeDoctorResult(stdoutText);
+      } catch (error) {
+        console.error(
+          `[doctor] run ${runId} normalize failed: ${error.message || "Unknown error"}`,
+        );
+        console.error(`[doctor] run ${runId} stdout begin`);
+        console.error(stdoutText || "(empty)");
+        console.error(`[doctor] run ${runId} stdout end`);
+        console.error(`[doctor] run ${runId} stderr begin`);
+        console.error(stderrText || "(empty)");
+        console.error(`[doctor] run ${runId} stderr end`);
+        throw error;
+      }
+      insertDoctorCards({
+        runId,
+        cards: normalizedResult.cards,
+      });
+      completeDoctorRun({
+        id: runId,
+        status: kDoctorRunStatus.completed,
+        summary: normalizedResult.summary,
+        rawResult: normalizedResult.rawPayload,
+      });
+    } catch (error) {
+      completeDoctorRun({
+        id: runId,
+        status: kDoctorRunStatus.failed,
+        error: error.message || "Doctor run failed",
+      });
+    } finally {
+      state.activeRunId = 0;
+      state.activeRunPromise = null;
+    }
+  };
+
+  const runDoctor = () => {
+    if (state.activeRunPromise) {
+      return {
+        ok: false,
+        alreadyRunning: true,
+        runId: state.activeRunId || 0,
+        status: buildStatus(),
+        error: "Doctor run already in progress",
+      };
+    }
+    const workspaceSnapshot = getCurrentWorkspaceSnapshot();
+    const workspaceFingerprint = workspaceSnapshot.fingerprint;
+    const latestCompletedRun = getLatestCompletedRun();
+    if (
+      latestCompletedRun &&
+      latestCompletedRun.workspaceFingerprint &&
+      latestCompletedRun.workspaceFingerprint === workspaceFingerprint
+    ) {
+      const runId = createDoctorRun({
+        status: kDoctorRunStatus.completed,
+        engine: kDoctorEngine.deterministicReuse,
+        workspaceRoot,
+        workspaceFingerprint,
+        workspaceManifest: workspaceSnapshot.manifest,
+        promptVersion: kDoctorPromptVersion,
+        reusedFromRunId: latestCompletedRun.id,
+      });
+      cloneRunCards({
+        sourceRunId: latestCompletedRun.id,
+        targetRunId: runId,
+      });
+      const summary = `No workspace changes since last scan (${formatElapsedSince(
+        latestCompletedRun.completedAt || latestCompletedRun.startedAt,
+      )}). Same findings apply.`;
+      completeDoctorRun({
+        id: runId,
+        status: kDoctorRunStatus.completed,
+        summary,
+        rawResult: latestCompletedRun.rawResult,
+      });
+      return {
+        ok: true,
+        runId,
+        reusedPreviousRun: true,
+        sourceRunId: latestCompletedRun.id,
+        status: buildStatus(),
+      };
+    }
+    const runId = createDoctorRun({
+      status: kDoctorRunStatus.running,
+      engine: kDoctorEngine.gatewayAgent,
+      workspaceRoot,
+      workspaceFingerprint,
+      workspaceManifest: workspaceSnapshot.manifest,
+      promptVersion: kDoctorPromptVersion,
+    });
+    state.activeRunId = runId;
+    state.activeRunPromise = executeDoctorRun(runId);
+    return {
+      ok: true,
+      runId,
+      status: buildStatus(),
+    };
+  };
+
+  const importDoctorResult = ({
+    rawOutput,
+    engine = kDoctorEngine.manualImport,
+  } = {}) => {
+    const normalizedRawOutput = String(rawOutput || "");
+    if (!normalizedRawOutput.trim()) {
+      throw new Error("Doctor import requires raw output");
+    }
+    const normalizedResult = normalizeDoctorResult(normalizedRawOutput);
+    const workspaceSnapshot = getCurrentWorkspaceSnapshot();
+    const runId = createDoctorRun({
+      status: kDoctorRunStatus.completed,
+      engine,
+      workspaceRoot,
+      workspaceFingerprint: workspaceSnapshot.fingerprint,
+      workspaceManifest: workspaceSnapshot.manifest,
+      promptVersion: kDoctorPromptVersion,
+    });
+    insertDoctorCards({
+      runId,
+      cards: normalizedResult.cards,
+    });
+    completeDoctorRun({
+      id: runId,
+      status: kDoctorRunStatus.completed,
+      summary: normalizedResult.summary,
+      rawResult: normalizedResult.rawPayload,
+    });
+    return {
+      ok: true,
+      runId,
+      run: getDoctorRun(runId),
+    };
+  };
+
+  const requestCardFix = async ({
+    cardId,
+    sessionId = "",
+    replyChannel = "",
+    replyTo = "",
+  } = {}) => {
+    const card = getDoctorCard(cardId);
+    if (!card) throw new Error("Doctor card not found");
+    const prompt = String(card.fixPrompt || "").trim();
+    if (!prompt) throw new Error("Doctor card does not include a fix prompt");
+    let command = `agent --agent main --message ${shellEscapeArg(prompt)}`;
+    const trimmedSessionId = String(sessionId || "").trim();
+    const trimmedReplyChannel = String(replyChannel || "").trim();
+    const trimmedReplyTo = String(replyTo || "").trim();
+    if (trimmedReplyChannel && trimmedReplyTo) {
+      command +=
+        ` --deliver --reply-channel ${shellEscapeArg(trimmedReplyChannel)}` +
+        ` --reply-to ${shellEscapeArg(trimmedReplyTo)}`;
+    } else if (trimmedSessionId) {
+      command += ` --session-id ${shellEscapeArg(trimmedSessionId)}`;
+    }
+    const result = await clawCmd(command, {
+      quiet: true,
+      timeoutMs: kDoctorRunTimeoutMs,
+    });
+    if (!result?.ok) {
+      throw new Error(result?.stderr || "Could not send Doctor fix request");
+    }
+    return {
+      ok: true,
+      stdout: result.stdout || "",
+      card,
+    };
+  };
+
+  const setCardStatus = ({ cardId, status }) => {
+    const updatedCard = updateDoctorCardStatus({
+      id: cardId,
+      status,
+    });
+    if (!updatedCard) throw new Error("Doctor card not found");
+    return updatedCard;
+  };
+
+  return {
+    buildStatus,
+    runDoctor,
+    importDoctorResult,
+    listDoctorRuns,
+    listDoctorCards,
+    getDoctorRun,
+    getDoctorCardsByRunId,
+    requestCardFix,
+    setCardStatus,
+    getDoctorCard,
+  };
+};
+
+module.exports = {
+  buildDoctorIdempotencyKey,
+  buildDoctorSessionKey,
+  buildDoctorSessionId,
+  createDoctorService,
+};

package/lib/server/doctor/workspace-fingerprint.js

@@ -0,0 +1,126 @@
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+
+const kIgnoredDirectoryNames = new Set([".git", "node_modules"]);
+
+const hashFile = (filePath) => {
+  const buffer = fs.readFileSync(filePath);
+  return crypto.createHash("sha256").update(buffer).digest("hex");
+};
+
+const normalizeRelativePath = (rootDir, filePath) =>
+  path.relative(rootDir, filePath).split(path.sep).join("/");
+
+const walkFiles = (rootDir, currentDir = rootDir) => {
+  const entries = fs.readdirSync(currentDir, { withFileTypes: true });
+  const sortedEntries = [...entries].sort((left, right) => left.name.localeCompare(right.name));
+  const files = [];
+
+  for (const entry of sortedEntries) {
+    if (entry.isDirectory()) {
+      if (kIgnoredDirectoryNames.has(entry.name)) continue;
+      files.push(...walkFiles(rootDir, path.join(currentDir, entry.name)));
+      continue;
+    }
+    if (!entry.isFile()) continue;
+    files.push(path.join(currentDir, entry.name));
+  }
+
+  return files;
+};
+
+const buildWorkspaceManifest = (rootDir) => {
+  const normalizedRootDir = path.resolve(String(rootDir || ""));
+  const files = walkFiles(normalizedRootDir);
+  return files.reduce((manifest, filePath) => {
+    manifest[normalizeRelativePath(normalizedRootDir, filePath)] = hashFile(filePath);
+    return manifest;
+  }, {});
+};
+
+const computeWorkspaceFingerprintFromManifest = (manifest = {}) => {
+  const hash = crypto.createHash("sha256");
+  const entries = Object.entries(manifest).sort(([leftPath], [rightPath]) =>
+    leftPath.localeCompare(rightPath),
+  );
+
+  hash.update("workspace-fingerprint-v1");
+  for (const [relativePath, fileHash] of entries) {
+    hash.update(relativePath);
+    hash.update("\0");
+    hash.update(fileHash);
+    hash.update("\0");
+  }
+
+  return hash.digest("hex");
+};
+
+const computeWorkspaceSnapshot = (rootDir) => {
+  const manifest = buildWorkspaceManifest(rootDir);
+  return {
+    fingerprint: computeWorkspaceFingerprintFromManifest(manifest),
+    manifest,
+  };
+};
+
+const getPathChangeWeight = (relativePath = "") => {
+  const normalizedPath = String(relativePath || "").trim().toLowerCase();
+  if (!normalizedPath) return 1;
+  if (
+    normalizedPath === "agents.md" ||
+    normalizedPath === "tools.md" ||
+    normalizedPath === "readme.md" ||
+    normalizedPath === "bootstrap.md" ||
+    normalizedPath === "memory.md" ||
+    normalizedPath === "user.md" ||
+    normalizedPath === "identity.md"
+  ) {
+    return 4;
+  }
+  if (normalizedPath.startsWith("hooks/bootstrap/")) return 4;
+  if (normalizedPath.startsWith("skills/")) return 3;
+  if (normalizedPath.endsWith(".md")) return 2;
+  return 1;
+};
+
+const calculateWorkspaceDelta = ({ previousManifest = {}, currentManifest = {} } = {}) => {
+  const previousPaths = Object.keys(previousManifest);
+  const currentPaths = Object.keys(currentManifest);
+  const allPaths = Array.from(new Set([...previousPaths, ...currentPaths])).sort((left, right) =>
+    left.localeCompare(right),
+  );
+  const changeSummary = {
+    addedFilesCount: 0,
+    removedFilesCount: 0,
+    modifiedFilesCount: 0,
+    changedFilesCount: 0,
+    deltaScore: 0,
+    changedPaths: [],
+  };
+
+  for (const relativePath of allPaths) {
+    const previousHash = previousManifest[relativePath] || "";
+    const currentHash = currentManifest[relativePath] || "";
+    if (!previousHash && currentHash) {
+      changeSummary.addedFilesCount += 1;
+    } else if (previousHash && !currentHash) {
+      changeSummary.removedFilesCount += 1;
+    } else if (previousHash !== currentHash) {
+      changeSummary.modifiedFilesCount += 1;
+    } else {
+      continue;
+    }
+    changeSummary.changedFilesCount += 1;
+    changeSummary.deltaScore += getPathChangeWeight(relativePath);
+    changeSummary.changedPaths.push(relativePath);
+  }
+
+  return changeSummary;
+};
+
+module.exports = {
+  calculateWorkspaceDelta,
+  computeWorkspaceFingerprintFromManifest,
+  computeWorkspaceSnapshot,
+};

package/lib/server/routes/doctor.js

@@ -0,0 +1,123 @@
+const { kDoctorCardStatus, kDoctorDefaultRunsLimit } = require("../doctor/constants");
+
+const registerDoctorRoutes = ({ app, requireAuth, doctorService }) => {
+  app.get("/api/doctor/status", requireAuth, (req, res) => {
+    try {
+      res.json({ ok: true, status: doctorService.buildStatus() });
+    } catch (error) {
+      res.status(500).json({ ok: false, error: error.message });
+    }
+  });
+
+  app.post("/api/doctor/run", requireAuth, (req, res) => {
+    try {
+      const result = doctorService.runDoctor();
+      if (!result.ok && result.alreadyRunning) {
+        return res.status(409).json(result);
+      }
+      return res.status(result.reusedPreviousRun ? 200 : 202).json(result);
+    } catch (error) {
+      return res.status(500).json({ ok: false, error: error.message });
+    }
+  });
+
+  app.post("/api/doctor/import", requireAuth, (req, res) => {
+    try {
+      const result = doctorService.importDoctorResult({
+        rawOutput: req.body?.rawOutput,
+      });
+      return res.status(201).json(result);
+    } catch (error) {
+      return res.status(400).json({ ok: false, error: error.message });
+    }
+  });
+
+  app.get("/api/doctor/runs", requireAuth, (req, res) => {
+    try {
+      const limit = Number.parseInt(String(req.query.limit || kDoctorDefaultRunsLimit), 10);
+      const runs = doctorService.listDoctorRuns({ limit });
+      res.json({ ok: true, runs });
+    } catch (error) {
+      res.status(500).json({ ok: false, error: error.message });
+    }
+  });
+
+  app.get("/api/doctor/cards", requireAuth, (req, res) => {
+    try {
+      const runId = String(req.query.runId || "").trim();
+      const cards = doctorService.listDoctorCards({
+        runId: runId || "all",
+      });
+      return res.json({ ok: true, cards });
+    } catch (error) {
+      return res.status(500).json({ ok: false, error: error.message });
+    }
+  });
+
+  app.get("/api/doctor/runs/:id", requireAuth, (req, res) => {
+    try {
+      const run = doctorService.getDoctorRun(req.params.id);
+      if (!run) {
+        return res.status(404).json({ ok: false, error: "Doctor run not found" });
+      }
+      return res.json({ ok: true, run });
+    } catch (error) {
+      return res.status(500).json({ ok: false, error: error.message });
+    }
+  });
+
+  app.get("/api/doctor/runs/:id/cards", requireAuth, (req, res) => {
+    try {
+      const run = doctorService.getDoctorRun(req.params.id);
+      if (!run) {
+        return res.status(404).json({ ok: false, error: "Doctor run not found" });
+      }
+      const cards = doctorService.getDoctorCardsByRunId(req.params.id);
+      return res.json({ ok: true, cards });
+    } catch (error) {
+      return res.status(500).json({ ok: false, error: error.message });
+    }
+  });
+
+  app.post("/api/doctor/cards/:id/status", requireAuth, (req, res) => {
+    try {
+      const requestedStatus = String(req.body?.status || "").trim().toLowerCase();
+      if (
+        requestedStatus !== kDoctorCardStatus.open &&
+        requestedStatus !== kDoctorCardStatus.dismissed &&
+        requestedStatus !== kDoctorCardStatus.fixed
+      ) {
+        return res.status(400).json({ ok: false, error: "Invalid Doctor card status" });
+      }
+      const card = doctorService.setCardStatus({
+        cardId: req.params.id,
+        status: requestedStatus,
+      });
+      return res.json({ ok: true, card });
+    } catch (error) {
+      if (/not found/i.test(error.message || "")) {
+        return res.status(404).json({ ok: false, error: error.message });
+      }
+      return res.status(400).json({ ok: false, error: error.message });
+    }
+  });
+
+  app.post("/api/doctor/findings/:id/fix", requireAuth, async (req, res) => {
+    try {
+      const result = await doctorService.requestCardFix({
+        cardId: req.params.id,
+        sessionId: req.body?.sessionId,
+        replyChannel: req.body?.replyChannel,
+        replyTo: req.body?.replyTo,
+      });
+      return res.json(result);
+    } catch (error) {
+      if (/not found/i.test(error.message || "")) {
+        return res.status(404).json({ ok: false, error: error.message });
+      }
+      return res.status(400).json({ ok: false, error: error.message });
+    }
+  });
+};
+
+module.exports = { registerDoctorRoutes };

package/lib/server/routes/system.js

@@ -90,7 +90,13 @@ const registerSystemRoutes = ({
       .filter((sessionRow) => {
         const key = String(sessionRow?.key || "").toLowerCase();
         if (!key) return false;
-        if (key.includes(":hook:") || key.includes(":cron:")) return false;
+        if (
+          key.includes(":hook:") ||
+          key.includes(":cron:") ||
+          key.includes(":doctor:")
+        ) {
+          return false;
+        }
         return true;
       })
       .map((sessionRow) => {