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
/**
 * MCP integration tests for `brain_intake_entities` (model-based NER intake,
 * Knowledge Provenance suite). The calling agent owns the recognition; the
 * tool validates the typed payload and commits it through the shared
 * extraction-intake primitive. OSB never runs a model here.
 *
 * The handler is exercised directly with a minimal ServerContext - the arg
 * validation and the INVALID_PARAMS translation are the surface under test.
 */

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

import { bootstrapBrain } from "../../src/core/brain/init.ts";
import { atomicWriteFileSync } from "../../src/core/fs-atomic.ts";
import { getEntity, listEntities } from "../../src/core/brain/entities/registry.ts";
import {
  INTAKE_TRUST,
  SOURCE_CONTENT_HASH_FRONTMATTER_KEY,
} from "../../src/core/brain/trust/untrusted-provenance.ts";
import { TRANSPORT_REACH } from "../../src/core/graph/transport-reach.ts";
import { NER_TOOLS } from "../../src/mcp/brain/ner-tools.ts";
import { MCPError } from "../../src/mcp/protocol.ts";
import type { ServerContext } from "../../src/mcp/tool-contract.ts";
import { brainPageTexts } from "../helpers/brain-pages.ts";
import { CHMOD_CANNOT_DENY } from "../helpers/platform.ts";

let vault: string;
let configHome: string;
let ctx: ServerContext;

beforeEach(() => {
  vault = mkdtempSync(join(tmpdir(), "o2b-ner-vault-"));
  configHome = mkdtempSync(join(tmpdir(), "o2b-ner-cfg-"));
  const configPath = join(configHome, "config.yaml");
  atomicWriteFileSync(configPath, `vault: ${vault}\nagent_name: claude\n`);
  bootstrapBrain(vault, { configPath });
  ctx = { vault, configPath, repoRoot: null };
});

afterEach(() => {
  // The locked directory first: a 0-mode directory cannot be walked, so the
  // vault removal below would fail on the test that creates one.
  try {
    chmodSync(join(vault, LOCKED_DIR), 0o755);
  } catch {
    // Only one test creates it.
  }
  rmSync(vault, { recursive: true, force: true });
  rmSync(configHome, { recursive: true, force: true });
});

/** A directory this vault denies itself, so `stat` answers with an errno. */
const LOCKED_DIR = "Locked";

const handler = NER_TOOLS[0]!.handler;

/**
 * A cited source is trusted only when the file it names is really there
 * (GitHub #160), so every intake below that expects its entities in the
 * canonical registry seeds the note it claims to have read.
 */
function seed(rel: string): void {
  const abs = join(vault, rel);
  mkdirSync(join(abs, ".."), { recursive: true });
  writeFileSync(abs, `bytes of ${rel}\n`, "utf8");
}

describe("brain_intake_entities", () => {
  test("intakes agent-supplied entities into the registry", async () => {
    seed("Notes/scaling.md");
    const res = await handler(ctx, {
      source: "[[Notes/scaling.md]]",
      entities: [
        { category: "concept", name: "Layer 2s" },
        { category: "people", name: "Vitalik", aliases: ["V."] },
      ],
    });
    expect(res).toEqual({
      entities_created: [expect.any(String), expect.any(String)],
      entities_updated: [],
      relations_applied: 0,
      trust: "trusted",
    });
    expect(listEntities(vault)).toHaveLength(2);
    expect(getEntity(vault, { category: "concept", query: "Layer 2s" })?.name).toBe("Layer 2s");
  });

  test("applies typed relations between extracted entities", async () => {
    seed("Notes/restaking.md");
    const res = await handler(ctx, {
      source: "[[Notes/restaking.md]]",
      entities: [
        { category: "concept", name: "Restaking" },
        { category: "concept", name: "Validators" },
      ],
      relations: [{ from: "Restaking", relation: "related", to: "Validators" }],
    });
    expect(res).toMatchObject({ relations_applied: 1 });
    const restaking = getEntity(vault, { category: "concept", query: "Restaking" });
    expect(restaking?.relations.some((r) => r.relation === "related")).toBe(true);
  });

  test("cites the source wikilink in a newly created entity body", async () => {
    seed("Articles/eth-roadmap.md");
    await handler(ctx, {
      entities: [{ category: "concept", name: "Sharding" }],
      source: "[[Articles/eth-roadmap.md]]",
    });
    const sharding = getEntity(vault, { category: "concept", query: "Sharding" });
    expect(sharding?.body).toContain("## Sources");
    expect(sharding?.body).toContain("[[Articles/eth-roadmap.md]]");
  });

  test("rejects an empty entities array with INVALID_PARAMS and writes nothing", async () => {
    await expect(handler(ctx, { entities: [] })).rejects.toThrow(MCPError);
    expect(listEntities(vault)).toHaveLength(0);
  });

  /**
   * The classifier refuses an unreadable source rather than calling it
   * untrusted, and that refusal reaches the caller as an MCP error. Rethrown
   * verbatim, the Node errno spells out `/home/<user>/<vault>/Locked/note.md`
   * - an existence-and-permission oracle over the operator's filesystem,
   * queried with a string the caller chose. The refusal is right; the
   * operator's path in the answer is not.
   */
  // chmod cannot deny access on Windows or as root (tests/helpers/platform.ts).
  test.skipIf(CHMOD_CANNOT_DENY)("an unreadable source fails without naming a path", async () => {
    const locked = join(vault, LOCKED_DIR);
    mkdirSync(locked, { recursive: true });
    writeFileSync(join(locked, "note.md"), "bytes\n", "utf8");
    chmodSync(locked, 0o000);
    let thrown: unknown;
    try {
      // At local reach: a caller that may not read the page is answered as
      // for an absent one before the stat is made (source-reach-first.test.ts).
      await handler(
        { ...ctx, reach: TRANSPORT_REACH.local },
        {
          source: `[[${LOCKED_DIR}/note.md]]`,
          entities: [{ category: "concept", name: "Restaking" }],
        },
      );
    } catch (err) {
      thrown = err;
    }
    expect(thrown).toBeInstanceOf(MCPError);
    const message = (thrown as Error).message;
    expect(message).toContain(`${LOCKED_DIR}/note.md`);
    expect(message).toContain("EACCES");
    expect(message).not.toContain(vault);
    expect(message).not.toContain("permission denied");
    expect(listEntities(vault)).toHaveLength(0);
  });

  test("translates an unknown relation into INVALID_PARAMS with no partial write", async () => {
    // A real source, so the refusal under test is the relation vocabulary and
    // not the source contract checked before it.
    seed("Notes/scaling.md");
    await expect(
      handler(ctx, {
        source: "[[Notes/scaling.md]]",
        entities: [
          { category: "concept", name: "A" },
          { category: "concept", name: "B" },
        ],
        relations: [{ from: "A", relation: "causes", to: "B" }],
      }),
    ).rejects.toThrow(MCPError);
    expect(listEntities(vault)).toHaveLength(0);
  });
});

/**
 * A page the caller cannot read at its reach is cited exactly like an absent
 * one: the intake commits in the untrusted lane and records no digest of it.
 */
describe("brain_intake_entities - a page withheld at the caller's reach", () => {
  const PRIVATE_PATH = "Notes/secret.md";
  const ABSENT = "Notes/absent.md";

  beforeEach(() => {
    mkdirSync(join(vault, "Notes"), { recursive: true });
    writeFileSync(
      join(vault, PRIVATE_PATH),
      "---\nvisibility: private\n---\nThe code is ZX8.\n",
      "utf8",
    );
  });

  const intake = (source: string, reachCtx: ServerContext = ctx) =>
    handler(reachCtx, { source, entities: [{ category: "concept", name: "Codes" }] }) as Promise<{
      trust: string;
    }>;

  test("answers like an absent source and writes no digest", async () => {
    const hidden = await intake(PRIVATE_PATH);
    const absent = await intake(ABSENT);
    expect(hidden.trust).toBe(INTAKE_TRUST.untrusted);
    expect(hidden.trust).toBe(absent.trust);
    for (const page of brainPageTexts(vault))
      expect(page).not.toContain(SOURCE_CONTENT_HASH_FRONTMATTER_KEY);
  });

  test("at local reach the same page is trusted, and no digest of it is recorded", async () => {
    // The entity pages do not inherit the page's reservation, so its digest
    // would be readable where the page is not.
    const res = await intake(PRIVATE_PATH, { ...ctx, reach: TRANSPORT_REACH.local });
    expect(res.trust).toBe(INTAKE_TRUST.trusted);
    for (const page of brainPageTexts(vault))
      expect(page).not.toContain(SOURCE_CONTENT_HASH_FRONTMATTER_KEY);
  });
});