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
15.0 KB
Raw Blame
/**
 * `Brain/standing-rules.md` is uneditable by inheritance, and this suite
 * is the assertion rather than the mechanism.
 *
 * The file lives under the Brain machinery root, whose first path
 * segment {@link resolveNoteTarget} refuses outright, and all four
 * caller-named write tools - `brain_create_note`, `brain_update_note`,
 * `brain_append_note`, `brain_write_batch` - resolve their target
 * through that one envelope. Choosing the directory was the entire
 * enforcement decision; what is left to prove is that the four really do
 * share the envelope and that the on-disk bytes survive the attempt.
 *
 * The scope of the claim is stated honestly in `standing-rules.ts`: this
 * is the caller-named write class, which is the boundary the write-site
 * census maintains. It is not a claim that no module in this process can
 * open the file.
 *
 * The last case is the other half of the property: a tool table that
 * NAMED the file - in a tool name, a description, or an input-schema
 * property description - would be advertising a target the envelope then
 * refuses, which is how an agent learns to keep trying.
 */

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

import { JSONRPC_VERSION, MCPServer, PROTOCOL_VERSION } from "../../src/mcp/index.ts";
import { atomicWriteFileSync } from "../../src/core/fs-atomic.ts";
import { buildToolTable } from "../../src/mcp/tools.ts";
import { CreateNoteError, resolveNoteTarget } from "../../src/core/brain/notes/create-note.ts";
import {
  assertStandingRulesNotTargeted,
  StandingRulesWriteRefusedError,
} from "../../src/core/brain/standing-rules.ts";
import {
  BRAIN_SCOPED_RULES_DIR,
  BRAIN_STANDING_RULES_FILE,
} from "../../src/core/brain/path-constants.ts";

let tmp: string;
let vault: string;
let configHome: string;
let configPath: string;
const savedEnv: Record<string, string | undefined> = {};

const RULES_REL = `Brain/${BRAIN_STANDING_RULES_FILE}`;
const RULES_BYTES = "Never force-push to main.\nAsk before deleting anything under Archive/.\n";
const SCOPED_REL = `Brain/${BRAIN_SCOPED_RULES_DIR}/project/x.md`;
const SCOPED_BYTES = "Run the project linter before every commit.\n";

beforeEach(() => {
  tmp = mkdtempSync(join(tmpdir(), "o2b-standing-uneditable-"));
  vault = join(tmp, "vault");
  for (const dir of ["preferences", "retired", "inbox", "log"]) {
    mkdirSync(join(vault, "Brain", dir), { recursive: true });
  }
  writeFileSync(join(vault, "Brain", "_brain.yaml"), "schema_version: 1\n");
  writeFileSync(join(vault, RULES_REL), RULES_BYTES, "utf8");
  mkdirSync(join(vault, "Brain", BRAIN_SCOPED_RULES_DIR, "project"), { recursive: true });
  writeFileSync(join(vault, SCOPED_REL), SCOPED_BYTES, "utf8");
  configHome = mkdtempSync(join(tmpdir(), "o2b-standing-uneditable-cfg-"));
  configPath = join(configHome, "config.yaml");
  for (const k of ["VAULT_AGENT_NAME", "VAULT_TIMEZONE", "VAULT_DIR", "OPEN_SECOND_BRAIN_CONFIG"]) {
    savedEnv[k] = process.env[k];
    delete process.env[k];
  }
  process.env["OPEN_SECOND_BRAIN_CONFIG"] = configPath;
  atomicWriteFileSync(configPath, `vault: ${vault}\nagent_name: claude\n`);
});

afterEach(() => {
  rmSync(tmp, { recursive: true, force: true });
  rmSync(configHome, { recursive: true, force: true });
  for (const [k, v] of Object.entries(savedEnv)) {
    if (v === undefined) delete process.env[k];
    else process.env[k] = v;
  }
});

interface CallOutcome {
  readonly error?: { readonly message?: string };
  readonly result?: { readonly isError?: boolean; readonly content?: ReadonlyArray<unknown> };
}

async function callTool(name: string, args: Record<string, unknown>): Promise<CallOutcome> {
  const server = new MCPServer({ vault, configPath });
  await server.handleRequest({
    jsonrpc: JSONRPC_VERSION,
    id: 1,
    method: "initialize",
    params: {
      protocolVersion: PROTOCOL_VERSION,
      capabilities: {},
      clientInfo: { name: "uneditable-test", version: "0" },
    },
  });
  await server.handleRequest({ jsonrpc: JSONRPC_VERSION, method: "notifications/initialized" });
  return (await server.handleRequest({
    jsonrpc: JSONRPC_VERSION,
    id: 2,
    method: "tools/call",
    params: { name, arguments: args },
  })) as CallOutcome;
}

/** Serialized response text, whichever channel the refusal came back on. */
function outcomeText(out: CallOutcome): string {
  return JSON.stringify(out);
}

function onDiskBytes(): string {
  return readFileSync(join(vault, RULES_REL), "utf8");
}

function scopedOnDiskBytes(): string {
  return readFileSync(join(vault, SCOPED_REL), "utf8");
}

/** The four tools that address a note by a path the caller names. */
const CALLER_NAMED_WRITE_TOOLS: ReadonlyArray<{
  readonly tool: string;
  readonly args: Record<string, unknown>;
}> = Object.freeze([
  { tool: "brain_create_note", args: { path: RULES_REL, content: "OVERWRITTEN" } },
  { tool: "brain_update_note", args: { path: RULES_REL, content: "OVERWRITTEN" } },
  { tool: "brain_append_note", args: { path: RULES_REL, content: "OVERWRITTEN" } },
  {
    tool: "brain_write_batch",
    args: { operations: [{ op: "update_note", path: RULES_REL, content: "OVERWRITTEN" }] },
  },
]);

describe("Brain/standing-rules.md is uneditable through every caller-named write tool", () => {
  for (const { tool, args } of CALLER_NAMED_WRITE_TOOLS) {
    test(`${tool} refuses the path and leaves the bytes unchanged`, async () => {
      const out = await callTool(tool, args);
      const text = outcomeText(out);
      // Refused, however this tool reports refusals, and refused for the
      // REASON that makes the file safe rather than for an incidental one.
      expect(text).not.toContain("OVERWRITTEN");
      expect(text).toContain(RULES_REL);
      expect(text).toContain("Brain machinery root");
      // And the file the operator wrote is byte-for-byte what it was.
      expect(onDiskBytes()).toBe(RULES_BYTES);
    });
  }

  test("the note-target resolver refuses the path with the excluded code", () => {
    let thrown: unknown;
    try {
      resolveNoteTarget(vault, RULES_REL);
    } catch (err) {
      thrown = err;
    }
    expect(thrown).toBeInstanceOf(CreateNoteError);
    expect((thrown as CreateNoteError).code).toBe("excluded");
    expect((thrown as CreateNoteError).message).toContain(RULES_REL);
  });

  test("no tool name, description, or schema property description mentions the file or the scoped directory", () => {
    // The scoped directory is matched with its trailing separator: the
    // bare stem is also the stem of the constitution file name, which the
    // first needle already covers.
    const needles = [BRAIN_STANDING_RULES_FILE, `${BRAIN_SCOPED_RULES_DIR}/`];
    const offenders: string[] = [];
    for (const tool of buildToolTable("full")) {
      const places: Array<[string, string]> = [
        [`${tool.name} (name)`, tool.name],
        [`${tool.name} (description)`, tool.description],
      ];
      for (const [prop, description] of schemaDescriptions(tool.inputSchema)) {
        places.push([`${tool.name}.${prop}`, description]);
      }
      for (const [label, text] of places) {
        for (const needle of needles) {
          if (text.includes(needle)) offenders.push(`${label}: ${needle}`);
        }
      }
    }
    expect(offenders).toEqual([]);
  });
});

/**
 * The lexical `Brain/` check reads the path as spelled. A vault folder
 * that is a symbolic link to `Brain/` spells machinery as an ordinary
 * note path, so the envelope has to re-read where the bytes land.
 */
describe("a vault folder symlinked into Brain/ does not carry a note write there", () => {
  const VIA_LINK = `notes/${BRAIN_STANDING_RULES_FILE}`;
  const LINK_ATTEMPTS: ReadonlyArray<{
    readonly tool: string;
    readonly args: Record<string, unknown>;
  }> = Object.freeze([
    { tool: "brain_create_note", args: { path: "notes/forged.md", content: "OVERWRITTEN" } },
    { tool: "brain_update_note", args: { path: VIA_LINK, content: "OVERWRITTEN" } },
    { tool: "brain_append_note", args: { path: VIA_LINK, content: "OVERWRITTEN" } },
    {
      tool: "brain_write_batch",
      args: {
        operations: [
          { op: "update_note", path: VIA_LINK, content: "OVERWRITTEN" },
          { op: "create_note", path: "notes/forged.md", content: "OVERWRITTEN" },
        ],
      },
    },
  ]);

  beforeEach(() => {
    symlinkSync(join(vault, "Brain"), join(vault, "notes"), "dir");
  });

  for (const { tool, args } of LINK_ATTEMPTS) {
    test(`${tool} refuses and neither the rules nor a new Brain file change`, async () => {
      const out = await callTool(tool, args);
      expect(outcomeText(out)).toContain("Brain machinery root");
      expect(onDiskBytes()).toBe(RULES_BYTES);
      expect(existsSync(join(vault, "Brain", "forged.md"))).toBe(false);
    });
  }

  test("the note-target resolver names where the path lands", () => {
    let thrown: unknown;
    try {
      resolveNoteTarget(vault, VIA_LINK);
    } catch (err) {
      thrown = err;
    }
    expect(thrown).toBeInstanceOf(CreateNoteError);
    expect((thrown as CreateNoteError).code).toBe("excluded");
    expect((thrown as CreateNoteError).message).toContain(RULES_REL);
  });
});

/**
 * The one caller-named write surface that does NOT go through
 * `resolveNoteTarget`: `brain_labels` resolves its path with
 * `resolveNotePath`, which checks containment and symlinks and nothing
 * else, and `assignNoteLabel` then rewrites frontmatter with overwrite -
 * so the inherited refusal did not cover it and an agent could mint the
 * dimension it needed itself. The guard below is named and narrow: it
 * refuses this one path, and it says which file it is protecting.
 */
describe("brain_labels cannot rewrite the standing-rules file", () => {
  const LABEL_ATTEMPTS: ReadonlyArray<Record<string, unknown>> = Object.freeze([
    { operation: "assign", path: RULES_REL, dimension: "status", value: "draft" },
    { operation: "remove", path: RULES_REL, dimension: "status" },
  ]);

  for (const args of LABEL_ATTEMPTS) {
    test(`${String(args["operation"])} is refused and the bytes survive`, async () => {
      const out = await callTool("brain_labels", args);
      // An ERROR, not a result: `remove` used to succeed vacuously on a
      // file with no labels, which reported the path back as if the tool
      // had operated on it. And the message has to NAME the file, so a
      // vocabulary complaint cannot pass for this refusal.
      expect(out.result).toBeUndefined();
      expect(out.error?.message ?? "").toContain(BRAIN_STANDING_RULES_FILE);
      expect(onDiskBytes()).toBe(RULES_BYTES);
    });
  }

  test("the guard refuses the path directly and names the file", () => {
    let thrown: unknown;
    try {
      assertStandingRulesNotTargeted(vault, RULES_REL, "test surface");
    } catch (err) {
      thrown = err;
    }
    expect(thrown).toBeInstanceOf(StandingRulesWriteRefusedError);
    expect((thrown as Error).message).toContain(BRAIN_STANDING_RULES_FILE);
  });

  test("the guard lets every other note through", () => {
    // Narrow by construction: several legitimate callers write into
    // `Brain/` through the same resolver (marker write-back, tombstones,
    // temporal replace), so this guard names the constitution file and
    // the scoped-rules directory beside it, and nothing else.
    for (const other of [
      "Brain/preferences/pref-x.md",
      "Brain/standing-rules-notes.md",
      "Notes/standing-rules/x.md",
    ]) {
      expect(() => assertStandingRulesNotTargeted(vault, other, "test surface")).not.toThrow();
    }
  });
});

/**
 * The scoped operator rules (`Brain/standing-rules/<axis>/<key>.md`) are
 * the constitution's per-project, per-harness and per-host companions and
 * are exactly as uneditable: the four caller-named write tools inherit the
 * `Brain/` refusal, and `brain_labels` - the one surface outside that
 * envelope - is refused by the directory arm of the standing-rules guard.
 */
describe("the scoped standing-rules directory is uneditable", () => {
  const SCOPED_WRITES: ReadonlyArray<{
    readonly tool: string;
    readonly args: Record<string, unknown>;
  }> = Object.freeze([
    { tool: "brain_create_note", args: { path: SCOPED_REL, content: "OVERWRITTEN" } },
    { tool: "brain_update_note", args: { path: SCOPED_REL, content: "OVERWRITTEN" } },
    { tool: "brain_append_note", args: { path: SCOPED_REL, content: "OVERWRITTEN" } },
    {
      tool: "brain_write_batch",
      args: { operations: [{ op: "update_note", path: SCOPED_REL, content: "OVERWRITTEN" }] },
    },
  ]);

  for (const { tool, args } of SCOPED_WRITES) {
    test(`${tool} refuses a scoped rule file and leaves its bytes unchanged`, async () => {
      const text = outcomeText(await callTool(tool, args));
      expect(text).not.toContain("OVERWRITTEN");
      expect(text).toContain(SCOPED_REL);
      expect(text).toContain("Brain machinery root");
      expect(scopedOnDiskBytes()).toBe(SCOPED_BYTES);
    });
  }

  for (const args of [
    { operation: "assign", path: SCOPED_REL, dimension: "status", value: "draft" },
    { operation: "remove", path: SCOPED_REL, dimension: "status" },
  ] as ReadonlyArray<Record<string, unknown>>) {
    test(`brain_labels ${String(args["operation"])} is refused on a scoped rule file`, async () => {
      const out = await callTool("brain_labels", args);
      // Refused by the standing-rules guard, not by an incidental check
      // (an unknown label dimension, a missing frontmatter block): the
      // guard's own wording is what this row pins.
      expect(out.result).toBeUndefined();
      expect(out.error?.message ?? "").toContain("standing-rules file");
      expect(scopedOnDiskBytes()).toBe(SCOPED_BYTES);
    });
  }

  test("the guard refuses a scoped rule path directly", () => {
    let thrown: unknown;
    try {
      assertStandingRulesNotTargeted(vault, SCOPED_REL, "test surface");
    } catch (err) {
      thrown = err;
    }
    expect(thrown).toBeInstanceOf(StandingRulesWriteRefusedError);
  });
});

/**
 * Every `description` string reachable from an input schema, paired with
 * the property path that carries it. Walks nested objects and array
 * items rather than only the top level, because a batch tool hides its
 * per-operation properties one level down.
 */
function schemaDescriptions(schema: unknown, path = ""): Array<[string, string]> {
  if (typeof schema !== "object" || schema === null) return [];
  const out: Array<[string, string]> = [];
  const node = schema as Record<string, unknown>;
  const description = node["description"];
  if (typeof description === "string" && path.length > 0) out.push([path, description]);
  const properties = node["properties"];
  if (typeof properties === "object" && properties !== null) {
    for (const [key, value] of Object.entries(properties)) {
      out.push(...schemaDescriptions(value, path.length > 0 ? `${path}.${key}` : key));
    }
  }
  out.push(...schemaDescriptions(node["items"], path.length > 0 ? `${path}[]` : "[]"));
  return out;
}