@chrysb/alphaclaw 0.4.4 → 0.4.6-beta.0

package/lib/server/doctor/normalize.js

@@ -0,0 +1,214 @@
+const {
+  parseJsonSafe,
+  parseJsonValueFromNoisyOutput,
+} = require("../utils/json");
+const {
+  kDoctorCardStatus,
+  kDoctorPriority,
+  kDoctorMaxCardsPerRun,
+} = require("./constants");
+
+const kCandidateArrayKeys = ["cards", "findings", "issues", "recommendations"];
+const kCandidateObjectKeys = [
+  "result",
+  "data",
+  "output",
+  "response",
+  "message",
+  "content",
+  "text",
+  "payload",
+  "payloads",
+  "body",
+];
+
+const toTrimmedString = (value) => String(value ?? "").trim();
+
+const parseJsonCandidate = (value) => {
+  if (value == null) return null;
+  if (typeof value === "object") return value;
+  if (typeof value !== "string") return null;
+  const direct = parseJsonSafe(value, null, { trim: true });
+  if (direct) return direct;
+  const noisy = parseJsonValueFromNoisyOutput(value);
+  if (noisy) return noisy;
+  const fencedMatch = value.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  if (!fencedMatch) return null;
+  return parseJsonSafe(fencedMatch[1], null, { trim: true });
+};
+
+const collectCandidatePayloads = (rootValue) => {
+  const queue = [rootValue];
+  const seen = new Set();
+  const candidates = [];
+  while (queue.length) {
+    const currentValue = queue.shift();
+    if (currentValue == null) continue;
+    if (typeof currentValue === "string") {
+      const parsedValue = parseJsonCandidate(currentValue);
+      if (parsedValue && typeof parsedValue === "object") {
+        queue.push(parsedValue);
+      }
+      continue;
+    }
+    if (typeof currentValue !== "object") continue;
+    if (seen.has(currentValue)) continue;
+    seen.add(currentValue);
+    if (Array.isArray(currentValue)) {
+      for (const item of currentValue) {
+        if (item != null) queue.push(item);
+      }
+      continue;
+    }
+    candidates.push(currentValue);
+    for (const key of kCandidateObjectKeys) {
+      if (currentValue[key] != null) queue.push(currentValue[key]);
+    }
+  }
+  return candidates;
+};
+
+const normalizePriority = (value) => {
+  const normalized = toTrimmedString(value).toUpperCase();
+  if (normalized === "P0" || normalized === "CRITICAL" || normalized === "HIGH") {
+    return kDoctorPriority.P0;
+  }
+  if (normalized === "P1" || normalized === "MEDIUM" || normalized === "MODERATE") {
+    return kDoctorPriority.P1;
+  }
+  if (normalized === "P2" || normalized === "LOW" || normalized === "NICE_TO_HAVE") {
+    return kDoctorPriority.P2;
+  }
+  return kDoctorPriority.P2;
+};
+
+const normalizeCardStatus = (value) => {
+  const normalized = toTrimmedString(value).toLowerCase();
+  if (normalized === kDoctorCardStatus.fixed) return kDoctorCardStatus.fixed;
+  if (normalized === kDoctorCardStatus.dismissed) return kDoctorCardStatus.dismissed;
+  return kDoctorCardStatus.open;
+};
+
+const normalizeEvidence = (value) => {
+  if (Array.isArray(value)) {
+    return value
+      .map((item) => {
+        if (item == null) return null;
+        if (typeof item === "string") {
+          const text = toTrimmedString(item);
+          return text ? { type: "text", text } : null;
+        }
+        if (typeof item === "object") return item;
+        return { type: "text", text: String(item) };
+      })
+      .filter(Boolean);
+  }
+  if (typeof value === "string") {
+    const text = toTrimmedString(value);
+    return text ? [{ type: "text", text }] : [];
+  }
+  if (value && typeof value === "object") return [value];
+  return [];
+};
+
+const normalizeTargetPaths = (value) => {
+  const values = Array.isArray(value) ? value : value == null ? [] : [value];
+  return Array.from(
+    new Set(
+      values
+        .map((item) => toTrimmedString(item))
+        .filter(Boolean),
+    ),
+  );
+};
+
+const buildFallbackFixPrompt = ({ title, recommendation, targetPaths }) => {
+  const targetLine = targetPaths.length
+    ? `Focus on these paths if relevant: ${targetPaths.join(", ")}.`
+    : "Inspect the relevant workspace files before making changes.";
+  return (
+    `Please address this Doctor finding safely.\n\n` +
+    `Finding: ${title}\n` +
+    `Recommendation: ${recommendation}\n` +
+    `${targetLine}\n` +
+    `Preserve existing behavior unless the change clearly improves workspace guidance organization.`
+  );
+};
+
+const normalizeDoctorCard = (cardValue, index) => {
+  const title =
+    toTrimmedString(cardValue?.title) ||
+    toTrimmedString(cardValue?.headline) ||
+    toTrimmedString(cardValue?.name) ||
+    `Doctor recommendation ${index + 1}`;
+  const summary =
+    toTrimmedString(cardValue?.summary) ||
+    toTrimmedString(cardValue?.description) ||
+    toTrimmedString(cardValue?.detail) ||
+    "";
+  const recommendation =
+    toTrimmedString(cardValue?.recommendation) ||
+    toTrimmedString(cardValue?.recommendedAction) ||
+    toTrimmedString(cardValue?.action) ||
+    summary ||
+    title;
+  const targetPaths = normalizeTargetPaths(
+    cardValue?.targetPaths ?? cardValue?.paths ?? cardValue?.files,
+  );
+  return {
+    priority: normalizePriority(cardValue?.priority ?? cardValue?.severity),
+    category: toTrimmedString(cardValue?.category) || "workspace",
+    title,
+    summary,
+    recommendation,
+    evidence: normalizeEvidence(cardValue?.evidence),
+    targetPaths,
+    fixPrompt:
+      toTrimmedString(cardValue?.fixPrompt) ||
+      toTrimmedString(cardValue?.fix_prompt) ||
+      buildFallbackFixPrompt({ title, recommendation, targetPaths }),
+    status: normalizeCardStatus(cardValue?.status),
+  };
+};
+
+const extractCardPayload = (payload) => {
+  if (!payload || typeof payload !== "object") return null;
+  for (const key of kCandidateArrayKeys) {
+    if (!Array.isArray(payload[key])) continue;
+    return {
+      summary:
+        toTrimmedString(payload.summary) ||
+        toTrimmedString(payload.overview) ||
+        toTrimmedString(payload.assessment) ||
+        "",
+      cards: payload[key],
+      rawPayload: payload,
+    };
+  }
+  return null;
+};
+
+const normalizeDoctorResult = (rawOutput) => {
+  const initialPayload = parseJsonCandidate(rawOutput);
+  const payloadCandidates = collectCandidatePayloads(initialPayload || rawOutput);
+  for (const candidate of payloadCandidates) {
+    const extracted = extractCardPayload(candidate);
+    if (!extracted) continue;
+    const cards = extracted.cards
+      .slice(0, kDoctorMaxCardsPerRun)
+      .map((cardValue, index) => normalizeDoctorCard(cardValue, index));
+    return {
+      summary: extracted.summary,
+      cards,
+      rawPayload: extracted.rawPayload,
+    };
+  }
+  throw new Error("Doctor response did not include a recognizable cards payload");
+};
+
+module.exports = {
+  normalizePriority,
+  normalizeCardStatus,
+  normalizeDoctorResult,
+  normalizeDoctorCard,
+};

package/lib/server/doctor/prompt.js

@@ -0,0 +1,89 @@
+const renderList = (items = []) =>
+  items.length ? items.map((item) => `- ${item}`).join("\n") : "- (none)";
+
+const buildDoctorPrompt = ({
+  workspaceRoot = "",
+  managedRoot = "",
+  protectedPaths = [],
+  lockedPaths = [],
+  promptVersion = "doctor-v1",
+}) => `
+You are AlphaClaw Doctor. Analyze this OpenClaw workspace for guidance drift, redundancy, misplacement, and cleanup opportunities.
+
+Important:
+- Read the workspace and managed files as needed before deciding.
+- This is advisory only. Do not make changes.
+- Focus on organization and correctness of workspace guidance and setup-owned files.
+- Prefer fewer, higher-signal findings.
+- Avoid reporting issues that are already intentionally managed or locked by AlphaClaw.
+- Evaluate files against intended OpenClaw defaults, not against an idealized minimal workspace.
+- A fresh install can be healthy even if it includes broad default guidance.
+- Return ONLY valid JSON. No markdown fences. No extra prose.
+
+OpenClaw default context:
+- \`AGENTS.md\` is the workspace home file in the default OpenClaw template. It may intentionally include first-run instructions, session-startup guidance, memory conventions, safety rules, tool pointers, and optional behavioral guidance.
+- Do not treat default-template content as drift just because it is broad or multi-purpose.
+- Only flag \`AGENTS.md\` when there is clear workspace-specific drift, contradiction, substantial unnecessary local accretion, or guidance that no longer fits the file's intended role.
+
+AlphaClaw ownership rules:
+- AlphaClaw-managed files and bootstrap files are product-owned constraints.
+- Do not recommend splitting, renaming, relocating, or otherwise restructuring AlphaClaw-managed files solely for cleanliness or purity.
+- Do not propose breaking changes to AlphaClaw's managed file layout, even if another structure might look cleaner.
+- Only flag AlphaClaw-managed content when there is a concrete correctness issue, internal contradiction, broken ownership boundary, or behavior that is actively misleading.
+
+Workspace roots:
+- Primary workspace root: ${workspaceRoot || "(unknown)"}
+- Managed OpenClaw root: ${managedRoot || "(unknown)"}
+
+AlphaClaw protected paths:
+${renderList(protectedPaths)}
+
+AlphaClaw locked/managed paths:
+${renderList(lockedPaths)}
+
+Review priorities:
+- Drift between workspace reality and AGENTS.md, TOOLS.md, SKILL.md, README, and setup-owned docs
+- Redundant or scattered instructions that should be centralized
+- Tool-specific guidance placed in the wrong file
+- Workspace cleanup and consolidation opportunities
+- Real contradictions or misleading guidance inside AlphaClaw-managed files
+
+Priority rubric:
+- P0: dangerous drift, broken setup ownership, or issues likely to cause incorrect agent behavior
+- P1: meaningful duplication, misplaced guidance, or organizational drift with clear cleanup value
+- P2: nice-to-have consolidation and lower-risk cleanup opportunities
+
+Return exactly this JSON shape:
+{
+  "summary": "short overall assessment",
+  "cards": [
+    {
+      "priority": "P0 | P1 | P2",
+      "category": "short category",
+      "title": "short title",
+      "summary": "what is wrong and why it matters",
+      "recommendation": "clear recommended action",
+      "evidence": [
+        { "type": "path", "path": "relative/path" },
+        { "type": "note", "text": "short supporting note" }
+      ],
+      "targetPaths": ["relative/path/one", "relative/path/two"],
+      "fixPrompt": "a concise message another agent can use to fix just this finding safely",
+      "status": "open"
+    }
+  ]
+}
+
+Constraints:
+- Maximum 12 cards
+- Use relative paths in evidence and targetPaths
+- Do not include duplicate cards
+- Do not create cards for healthy default-template behavior
+- Do not create cards whose primary recommendation is to refactor AlphaClaw-managed file structure
+- If there are no meaningful findings, return an empty cards array
+- promptVersion: ${promptVersion}
+`.trim();
+
+module.exports = {
+  buildDoctorPrompt,
+};

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,
+};