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
7.9 KB
Raw Blame
/**
 * A phase request that cannot be honoured is refused by name
 * (no-dead-ends, Unit E).
 *
 * The five `DREAM_PHASE` labels are a reporting layer, not callable units,
 * and two of the planning steps behind them mutate each other's
 * accumulators specifically so a preference is never both refreshed and
 * retired. Asking for one of those alone must raise a named error that says
 * which steps ARE independently runnable and why the requested one is not -
 * never a partial run, never a full-looking result whose fields are empty
 * because the work did not happen.
 */

import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import {
  existsSync,
  mkdirSync,
  mkdtempSync,
  readFileSync,
  readdirSync,
  rmSync,
  statSync,
  writeFileSync,
} from "node:fs";
import { createHash } from "node:crypto";
import { tmpdir } from "node:os";
import { join, relative } from "node:path";

import { DREAM_PHASE } from "../../../src/core/brain/dream-phases.ts";
import {
  DREAM_STEP,
  DREAM_STEP_RUNNABLE,
  DreamStepNotRunnableError,
  runDreamStep,
} from "../../../src/core/brain/dream-step.ts";
import { brainDirs, dreamRunsDir } from "../../../src/core/brain/paths.ts";
import { writeSignal } from "../../../src/core/brain/signal.ts";
import { bootstrapBrain } from "../../../src/core/brain/init.ts";
import { atomicWriteFileSync } from "../../../src/core/fs-atomic.ts";

let vault: string;
let configHome: string;
let configPath: string;

beforeEach(() => {
  vault = mkdtempSync(join(tmpdir(), "o2b-dream-step-"));
  configHome = mkdtempSync(join(tmpdir(), "o2b-dream-step-cfg-"));
  configPath = join(configHome, "config.yaml");
  atomicWriteFileSync(configPath, `vault: ${vault}\n`);
  bootstrapBrain(vault, { configPath });
});

afterEach(() => {
  rmSync(vault, { recursive: true, force: true });
  rmSync(configHome, { recursive: true, force: true });
});

/** Three same-sign signals: enough that a full pass would promote them. */
function seedPromotion(): void {
  for (const [i, date] of ["2026-05-20", "2026-05-21", "2026-05-22"].entries()) {
    writeSignal(vault, {
      topic: "step-topic",
      signal: "positive",
      agent: "claude",
      principle: "Prefer the stepped approach",
      created_at: `${date}T10:00:00Z`,
      date,
      slug: `step-${i}`,
      scope: "writing",
    });
  }
}

/** Recursive `<relative path>:<sha256>` digest of a tree, sorted. */
function treeDigest(root: string): string {
  const lines: string[] = [];
  const walk = (dir: string): void => {
    for (const name of readdirSync(dir).toSorted()) {
      const full = join(dir, name);
      if (statSync(full).isDirectory()) walk(full);
      else
        lines.push(
          `${relative(root, full)}:${createHash("sha256").update(readFileSync(full)).digest("hex")}`,
        );
    }
  };
  walk(root);
  return lines.join("\n");
}

function makeNotes(): { refPath: string } {
  const notes = join(vault, "Notes");
  mkdirSync(notes, { recursive: true });
  writeFileSync(join(notes, "Acme.md"), "---\ntitle: Acme\n---\nThe Acme page.\n", "utf8");
  const refPath = join(notes, "ref.md");
  writeFileSync(refPath, "---\ntitle: Ref\n---\nwe rely on Acme daily\n", "utf8");
  return { refPath };
}

// ----- The refusal ---------------------------------------------------------

describe("runDreamStep refuses what it cannot honour", () => {
  test("the coupled synthesize label is refused, by name, and writes nothing", () => {
    seedPromotion();
    const before = treeDigest(vault);

    expect(() => runDreamStep(vault, DREAM_PHASE.synthesize)).toThrow(DreamStepNotRunnableError);

    let caught: DreamStepNotRunnableError | undefined;
    try {
      runDreamStep(vault, DREAM_PHASE.synthesize);
    } catch (err) {
      caught = err as DreamStepNotRunnableError;
    }
    expect(caught?.requested).toBe(DREAM_PHASE.synthesize);
    expect(caught?.runnable).toEqual([...DREAM_STEP_RUNNABLE]);
    // Names the coupling itself, not a generic "unsupported phase".
    expect(caught?.message).toContain("planRefresh");
    expect(caught?.message).toContain("planAutoRetires");
    expect(caught?.message).toContain("refresh.updated");
    expect(caught?.message).toContain("plan.retires");
    // And it names the way out.
    for (const step of DREAM_STEP_RUNNABLE) expect(caught?.message).toContain(step);

    expect(treeDigest(vault)).toBe(before);
    expect(existsSync(dreamRunsDir(vault))).toBe(false);
    expect(readdirSync(brainDirs(vault).preferences)).toEqual([]);
  });

  test("the heal label is refused for the same coupling and points at heal-enrich", () => {
    seedPromotion();
    const before = treeDigest(vault);

    let caught: DreamStepNotRunnableError | undefined;
    try {
      runDreamStep(vault, DREAM_PHASE.heal);
    } catch (err) {
      caught = err as DreamStepNotRunnableError;
    }
    expect(caught).toBeInstanceOf(DreamStepNotRunnableError);
    expect(caught?.message).toContain("planAutoRetires");
    expect(caught?.message).toContain(DREAM_STEP.healEnrich);
    expect(treeDigest(vault)).toBe(before);
  });

  test("every remaining phase label is refused with its own specific reason", () => {
    const reasons = new Map<string, string>();
    for (const phase of [DREAM_PHASE.close, DREAM_PHASE.reconcile, DREAM_PHASE.log]) {
      let caught: DreamStepNotRunnableError | undefined;
      try {
        runDreamStep(vault, phase);
      } catch (err) {
        caught = err as DreamStepNotRunnableError;
      }
      expect(caught).toBeInstanceOf(DreamStepNotRunnableError);
      expect(caught?.requested).toBe(phase);
      reasons.set(phase, caught!.reason);
    }
    // No two labels share a reason: each refusal explains that label.
    expect(new Set(reasons.values()).size).toBe(reasons.size);
    expect(reasons.get(DREAM_PHASE.close)).toContain(DREAM_STEP.scan);
  });

  test("an unknown step name is refused rather than silently ignored", () => {
    let caught: DreamStepNotRunnableError | undefined;
    try {
      runDreamStep(vault, "not-a-phase");
    } catch (err) {
      caught = err as DreamStepNotRunnableError;
    }
    expect(caught).toBeInstanceOf(DreamStepNotRunnableError);
    expect(caught?.requested).toBe("not-a-phase");
    expect(caught?.runnable).toEqual([...DREAM_STEP_RUNNABLE]);
  });
});

// ----- The honoured steps --------------------------------------------------

describe("runDreamStep performs exactly the step requested", () => {
  test("scan reports the tree and mutates nothing", () => {
    seedPromotion();
    const before = treeDigest(vault);

    const result = runDreamStep(vault, DREAM_STEP.scan);

    expect(result).toEqual({
      step: DREAM_STEP.scan,
      partial: true,
      active_signals: 3,
      processed_signals: 0,
      archived_signals: 0,
      preferences: 0,
      retired: 0,
      corrupted: [],
    });
    // Nothing that a full pass would have done has happened: no
    // preference, no signal move, no log, no workrun.
    expect(treeDigest(vault)).toBe(before);
    expect(existsSync(dreamRunsDir(vault))).toBe(false);
  });

  test("scan surfaces corrupted entries as paths rather than swallowing them", () => {
    writeFileSync(join(brainDirs(vault).inbox, "sig-broken.md"), "not frontmatter\n", "utf8");

    const result = runDreamStep(vault, DREAM_STEP.scan);

    expect(result.step).toBe(DREAM_STEP.scan);
    expect(result).toMatchObject({ corrupted: ["Brain/inbox/sig-broken.md"] });
  });

  test("heal-enrich enriches user pages and does nothing else", () => {
    const { refPath } = makeNotes();
    seedPromotion();

    const result = runDreamStep(vault, DREAM_STEP.healEnrich);

    expect(result).toMatchObject({ step: DREAM_STEP.healEnrich, partial: true, enriched: 1 });
    expect(readFileSync(refPath, "utf8")).toContain("[[Acme]]");
    // The promotion the full pass would have made did not happen.
    expect(readdirSync(brainDirs(vault).preferences)).toEqual([]);
    expect(readdirSync(brainDirs(vault).inbox).filter((n) => n.endsWith(".md"))).toHaveLength(3);
    expect(existsSync(dreamRunsDir(vault))).toBe(false);
  });
});