Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript
8.4 KB
Raw Blame
import { mkdirSync, rmSync, statSync } from "node:fs";
import { join } from "node:path";

import { appendAuditRecord, type AuditRecord } from "../reliability/audit.ts";
import { buildProbeReport, type ProbeCheck, type ProbeReport } from "../reliability/probe.ts";
import { WATCHDOG_AUDIT_DIR, WATCHDOG_FALLBACK_AUDIT_DIR } from "./audit-dirs.ts";
import { DERIVED_STORE_DIR } from "./path-constants.ts";
import { resolveConfiguredIndexPath } from "../search/paths.ts";
import {
  BRAIN_CONFIG_FILE,
  BRAIN_INBOX_REL,
  BRAIN_LOG_REL,
  BRAIN_PREFERENCES_REL,
  BRAIN_PROCESSED_REL,
  BRAIN_RETIRED_REL,
  brainConfigPath,
  brainDirs,
  brainDirsForWrite,
} from "./paths.ts";

export interface WatchdogOptions {
  readonly remediate?: boolean;
  readonly dryRun?: boolean;
  readonly restoreRunId?: string;
  readonly forceRestore?: boolean;
  readonly attempt?: number;
  readonly now?: Date;
}

export interface WatchdogRemediation {
  readonly action: "create-dir" | "run-command" | "restore-snapshot";
  readonly target?: string;
  readonly command?: string;
  readonly safe: boolean;
  readonly applied?: boolean;
}

export interface WatchdogRestoreState {
  readonly requested: boolean;
  readonly refused: boolean;
  readonly run_id?: string;
  readonly command?: string;
  readonly reason?: string;
}

export interface WatchdogBackoff {
  readonly attempt: number;
  readonly base_delay_ms: number;
  readonly next_delay_ms: number;
  readonly max_delay_ms: number;
}

export interface BrainWatchdogResult {
  readonly report: ProbeReport;
  readonly remediation_plan: ReadonlyArray<WatchdogRemediation>;
  readonly applied_remediations: ReadonlyArray<WatchdogRemediation>;
  readonly restore: WatchdogRestoreState;
  readonly backoff: WatchdogBackoff;
  readonly audit_path: string;
}

const REQUIRED_DIRS: ReadonlyArray<{
  rel: string;
  pathKey: keyof ReturnType<typeof brainDirs>;
}> = [
  { rel: BRAIN_PREFERENCES_REL, pathKey: "preferences" },
  { rel: BRAIN_RETIRED_REL, pathKey: "retired" },
  { rel: BRAIN_INBOX_REL, pathKey: "inbox" },
  { rel: BRAIN_PROCESSED_REL, pathKey: "processed" },
  { rel: BRAIN_LOG_REL, pathKey: "log" },
];

export function runBrainWatchdog(vault: string, opts: WatchdogOptions = {}): BrainWatchdogResult {
  const now = opts.now ?? new Date();
  const checks: ProbeCheck[] = [];
  const remediationPlan: WatchdogRemediation[] = [];
  const applied: WatchdogRemediation[] = [];
  // Write-intent unconditionally (context-integrity-gates, Unit J): a
  // remediating run creates or replaces the directories below, and EVERY
  // run - probe included - appends its audit record into `dirs.log`.
  const dirs = brainDirsForWrite(vault);

  const configPath = brainConfigPath(vault);
  const configKind = pathKind(configPath);
  if (configKind === "file") {
    checks.push({
      name: "brain-config",
      status: "ok",
      message: `${BRAIN_CONFIG_FILE} exists`,
    });
  } else {
    checks.push({
      name: "brain-config",
      status: "critical",
      message:
        configKind === "missing"
          ? `${BRAIN_CONFIG_FILE} is missing`
          : `${BRAIN_CONFIG_FILE} is not a file`,
      remediation: "run o2b brain init",
    });
    remediationPlan.push({
      action: "run-command",
      command: "o2b brain init",
      safe: false,
    });
  }

  for (const dir of REQUIRED_DIRS) {
    const abs = dirs[dir.pathKey];
    const kind = pathKind(abs);
    if (kind === "directory") {
      checks.push({
        name: `dir:${dir.rel}`,
        status: "ok",
        message: `${dir.rel} exists`,
      });
      continue;
    }
    checks.push({
      name: `dir:${dir.rel}`,
      status: "warning",
      message: kind === "missing" ? `${dir.rel} is missing` : `${dir.rel} is not a directory`,
      remediation: kind === "missing" ? `create ${dir.rel}` : `replace with directory ${dir.rel}`,
    });
    const remediation: WatchdogRemediation = {
      action: "create-dir",
      target: dir.rel,
      safe: true,
    };
    remediationPlan.push(remediation);
    if (opts.remediate && !opts.dryRun) {
      if (kind !== "missing") rmSync(abs, { recursive: true, force: true });
      mkdirSync(abs, { recursive: true });
      applied.push({ ...remediation, applied: true });
    }
  }

  const indexPath = resolveConfiguredIndexPath(vault);
  const indexKind = pathKind(indexPath);
  if (indexKind === "file") {
    checks.push({
      name: "search-index",
      status: "ok",
      message: "search index exists",
    });
  } else {
    checks.push({
      name: "search-index",
      status: "warning",
      message:
        indexKind === "missing"
          ? "search index is missing or not yet built"
          : "search index path is not a file",
      remediation: "run o2b search reindex",
    });
    remediationPlan.push({
      action: "run-command",
      command: "o2b search reindex",
      safe: true,
    });
  }

  const restore = buildRestoreState(opts.restoreRunId, opts.forceRestore === true);
  if (restore.requested) {
    checks.push({
      name: "snapshot-restore",
      status: restore.refused ? "critical" : "warning",
      message: restore.refused
        ? "snapshot restore refused without --force-restore"
        : "snapshot restore is explicit and force-enabled; delegate to rollback command",
      remediation: restore.command,
    });
    if (restore.command) {
      remediationPlan.push({
        action: "restore-snapshot",
        command: restore.command,
        safe: false,
      });
    }
  }

  const report = buildProbeReport(checks);
  const backoff = buildBackoff(opts.attempt ?? 0);
  const auditRecord: AuditRecord = {
    timestamp: now.toISOString(),
    actor: "watchdog",
    action: "brain_watchdog",
    target: "Brain",
    ok: report.counts.critical === 0,
    details: {
      counts: report.counts,
      remediate: opts.remediate === true,
      dry_run: opts.dryRun === true,
      applied: applied.length,
      restore,
      backoff,
    },
  };
  const auditPath = appendWatchdogAudit(vault, dirs.log, auditRecord);

  return {
    report,
    remediation_plan: Object.freeze(remediationPlan),
    applied_remediations: Object.freeze(applied),
    restore,
    backoff,
    audit_path: auditPath,
  };
}

function buildRestoreState(runId: string | undefined, force: boolean): WatchdogRestoreState {
  if (runId === undefined || runId.trim() === "") return { requested: false, refused: false };
  const trimmed = runId.trim();
  if (!/^[A-Za-z0-9._-]+$/.test(trimmed)) {
    return {
      requested: true,
      refused: true,
      run_id: trimmed,
      reason:
        "snapshot restore run id must contain only letters, numbers, dot, dash, and underscore",
    };
  }
  if (!force) {
    return {
      requested: true,
      refused: true,
      run_id: trimmed,
      reason:
        "snapshot restore requires --force-restore and should normally be run through rollback",
    };
  }
  return {
    requested: true,
    refused: false,
    run_id: trimmed,
    command: `o2b brain rollback ${trimmed} --yes --force-rollback`,
  };
}

function pathKind(path: string): "file" | "directory" | "other" | "missing" {
  try {
    const stat = statSync(path);
    if (stat.isFile()) return "file";
    if (stat.isDirectory()) return "directory";
    return "other";
  } catch (error) {
    if ((error as NodeJS.ErrnoException).code === "ENOENT") return "missing";
    throw error;
  }
}

/**
 * Where a watchdog record lands when its `Brain/log/` directory refuses
 * the write: `.open-second-brain/watchdog-audit/`. Exported so the
 * doctor's sync-conflict sweep visits the directory this module writes.
 */
export function watchdogFallbackAuditDir(vault: string): string {
  return join(vault, DERIVED_STORE_DIR, WATCHDOG_FALLBACK_AUDIT_DIR);
}

function appendWatchdogAudit(vault: string, logDir: string, record: AuditRecord): string {
  try {
    return appendAuditRecord(join(logDir, WATCHDOG_AUDIT_DIR), record, vault);
  } catch (error) {
    return appendAuditRecord(
      watchdogFallbackAuditDir(vault),
      {
        ...record,
        ok: false,
        details: {
          ...record.details,
          audit_fallback_reason: (error as Error).message ?? String(error),
        },
      },
      vault,
    );
  }
}

function buildBackoff(attempt: number): WatchdogBackoff {
  const safeAttempt = Math.max(0, Math.floor(attempt));
  const base = 1000;
  const max = 60_000;
  return {
    attempt: safeAttempt,
    base_delay_ms: base,
    next_delay_ms: Math.min(max, base * 2 ** safeAttempt),
    max_delay_ms: max,
  };
}