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
14.3 KB
Raw Blame
/**
 * Operator summary composer (v0.10.16).
 *
 * One read-only call that aggregates the three independent brain
 * surfaces - doctor, dream, vault metadata - into a unified envelope:
 *
 *   - `trust_verdict`            - `clean | watch | investigate`
 *   - `digest_summary`           - preference status counts
 *   - `doctor_summary`           - warning / error counts
 *   - `dream_summary`            - warning / uncertain / quarantined counts
 *   - `verification_delta`       - confirmed / drift / regression / missing
 *   - `top_actions`              - ranked maintenance action list
 *   - `instruction_file_warnings`- ceiling breaches at vault root
 *
 * The composer never mutates the vault. It accepts a precomputed
 * dream summary so callers can choose between "run dream first" and
 * "skip dream entirely"; verification delta falls back to all-zero
 * counts when no dream is supplied.
 */

import { existsSync, readdirSync, statSync } from "node:fs";
import { join, relative } from "node:path";

import { toPosix } from "../../path-safety.ts";
import { memoryFromStore, storePagesIn } from "../memory-pages.ts";

import { runDoctor, type RunDoctorResult } from "../doctor.ts";
import type { DreamRunSummary } from "../dream.ts";
import {
  closedCollectError,
  collectMaintenanceActions,
  type MaintenanceCollectSignal,
} from "../maintenance/collect.ts";
import type { ActionItem } from "../maintenance/action-scorer.ts";
import type { DoctorIssueNaming } from "../diagnostics.ts";
import { brainDirs } from "../paths.ts";
import { BRAIN_GUARDRAIL_DEFAULTS } from "../policy.ts";
import type {
  DoctorIssue,
  InstructionFileCeilingWarning,
  ResolvedBrainGuardrailConfig,
  TrustVerdict,
} from "../types.ts";
import {
  computeVerificationDelta,
  type VerificationDeltaEntry,
  type VerificationDeltaResult,
} from "./compute-verification-delta.ts";
import { computeTrustVerdict } from "./compute-trust-verdict.ts";
import { checkInstructionFileCeiling } from "./instruction-file-ceiling.ts";

export interface OperatorSummary {
  readonly trust_verdict: TrustVerdict;
  readonly digest_summary: DigestSummary;
  readonly doctor_summary: DoctorSummary;
  readonly dream_summary: DreamSummary;
  readonly verification_delta: VerificationDeltaResult;
  readonly top_actions: ReadonlyArray<ActionItem>;
  readonly instruction_file_warnings: ReadonlyArray<InstructionFileCeilingWarning>;
  /**
   * The maintenance scans that refused while the actions were collected
   * (review M10), rendered as `{scan, message}` rows - the same shape the
   * digest and doctor rows carry. A thin `top_actions` list must be
   * readable as healthy rather than indistinguishable from a scan that
   * failed. Present only when at least one scan refused.
   */
  readonly collect_errors?: ReadonlyArray<{
    readonly scan: MaintenanceCollectSignal;
    readonly message: string;
  }>;
}

export interface DigestSummary {
  readonly preference_count: number;
  readonly retired_count: number;
  readonly inbox_count: number;
}

export interface DoctorSummary {
  readonly warning_count: number;
  readonly error_count: number;
  readonly warnings: ReadonlyArray<DoctorIssue>;
  readonly errors: ReadonlyArray<DoctorIssue>;
}

export interface DreamSummary {
  readonly warning_count: number;
  readonly uncertain_count: number;
  readonly quarantined_count: number;
}

export interface BuildOperatorSummaryOptions {
  /**
   * Recent dream-pass summary. Verification delta is computed
   * against this; when omitted, all verification counts default to
   * zero.
   */
  readonly dreamSummary?: DreamRunSummary;
  /**
   * Resolved guardrail config. Drives the instruction-file ceiling
   * check. Defaults to `BRAIN_GUARDRAIL_DEFAULTS`.
   */
  readonly guardrails?: ResolvedBrainGuardrailConfig;
  /** Top-N cap on the maintenance action list. */
  readonly topActionsN?: number;
  /**
   * Whether the caller may see a doctor finding. The doctor counts and
   * the trust verdict are taken over the findings it keeps. Omitted,
   * every finding counts (the operator's own shell).
   */
  readonly keepIssue?: (issue: DoctorIssueNaming) => boolean;
  /**
   * Whether the caller may read a vault-relative path. The digest counts
   * only the records it may read, and the doctor pass counts its capped
   * and pre-filter totals over them. Omitted, every record counts.
   */
  readonly readable?: (rel: string) => boolean;
  /**
   * Whether the caller may see a maintenance action. Applied before the
   * top-N slice, so a withheld action takes no slot. Omitted, every
   * action is ranked.
   */
  readonly keepAction?: (action: ActionItem) => boolean;
  /**
   * Whether the caller may see an artifact reference - a page id, a
   * vault-relative path, or a wikilink-spelled one. Threaded into the
   * maintenance collector so it applies to the candidate inputs BEFORE
   * the scorer caps: a hidden top-ranked action takes no slot a visible
   * one could fill, and a dedup count excludes hidden secondaries.
   * Omitted, every candidate is ranked. `keepAction` stays as the
   * per-row filter beside it.
   */
  readonly visibleRef?: (ref: string | null | undefined) => boolean;
  /**
   * Whether the caller may see a verification-delta entry. The entries
   * and their summary counts - and the trust verdict over them - are
   * taken over the entries it keeps. Omitted, every entry counts.
   */
  readonly keepVerification?: (entry: VerificationDeltaEntry) => boolean;
  /**
   * The caller is below local reach: the maintenance actions and the
   * doctor pass leave out the log events of the store's `private`
   * partition (the token footprint's log bucket, the broken-backlink
   * check). Default false.
   */
  readonly withholdsPrivate?: boolean;
}

const DEFAULT_TOP_ACTIONS_N = 5;

export function buildOperatorSummary(
  vault: string,
  opts: BuildOperatorSummaryOptions,
): OperatorSummary {
  const guardrails = opts.guardrails ?? BRAIN_GUARDRAIL_DEFAULTS;
  const dreamSummary = opts.dreamSummary;

  const doctorResult = keptDoctorResult(
    safeDoctor(vault, guardrails, dreamSummary, opts.readable, opts.withholdsPrivate === true),
    opts.keepIssue,
  );
  const dreamCounts = summariseDream(dreamSummary);
  const digestCounts = collectDigestCounts(vault, opts.readable);
  const verification = dreamSummary
    ? keptVerification(computeVerificationDelta(vault, dreamSummary), opts.keepVerification)
    : zeroVerification();
  const instructionWarnings = checkInstructionFileCeiling(vault, {
    maxLines: guardrails.instruction_file_max_lines,
    ...(opts.readable !== undefined ? { readable: opts.readable } : {}),
  });
  const collectErrors: { scan: MaintenanceCollectSignal; message: string }[] = [];
  const topActions = safeTopActions(
    vault,
    opts.topActionsN ?? DEFAULT_TOP_ACTIONS_N,
    opts.keepAction,
    collectErrors,
    opts.readable !== undefined,
    opts.visibleRef,
    opts.withholdsPrivate === true,
  );

  const trust = computeTrustVerdict({
    doctorWarnings: doctorResult.warnings,
    doctorErrors: doctorResult.errors,
    dreamWarnings: dreamSummary?.warnings ?? [],
    verification: verification.summary,
  });

  return Object.freeze({
    trust_verdict: trust,
    digest_summary: digestCounts,
    doctor_summary: Object.freeze({
      warning_count: doctorResult.warnings.length,
      error_count: doctorResult.errors.length,
      warnings: doctorResult.warnings,
      errors: doctorResult.errors,
    }),
    dream_summary: dreamCounts,
    verification_delta: verification,
    top_actions: topActions,
    instruction_file_warnings: instructionWarnings,
    ...(collectErrors.length > 0 ? { collect_errors: Object.freeze(collectErrors) } : {}),
  });
}

/**
 * Markdown rendering of the operator summary. Sections mirror the
 * JSON envelope; no headings for sections that are entirely empty.
 */
export function renderOperatorSummaryMarkdown(summary: OperatorSummary): string {
  const out: string[] = [];
  out.push("# Operator summary");
  out.push("");
  out.push(`Trust: **${summary.trust_verdict}**`);
  out.push("");
  out.push(
    `Doctor: ${summary.doctor_summary.warning_count} warning(s), ${summary.doctor_summary.error_count} error(s)`,
  );
  out.push(
    `Dream: ${summary.dream_summary.warning_count} warning(s), ${summary.dream_summary.uncertain_count} uncertain, ${summary.dream_summary.quarantined_count} quarantined`,
  );
  out.push(
    `Verification: ${summary.verification_delta.summary.confirmed} confirmed, ${summary.verification_delta.summary.drift} drift, ${summary.verification_delta.summary.regression} regression, ${summary.verification_delta.summary.missing_evidence} missing_evidence`,
  );
  out.push("");
  out.push(
    `Vault: ${summary.digest_summary.preference_count} preferences, ${summary.digest_summary.retired_count} retired, ${summary.digest_summary.inbox_count} inbox`,
  );

  if (summary.instruction_file_warnings.length > 0) {
    out.push("");
    out.push("## Instruction file warnings");
    out.push("");
    for (const w of summary.instruction_file_warnings) {
      out.push(`- \`${w.path}\` - ${w.lines} lines (ceiling ${w.ceiling})`);
    }
  }

  if (summary.top_actions.length > 0) {
    out.push("");
    out.push("## Top actions");
    out.push("");
    for (const a of summary.top_actions) {
      out.push(`- ${a.category}: ${a.title}`);
    }
  }

  if (summary.collect_errors !== undefined && summary.collect_errors.length > 0) {
    out.push("");
    out.push("## Collection errors");
    out.push("");
    for (const e of summary.collect_errors) {
      out.push(`- ${e.scan}: ${e.message}`);
    }
  }

  out.push("");
  return out.join("\n");
}

// ----- Internals -----------------------------------------------------------

function safeDoctor(
  vault: string,
  guardrails: ResolvedBrainGuardrailConfig,
  dreamSummary: DreamRunSummary | undefined,
  readable: BuildOperatorSummaryOptions["readable"],
  withholdsPrivate: boolean,
): RunDoctorResult {
  try {
    return runDoctor(vault, {
      guardrails,
      ...(dreamSummary ? { dreamSummary } : {}),
      ...(readable !== undefined ? { readable } : {}),
      ...(withholdsPrivate ? { withholdsPrivate: true } : {}),
    });
  } catch {
    return Object.freeze({ warnings: [], errors: [] });
  }
}

/** The doctor's warnings and errors the caller may see. */
function keptDoctorResult(
  result: RunDoctorResult,
  keepIssue: BuildOperatorSummaryOptions["keepIssue"],
): RunDoctorResult {
  if (keepIssue === undefined) return result;
  return Object.freeze({
    ...result,
    warnings: Object.freeze(result.warnings.filter(keepIssue)),
    errors: Object.freeze(result.errors.filter(keepIssue)),
  });
}

/** The verification entries the caller may see, with the counts taken over them. */
function keptVerification(
  result: VerificationDeltaResult,
  keep: BuildOperatorSummaryOptions["keepVerification"],
): VerificationDeltaResult {
  if (keep === undefined) return result;
  const entries = result.entries.filter(keep);
  const count = (state: VerificationDeltaEntry["state"]): number =>
    entries.filter((entry) => entry.state === state).length;
  return Object.freeze({
    entries: Object.freeze(entries),
    summary: Object.freeze({
      confirmed: count("confirmed"),
      drift: count("drift"),
      regression: count("regression"),
      missing_evidence: count("missing_evidence"),
    }),
  });
}

function summariseDream(dream: DreamRunSummary | undefined): DreamSummary {
  if (dream === undefined) {
    return Object.freeze({
      warning_count: 0,
      uncertain_count: 0,
      quarantined_count: 0,
    });
  }
  return Object.freeze({
    warning_count: dream.warnings.length,
    uncertain_count: dream.uncertain.length,
    quarantined_count: dream.quarantined.length,
  });
}

function collectDigestCounts(
  vault: string,
  readable: BuildOperatorSummaryOptions["readable"],
): DigestSummary {
  const dirs = brainDirs(vault);
  return Object.freeze({
    preference_count: countMarkdownFiles(vault, dirs.preferences, readable),
    retired_count: countMarkdownFiles(vault, dirs.retired, readable),
    inbox_count: countMarkdownFiles(vault, dirs.inbox, readable),
  });
}

function countMarkdownFiles(
  vault: string,
  dir: string,
  readable: BuildOperatorSummaryOptions["readable"],
): number {
  if (memoryFromStore(vault)) {
    // Store-only (task 2.10): the fold's records whose page sat in `dir`.
    // Best effort like the folder count below: a fold that cannot be built
    // counts 0 rather than failing the whole summary.
    try {
      return storePagesIn(vault, dir).filter((p) => readable === undefined || readable(p.rel))
        .length;
    } catch {
      return 0;
    }
  }
  if (!existsSync(dir)) return 0;
  try {
    let n = 0;
    for (const name of readdirSync(dir)) {
      if (!name.endsWith(".md")) continue;
      if (readable !== undefined && !readable(toPosix(relative(vault, join(dir, name))))) {
        continue;
      }
      try {
        const s = statSync(join(dir, name));
        if (s.isFile()) n += 1;
      } catch {
        // Race: skip
      }
    }
    return n;
  } catch {
    return 0;
  }
}

function safeTopActions(
  vault: string,
  topN: number,
  keepAction: BuildOperatorSummaryOptions["keepAction"],
  collectErrors: { scan: MaintenanceCollectSignal; message: string }[],
  restricted: boolean,
  visibleRef?: BuildOperatorSummaryOptions["visibleRef"],
  withholdsPrivate = false,
): ReadonlyArray<ActionItem> {
  try {
    const all = collectMaintenanceActions(vault, {
      // Below local reach the raised message (which can carry a host
      // path) is replaced by the closed scan-and-code form.
      onError: (e) => {
        const shown = restricted ? closedCollectError(e) : e;
        collectErrors.push({ scan: shown.signal, message: shown.message });
      },
      // Candidate-level visibility, before the scorer caps: the same
      // predicate brain_doctor's suggested_actions and the digest's
      // actions ask, so the sinks cannot disagree about what a scoped
      // caller is shown.
      ...(visibleRef !== undefined ? { visible: visibleRef } : {}),
      withholdsPrivate,
    });
    const kept = keepAction === undefined ? all : all.filter(keepAction);
    return Object.freeze(kept.slice(0, Math.max(0, topN)));
  } catch {
    return Object.freeze([]);
  }
}

function zeroVerification(): VerificationDeltaResult {
  return Object.freeze({
    entries: Object.freeze([]),
    summary: Object.freeze({
      confirmed: 0,
      drift: 0,
      regression: 0,
      missing_evidence: 0,
    }),
  });
}