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
19.8 KB
Raw Blame
/**
 * Tests for the brain-usage block installer step (plan K2, t_ba41a78a).
 *
 * The installer maps each install target to the agent-instruction file
 * its host reads, plans a pure preview (vault-root path, exists, changed,
 * diff, note), and applies under an approved-preview binding: the apply
 * re-derives the plan from the live disk and refuses to write anything
 * else. Every write routes through the shared rules-block writer, and a
 * successful apply records the ownership lock this module also owns.
 */

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

import {
  auditWritebackContractFile,
  CANONICAL_WRITEBACK_BLOCK_BODY,
} from "../../../src/core/brain/writeback-contract.ts";
import { INSTALL_TARGET_IDS, type InstallTargetId } from "../../../src/core/runtime/host-facts.ts";
import {
  DEFAULT_BEGIN_MARKER,
  DEFAULT_END_MARKER,
} from "../../../src/core/install/managed-block.ts";
import {
  INSTRUCTION_BLOCK_LOCK_FILE,
  applyInstructionBlock,
  clearInstructionBlock,
  instructionBlockLockPath,
  instructionBlockTargetFor,
  planInstructionBlock,
  readInstructionBlockLock,
  recordInstructionBlock,
} from "../../../src/core/install/instruction-block.ts";
import { HOST_INSTRUCTION_PRECEDENCE } from "../../../src/core/brain/writeback-contract.ts";
import {
  RULES_BLOCK_ERROR_KIND,
  RULES_BLOCK_ID,
  RULES_BLOCK_MARKERS,
  RulesBlockError,
  writeRulesBlock,
} from "../../../src/core/install/rules-block.ts";
import type { InstallEnv } from "../../../src/core/install/types.ts";

let tmp: string;

beforeEach(() => {
  tmp = mkdtempSync(join(tmpdir(), "osb-instruction-block-"));
  // A legacy vault: it keeps its machine state. A vault with no `Brain/`
  // is store-only and keeps that state device-local instead.
  mkdirSync(join(tmp, "Brain"), { recursive: true });
});

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

const APPLIED_AT_MS = 1_700_000_000_000;

function envFor(vault: string): InstallEnv {
  return {
    vault,
    home: tmp,
    cwd: tmp,
    env: {},
    now: new Date(APPLIED_AT_MS),
  };
}

const OPERATOR = "# project notes\n\nHand-written content.\n";

/** The non-conforming body a manual install from the older docs pasted. */
const DOCS_SNIPPET_BODY = [
  "## Open Second Brain",
  "",
  "This project shares an Obsidian-compatible vault with an active",
  "observing-memory layer. At session start, read Brain/active.md.",
].join("\n");

const DOCS_SNIPPET_FILE = [
  OPERATOR,
  DEFAULT_BEGIN_MARKER,
  DOCS_SNIPPET_BODY,
  DEFAULT_END_MARKER,
  "",
].join("\n");

/** Backup siblings of `AGENTS.md` currently in the directory. */
function backupsOf(name: string): string[] {
  return readdirSync(tmp)
    .filter((entry) => entry.startsWith(`${name}.bak.`))
    .toSorted();
}

describe("instructionBlockTargetFor", () => {
  test("maps codex, cursor, opencode and aider to AGENTS.md", () => {
    expect(instructionBlockTargetFor("codex")).toBe("AGENTS.md");
    expect(instructionBlockTargetFor("cursor")).toBe("AGENTS.md");
    expect(instructionBlockTargetFor("opencode")).toBe("AGENTS.md");
    expect(instructionBlockTargetFor("aider")).toBe("AGENTS.md");
  });

  test("maps gemini-cli to GEMINI.md", () => {
    expect(instructionBlockTargetFor("gemini-cli")).toBe("GEMINI.md");
  });

  test("returns null, as a named skip, for targets with no precedence entry", () => {
    for (const target of ["copilot-cli", "grok", "kiro", "pi", "generic"] as const) {
      expect(instructionBlockTargetFor(target)).toBeNull();
    }
  });

  test("follows HOST_INSTRUCTION_PRECEDENCE if the table or targets ever grow", () => {
    const table = HOST_INSTRUCTION_PRECEDENCE as Readonly<Record<string, readonly string[]>>;
    for (const target of INSTALL_TARGET_IDS as ReadonlyArray<InstallTargetId>) {
      expect(instructionBlockTargetFor(target)).toBe(table[target]?.[0] ?? null);
    }
  });
});

describe("planInstructionBlock", () => {
  test("plans a vault-root path for an absent file, with a creation note", () => {
    const env = envFor(tmp);
    const plan = planInstructionBlock(env, "codex");
    expect(plan.path).toBe(join(tmp, "AGENTS.md"));
    expect(plan.exists).toBe(false);
    expect(plan.changed).toBe(true);
    expect(plan.diff).not.toBe("");
    expect(plan.note).not.toBeNull();
    expect(plan.note).toContain("AGENTS.md");
  });

  test("plans an insert into an operator-authored file and renders the diff", () => {
    writeFileSync(join(tmp, "AGENTS.md"), OPERATOR);
    const plan = planInstructionBlock(envFor(tmp), "codex");
    expect(plan.exists).toBe(true);
    expect(plan.changed).toBe(true);
    expect(plan.diff).toContain(`--- ${join(tmp, "AGENTS.md")}`);
    expect(plan.diff).toContain(DEFAULT_BEGIN_MARKER);
    expect(readFileSync(join(tmp, "AGENTS.md"), "utf8")).toBe(OPERATOR);
  });

  test("a current block plans no change and no diff", () => {
    writeRulesBlock(join(tmp, "AGENTS.md"), RULES_BLOCK_ID.usage, CANONICAL_WRITEBACK_BLOCK_BODY);
    const plan = planInstructionBlock(envFor(tmp), "codex");
    expect(plan.exists).toBe(true);
    expect(plan.changed).toBe(false);
    expect(plan.diff).toBe("");
  });

  test("a drifted block plans a replacement diff", () => {
    writeFileSync(join(tmp, "AGENTS.md"), DOCS_SNIPPET_FILE);
    const plan = planInstructionBlock(envFor(tmp), "codex");
    expect(plan.exists).toBe(true);
    expect(plan.changed).toBe(true);
    expect(plan.diff).toContain(
      "- observing-memory layer. At session start, read Brain/active.md.",
    );
    expect(plan.diff).toContain("+ Memory write gate: apply the marker_writeback guardrail.");
  });

  test("the gemini-cli file carries the name-implied-reading note", () => {
    const plan = planInstructionBlock(envFor(tmp), "gemini-cli");
    expect(plan.path).toBe(join(tmp, "GEMINI.md"));
    expect(plan.note).toContain("name-implied");
  });

  test("plans read, never write: a drift-only call leaves the vault untouched", () => {
    writeFileSync(join(tmp, "AGENTS.md"), OPERATOR);
    planInstructionBlock(envFor(tmp), "codex");
    expect(readFileSync(join(tmp, "AGENTS.md"), "utf8")).toBe(OPERATOR);
    expect(backupsOf("AGENTS.md").length).toBe(0);
    expect(existsSync(instructionBlockLockPath(tmp))).toBe(false);
  });

  test("refuses a symbolic link, by name, with the checker's posture", () => {
    const real = join(tmp, "real-agents.md");
    writeFileSync(real, OPERATOR);
    symlinkSync(real, join(tmp, "AGENTS.md"));
    expect(() => planInstructionBlock(envFor(tmp), "codex")).toThrow(RulesBlockError);
  });

  test("refuses malformed markers of the block's own spelling, by name", () => {
    writeFileSync(
      join(tmp, "AGENTS.md"),
      `${DEFAULT_BEGIN_MARKER}\nbroken\n${DEFAULT_BEGIN_MARKER}\n`,
    );
    let thrown: unknown = null;
    try {
      planInstructionBlock(envFor(tmp), "codex");
    } catch (err) {
      thrown = err;
    }
    expect(thrown).toBeInstanceOf(RulesBlockError);
    expect((thrown as Error & { kind?: string }).kind).toBe(RULES_BLOCK_ERROR_KIND.markers);
  });
});

describe("applyInstructionBlock", () => {
  test("writes the approved plan, backs up, records the lock, and the audit conforms", () => {
    writeFileSync(join(tmp, "AGENTS.md"), OPERATOR);
    const env = envFor(tmp);
    const approved = planInstructionBlock(env, "codex");
    const result = applyInstructionBlock(env, { approved });
    expect(result.backupPath).not.toBeNull();
    expect(backupsOf("AGENTS.md").length).toBe(1);
    expect(readFileSync(result.backupPath as string, "utf8")).toBe(OPERATOR);
    const audit = auditWritebackContractFile(join(tmp, "AGENTS.md"));
    expect(audit.finding).toBe("conforming");
    const lock = readInstructionBlockLock(tmp);
    expect(lock.schema_version).toBe(1);
    const entry = lock.files["AGENTS.md"];
    expect(entry).toBeDefined();
    expect(entry?.block_id).toBe(RULES_BLOCK_ID.usage);
    expect(entry?.begin_marker).toBe(RULES_BLOCK_MARKERS.usage.begin);
    // The lock stamps when the write landed: the mtime the gate itself
    // compares against, not the run-start clock in env.now.
    expect(Date.parse(entry?.applied_at ?? "")).toBe(
      Math.trunc(statSync(join(tmp, "AGENTS.md")).mtimeMs),
    );
  });

  test("the lock stamps when the write landed, not the run-start clock", () => {
    // env.now predates the plan render, the consent prompt and the
    // adapter apply - on an interactive install by more than the writer's
    // MTIME_SLACK_MS. A run-start stamp then sits behind the written
    // file's mtime, so the next canonical-body upgrade read our own
    // write as a later hand edit and refused with user-modified-block
    // instead of taking the documented rewrite path. The lock records
    // the written file's mtime, the exact anchor the hand-edit gate
    // compares against.
    writeFileSync(join(tmp, "AGENTS.md"), OPERATOR);
    const env = envFor(tmp);
    applyInstructionBlock(env, { approved: planInstructionBlock(env, "codex") });
    const stamped = Date.parse(readInstructionBlockLock(tmp).files["AGENTS.md"]?.applied_at ?? "");
    expect(stamped).toBe(Math.trunc(statSync(join(tmp, "AGENTS.md")).mtimeMs));
    expect(stamped).not.toBe(APPLIED_AT_MS);
  });

  test("a re-plan and re-apply converge: changed false, no new backup", () => {
    writeFileSync(join(tmp, "AGENTS.md"), OPERATOR);
    const env = envFor(tmp);
    applyInstructionBlock(env, { approved: planInstructionBlock(env, "codex") });
    const once = readFileSync(join(tmp, "AGENTS.md"), "utf8");
    const second = applyInstructionBlock(env, { approved: planInstructionBlock(env, "codex") });
    expect(second.backupPath).toBeNull();
    expect(readFileSync(join(tmp, "AGENTS.md"), "utf8")).toBe(once);
    expect(backupsOf("AGENTS.md").length).toBe(1);
  });

  test("refuses preview drift by name and writes nothing", () => {
    writeFileSync(join(tmp, "AGENTS.md"), OPERATOR);
    const env = envFor(tmp);
    const approved = planInstructionBlock(env, "codex");
    // The operator edits between consent and apply.
    writeFileSync(join(tmp, "AGENTS.md"), `${OPERATOR}\nMore notes.\n`);
    let thrown: unknown = null;
    try {
      applyInstructionBlock(env, { approved });
    } catch (err) {
      thrown = err;
    }
    expect(thrown).toBeInstanceOf(RulesBlockError);
    const err = thrown as Error & { kind?: string };
    expect(err.kind).toBe(RULES_BLOCK_ERROR_KIND.previewDrift);
    expect(readFileSync(join(tmp, "AGENTS.md"), "utf8")).toBe(`${OPERATOR}\nMore notes.\n`);
    expect(backupsOf("AGENTS.md").length).toBe(0);
    expect(existsSync(instructionBlockLockPath(tmp))).toBe(false);
  });

  test("refuses a docs-snippet block without force, then upgrades it with force to conforming", () => {
    writeFileSync(join(tmp, "AGENTS.md"), DOCS_SNIPPET_FILE);
    const env = envFor(tmp);
    const approved = planInstructionBlock(env, "codex");
    // No lock record exists, so the diverged block cannot be proven ours:
    // the refusal is fail-closed by name.
    let thrown: unknown = null;
    try {
      applyInstructionBlock(env, { approved });
    } catch (err) {
      thrown = err;
    }
    expect(thrown).toBeInstanceOf(RulesBlockError);
    expect((thrown as Error & { kind?: string }).kind).toBe(
      RULES_BLOCK_ERROR_KIND.userModifiedBlock,
    );
    expect(readFileSync(join(tmp, "AGENTS.md"), "utf8")).toBe(DOCS_SNIPPET_FILE);
    // The documented override: force rewrites, the backup holds the prior
    // bytes, and the real auditor now grades the file conforming.
    const result = applyInstructionBlock(env, { approved, force: true });
    expect(result.backupPath).not.toBeNull();
    expect(readFileSync(result.backupPath as string, "utf8")).toBe(DOCS_SNIPPET_FILE);
    expect(auditWritebackContractFile(join(tmp, "AGENTS.md")).finding).toBe("conforming");
    expect(readInstructionBlockLock(tmp).files["AGENTS.md"]).toBeDefined();
  });

  test("an installedAtMs from the lock excuses a divergence on a stale file", () => {
    writeFileSync(join(tmp, "AGENTS.md"), OPERATOR);
    const env = envFor(tmp);
    applyInstructionBlock(env, { approved: planInstructionBlock(env, "codex") });
    // The canonical body changed in a newer release; the file mtime is
    // still at the recorded install time, so the rewrite is ours to make.
    const second = planInstructionBlock(envFor(tmp), "codex");
    expect(second.changed).toBe(false);
  });

  test("dryRun writes nothing: no file change, no backup, no lock", () => {
    writeFileSync(join(tmp, "AGENTS.md"), OPERATOR);
    const env = envFor(tmp);
    const approved = planInstructionBlock(env, "codex");
    const result = applyInstructionBlock(env, { approved, dryRun: true });
    expect(result.backupPath).toBeNull();
    expect(readFileSync(join(tmp, "AGENTS.md"), "utf8")).toBe(OPERATOR);
    expect(backupsOf("AGENTS.md").length).toBe(0);
    expect(existsSync(instructionBlockLockPath(tmp))).toBe(false);
  });

  test("refuses an approved plan that does not name a vault-root agent instruction file", () => {
    const env = envFor(tmp);
    const approved = planInstructionBlock(env, "codex");
    const forged = { ...approved, path: join(tmp, "elsewhere", "AGENTS.md") };
    let thrown: unknown = null;
    try {
      applyInstructionBlock(env, { approved: forged });
    } catch (err) {
      thrown = err;
    }
    expect(thrown).toBeInstanceOf(RulesBlockError);
    expect((thrown as Error & { kind?: string }).kind).toBe(RULES_BLOCK_ERROR_KIND.invalidPlan);
  });

  test("an unchanged approved apply records ownership, so uninstall can find the block", () => {
    writeRulesBlock(join(tmp, "AGENTS.md"), RULES_BLOCK_ID.usage, CANONICAL_WRITEBACK_BLOCK_BODY);
    const env = envFor(tmp);
    const approved = planInstructionBlock(env, "codex");
    expect(approved.changed).toBe(false);
    applyInstructionBlock(env, { approved });
    expect(readInstructionBlockLock(tmp).files["AGENTS.md"]).toBeDefined();
  });

  test("the apply result names what happened: created, updated, or already current", () => {
    const env = envFor(tmp);
    // First apply on a vault with no AGENTS.md: the file is CREATED. The
    // result must say so - a backupPath-only derivation would report the
    // creation as "already carries the block".
    const created = applyInstructionBlock(env, { approved: planInstructionBlock(env, "codex") });
    expect(created.created).toBe(true);
    expect(created.changed).toBe(true);
    expect(created.backupPath).toBeNull();
    // A re-apply is already current on both fields.
    const current = applyInstructionBlock(env, { approved: planInstructionBlock(env, "codex") });
    expect(current.created).toBe(false);
    expect(current.changed).toBe(false);
    // A diverged block rewritten under force is an UPDATE of an existing
    // file, not a creation.
    writeFileSync(join(tmp, "AGENTS.md"), DOCS_SNIPPET_FILE);
    const updated = applyInstructionBlock(env, {
      approved: planInstructionBlock(env, "codex"),
      force: true,
    });
    expect(updated.created).toBe(false);
    expect(updated.changed).toBe(true);
    expect(updated.backupPath).not.toBeNull();
  });

  test("a future-stamped applied_at is untrusted: a diverged block refuses without force", () => {
    // The lock lives in agent-writable state; an applied_at stamped into
    // the future would make every operator hand-edit read as a canonical
    // move under an untouched file. The gate must treat it as no record.
    writeFileSync(join(tmp, "AGENTS.md"), DOCS_SNIPPET_FILE);
    recordInstructionBlock(tmp, "AGENTS.md", {
      block_id: RULES_BLOCK_ID.usage,
      begin_marker: RULES_BLOCK_MARKERS.usage.begin,
      applied_at: new Date(Date.now() + 10 * 60_000).toISOString(),
    });
    const env = envFor(tmp);
    const approved = planInstructionBlock(env, "codex");
    let thrown: unknown = null;
    try {
      applyInstructionBlock(env, { approved });
    } catch (err) {
      thrown = err;
    }
    expect(thrown).toBeInstanceOf(RulesBlockError);
    const err = thrown as Error & { kind?: string };
    expect(err.kind).toBe(RULES_BLOCK_ERROR_KIND.userModifiedBlock);
    expect(err.message).toContain("future");
    expect(readFileSync(join(tmp, "AGENTS.md"), "utf8")).toBe(DOCS_SNIPPET_FILE);
    // --force stays the documented override.
    const forced = applyInstructionBlock(env, { approved, force: true });
    expect(forced.changed).toBe(true);
    expect(auditWritebackContractFile(join(tmp, "AGENTS.md")).finding).toBe("conforming");
  });
});

describe("instruction-block lock I/O", () => {
  test("the lock file name and path are the derived-store join", () => {
    expect(INSTRUCTION_BLOCK_LOCK_FILE).toBe("instruction-block.lock.json");
    expect(instructionBlockLockPath(tmp)).toBe(
      join(tmp, ".open-second-brain", "instruction-block.lock.json"),
    );
    expect(basename(instructionBlockLockPath(tmp))).toBe("instruction-block.lock.json");
  });

  test("an absent lock reads as an empty schema-1 document", () => {
    const lock = readInstructionBlockLock(tmp);
    expect(lock.schema_version).toBe(1);
    expect(Object.keys(lock.files).length).toBe(0);
  });

  test("record and clear round-trip atomically", () => {
    recordInstructionBlock(tmp, "AGENTS.md", {
      block_id: RULES_BLOCK_ID.usage,
      begin_marker: RULES_BLOCK_MARKERS.usage.begin,
      applied_at: new Date(APPLIED_AT_MS).toISOString(),
    });
    recordInstructionBlock(tmp, "GEMINI.md", {
      block_id: RULES_BLOCK_ID.usage,
      begin_marker: RULES_BLOCK_MARKERS.usage.begin,
      applied_at: new Date(APPLIED_AT_MS).toISOString(),
    });
    expect(Object.keys(readInstructionBlockLock(tmp).files).toSorted()).toEqual([
      "AGENTS.md",
      "GEMINI.md",
    ]);
    // Re-recording one file replaces its entry, not the others.
    recordInstructionBlock(tmp, "AGENTS.md", {
      block_id: RULES_BLOCK_ID.usage,
      begin_marker: RULES_BLOCK_MARKERS.usage.begin,
      applied_at: new Date(APPLIED_AT_MS + 1).toISOString(),
    });
    expect(readInstructionBlockLock(tmp).files["AGENTS.md"]?.applied_at).toBe(
      new Date(APPLIED_AT_MS + 1).toISOString(),
    );
    expect(readInstructionBlockLock(tmp).files["GEMINI.md"]).toBeDefined();
    clearInstructionBlock(tmp, "AGENTS.md");
    expect(readInstructionBlockLock(tmp).files["AGENTS.md"]).toBeUndefined();
    clearInstructionBlock(tmp, "CLAUDE.md");
    expect(Object.keys(readInstructionBlockLock(tmp).files)).toEqual(["GEMINI.md"]);
  });

  test("corrupted JSON refuses with a named error carrying the path", () => {
    mkdirSync(join(tmp, ".open-second-brain"), { recursive: true });
    writeFileSync(instructionBlockLockPath(tmp), "{ not json");
    expect(() => readInstructionBlockLock(tmp)).toThrow(/instruction-block\.lock\.json/);
  });

  test("a non-object document refuses with a named error", () => {
    mkdirSync(join(tmp, ".open-second-brain"), { recursive: true });
    writeFileSync(instructionBlockLockPath(tmp), "[1, 2]\n");
    expect(() => readInstructionBlockLock(tmp)).toThrow(/not an object/);
  });

  test("an unsupported schema_version refuses with a named error", () => {
    mkdirSync(join(tmp, ".open-second-brain"), { recursive: true });
    writeFileSync(
      instructionBlockLockPath(tmp),
      JSON.stringify({ schema_version: 99, files: {} }) + "\n",
    );
    expect(() => readInstructionBlockLock(tmp)).toThrow(/schema_version 99/);
  });

  test("the lock is never a symlink target: reads refuse links with the writer's posture", () => {
    // A lock that can be redirected reads state the vault never wrote.
    mkdirSync(join(tmp, ".open-second-brain"), { recursive: true });
    const real = join(tmp, "real-lock.json");
    writeFileSync(real, JSON.stringify({ schema_version: 1, files: {} }));
    symlinkSync(real, instructionBlockLockPath(tmp));
    expect(() => readInstructionBlockLock(tmp)).toThrow(RulesBlockError);
  });
});