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
16.5 KB
Raw Blame
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import { mkdirSync, mkdtempSync, rmSync } 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 { buildToolTable } from "../../src/mcp/tools.ts";
import { TRANSPORT_REACH } from "../../src/core/graph/transport-reach.ts";
import { REMOTE_DENY_VISIBILITY_TOKEN } from "../../src/core/graph/visibility.ts";
import { UNTRUSTED_SOURCE_TAG } from "../../src/core/brain/untrusted-source.ts";

/**
 * The fence a remote read of an unstamped decision page carries
 * (delivery-trust, lane A): the server below mints no reach, so every
 * call in this file is a remote one.
 */
function fenced(body: string): string {
  return (
    `<${UNTRUSTED_SOURCE_TAG} origin="stored text: unverified provenance (no derivable stamps)">\n` +
    `${body}\n</${UNTRUSTED_SOURCE_TAG}>`
  );
}

let vault: string;

beforeEach(() => {
  vault = mkdtempSync(join(tmpdir(), "o2b-decision-tool-"));
  // An unswitched vault: its Brain/ tree is the legacy layout under test.
  mkdirSync(join(vault, "Brain"), { recursive: true });
});
afterEach(() => {
  rmSync(vault, { recursive: true, force: true });
});

async function initialize(server: MCPServer): Promise<void> {
  await server.handleRequest({
    jsonrpc: JSONRPC_VERSION,
    id: 1,
    method: "initialize",
    params: {
      protocolVersion: PROTOCOL_VERSION,
      capabilities: {},
      clientInfo: { name: "decision-test", version: "0" },
    },
  });
  await server.handleRequest({ jsonrpc: JSONRPC_VERSION, method: "notifications/initialized" });
}

async function call(
  server: MCPServer,
  args: Record<string, unknown>,
): Promise<{ result?: unknown; error?: unknown }> {
  return (await server.handleRequest({
    jsonrpc: JSONRPC_VERSION,
    id: 9,
    method: "tools/call",
    params: { name: "brain_decision", arguments: args },
  })) as { result?: unknown; error?: unknown };
}

function payload(response: { result?: unknown }): Record<string, unknown> {
  const result = response.result as { content: ReadonlyArray<{ type: string; text: string }> };
  return JSON.parse(result.content[0]!.text);
}

function errorMessage(response: { error?: unknown }): string {
  return (response.error as { message?: string } | undefined)?.message ?? "";
}

describe("brain_decision tool", () => {
  test("registered in the full tool table", () => {
    expect(buildToolTable("full").find((t) => t.name === "brain_decision")).toBeDefined();
  });

  test("records a decision and reads it back with its outcome", async () => {
    const server = new MCPServer({ vault, configPath: null });
    await initialize(server);
    const recorded = payload(
      await call(server, {
        action: "record",
        title: "Adopt Bun runtime",
        chosen: "Bun",
        assumption: "Bun stays compatible",
        review_date: "2026-12-01",
      }),
    );
    expect(recorded["id"]).toBe("decision-adopt-bun-runtime");
    expect(recorded["obligation_created"]).toBe(true);

    const outcome = payload(
      await call(server, { action: "outcome", slug: "adopt-bun-runtime", outcome: "held up" }),
    );
    // The write echo stays the authored bytes; the read-back fences.
    expect(outcome["outcome"]).toBe("held up");

    const shown = payload(await call(server, { action: "show", slug: "adopt-bun-runtime" }));
    expect(shown["outcome"]).toBe(fenced("held up"));
  });

  test("similar surfaces a prior decision", async () => {
    const server = new MCPServer({ vault, configPath: null });
    await initialize(server);
    await call(server, {
      action: "record",
      title: "Adopt Bun runtime for CLI",
      chosen: "Bun",
      assumption: "x",
      review_date: "2026-12-01",
    });
    const similar = payload(
      await call(server, {
        action: "similar",
        title: "Adopt Bun runtime for server",
        chosen: "Bun",
      }),
    );
    expect((similar["similar"] as unknown[]).length).toBeGreaterThanOrEqual(1);
  });

  test("show surfaces commitment when set and omits it when unset (B3)", async () => {
    const server = new MCPServer({ vault, configPath: null });
    await initialize(server);
    await call(server, {
      action: "record",
      title: "Committed choice",
      chosen: "X",
      assumption: "a",
      review_date: "2026-12-01",
      commitment: "decided",
    });
    await call(server, {
      action: "record",
      title: "Loose choice",
      chosen: "Y",
      assumption: "b",
      review_date: "2026-12-01",
    });
    const withCommitment = payload(
      await call(server, { action: "show", slug: "committed-choice" }),
    );
    expect(withCommitment["commitment"]).toBe("decided");
    const without = payload(await call(server, { action: "show", slug: "loose-choice" }));
    expect("commitment" in without).toBe(false);
  });

  test("rate, list rated, and compare (B2)", async () => {
    const server = new MCPServer({ vault, configPath: null });
    await initialize(server);
    await call(server, {
      action: "record",
      title: "Option A",
      chosen: "A",
      assumption: "x",
      review_date: "2026-12-01",
      rating: 4,
    });
    await call(server, {
      action: "record",
      title: "Option B",
      chosen: "B",
      assumption: "y",
      review_date: "2026-12-01",
    });
    const rated = payload(await call(server, { action: "rate", slug: "option-b", rating: 5 }));
    expect(rated["rating"]).toBe(5);

    const list = payload(await call(server, { action: "list", rated: true }));
    const decisions = list["decisions"] as Array<{ rating: number }>;
    expect(decisions.map((d) => d.rating)).toEqual([5, 4]);

    const compared = payload(
      await call(server, { action: "compare", slugs: ["option-a", "option-b"] }),
    );
    expect((compared["decisions"] as unknown[]).length).toBe(2);
  });

  test("out-of-range rating returns an error", async () => {
    const server = new MCPServer({ vault, configPath: null });
    await initialize(server);
    await call(server, {
      action: "record",
      title: "Option C",
      chosen: "C",
      assumption: "z",
      review_date: "2026-12-01",
    });
    const res = await call(server, { action: "rate", slug: "option-c", rating: 9 });
    expect(res.error).toBeDefined();
  });

  test("history reads decision-change receipts (B4)", async () => {
    const server = new MCPServer({ vault, configPath: null });
    await initialize(server);
    // A supersede/tombstone emits a decision-change receipt via the hook.
    await call(server, {
      action: "record",
      title: "Old choice",
      chosen: "old",
      assumption: "x",
      review_date: "2026-12-01",
    });
    await call(server, {
      action: "record",
      title: "New choice",
      chosen: "new",
      assumption: "y",
      review_date: "2026-12-01",
    });
    const supersede = (await server.handleRequest({
      jsonrpc: JSONRPC_VERSION,
      id: 20,
      method: "tools/call",
      params: {
        name: "brain_lifecycle",
        arguments: {
          action: "supersede",
          predecessor: "Brain/decisions/decision-old-choice.md",
          successor: "decision-new-choice",
        },
      },
    })) as { result?: unknown };
    expect(supersede.result).toBeDefined();

    const history = payload(await call(server, { action: "history" }));
    // Two record creations each emit a decision-record receipt (B4), plus
    // the supersede receipt from the lifecycle hook.
    expect(history["total"]).toBe(3);
    const receipts = history["receipts"] as Array<{ reason_code: string }>;
    const codes = receipts.map((r) => r.reason_code);
    expect(codes.filter((c) => c === "decision-record").length).toBe(2);
    expect(codes).toContain("supersede");
  });

  test("recall is disabled (byte-identical) when unconfigured (B5)", async () => {
    const server = new MCPServer({ vault, configPath: null });
    await initialize(server);
    await call(server, {
      action: "record",
      title: "Adopt Bun runtime",
      chosen: "Bun",
      assumption: "x",
      review_date: "2026-12-01",
      rating: 5,
    });
    const res = payload(await call(server, { action: "recall", prompt: "adopt Bun runtime" }));
    expect(res["enabled"]).toBe(false);
    expect(res["surfaced"]).toBeNull();
    expect(res["text"]).toBe("");
  });

  test("recall resurfaces a rated decision when configured (B5)", async () => {
    process.env["OPEN_SECOND_BRAIN_DECISION_RECALL_MAX_PER_SESSION"] = "3";
    try {
      const server = new MCPServer({ vault, configPath: null });
      await initialize(server);
      await call(server, {
        action: "record",
        title: "Adopt Bun runtime for the CLI",
        chosen: "Bun",
        assumption: "x",
        review_date: "2026-12-01",
        rating: 5,
      });
      const res = payload(
        await call(server, { action: "recall", prompt: "should we adopt Bun runtime for the API" }),
      );
      expect(res["enabled"]).toBe(true);
      expect((res["surfaced"] as { slug: string }).slug).toBe("adopt-bun-runtime-for-the-cli");
      expect(res["text"]).toContain("Recalled decision");
    } finally {
      delete process.env["OPEN_SECOND_BRAIN_DECISION_RECALL_MAX_PER_SESSION"];
    }
  });

  test("malformed input returns an error result", async () => {
    const server = new MCPServer({ vault, configPath: null });
    await initialize(server);
    const res = await call(server, {
      action: "record",
      title: "x",
      chosen: "y",
      assumption: "z",
      review_date: "not-a-date",
    });
    expect(res.error).toBeDefined();
  });
});

describe("brain_decision open-decision actions", () => {
  test("open parks a question, list_open and show_open read it, resolve mints the page", async () => {
    const server = new MCPServer({ vault, configPath: null });
    await initialize(server);
    const opened = payload(
      await call(server, {
        action: "open",
        title: "Which HTTP client for ingest",
        question: "Which HTTP client should the ingest lane adopt?",
        options: ["bun fetch", "undici"],
        context: "Needs pooling.",
      }),
    );
    expect(opened["id"]).toBe("open-which-http-client-for-ingest");
    expect(opened["status"]).toBe("open");

    const listed = payload(await call(server, { action: "list_open" }));
    expect((listed["open_decisions"] as unknown[]).length).toBe(1);
    expect(listed["unreadable"]).toEqual([]);

    const shown = payload(await call(server, { action: "show_open", id: opened["id"] }));
    expect(shown["question"]).toBe(fenced("Which HTTP client should the ingest lane adopt?"));
    expect(shown["options"]).toEqual(["bun fetch", "undici"]);

    const resolved = payload(
      await call(server, { action: "resolve", id: opened["id"], choice: "bun fetch" }),
    );
    expect(resolved["decision"]).toBe("decision-which-http-client-for-ingest");

    // The minted page is a real decision page, readable via `show`.
    const page = payload(
      await call(server, { action: "show", slug: "which-http-client-for-ingest" }),
    );
    expect(page["chosen"]).toBe("bun fetch");

    // The open record is terminal now: the open filter shows nothing,
    // and resolving again refuses.
    const after = payload(await call(server, { action: "list_open", status: "open" }));
    expect(after["open_decisions"]).toEqual([]);
    const again = await call(server, {
      action: "resolve",
      id: opened["id"],
      choice: "undici",
    });
    expect(again.error).toBeDefined();
  });

  test("list_open partitions by status and names unreadable records", async () => {
    const { readFileSync, writeFileSync } = await import("node:fs");
    const { join } = await import("node:path");
    const server = new MCPServer({ vault, configPath: null });
    await initialize(server);
    const openRec = payload(
      await call(server, {
        action: "open",
        title: "Keep the legacy importer",
        question: "Do we keep the legacy importer?",
        options: ["keep", "drop"],
      }),
    );
    const discardRec = payload(
      await call(server, {
        action: "open",
        title: "Retry budget for ingest",
        question: "Which retry budget for ingest?",
        options: ["3", "5"],
      }),
    );
    payload(await call(server, { action: "discard", id: discardRec["id"], reason: "superseded" }));

    const openList = payload(await call(server, { action: "list_open", status: "open" }));
    expect((openList["open_decisions"] as Array<{ id: string }>).map((r) => r.id)).toEqual([
      openRec["id"] as string,
    ]);
    const discarded = payload(await call(server, { action: "list_open", status: "discarded" }));
    expect((discarded["open_decisions"] as Array<{ id: string }>).map((r) => r.id)).toEqual([
      discardRec["id"] as string,
    ]);

    // A hand-edited status is confined to its record: named, not fatal,
    // and it never hides the readable sibling.
    const path = join(vault, "Brain", "decisions", `${openRec["id"] as string}.md`);
    writeFileSync(path, readFileSync(path, "utf8").replace("status: open", "status: gone"), "utf8");
    const broken = payload(await call(server, { action: "list_open" }));
    expect((broken["open_decisions"] as Array<{ id: string }>).map((r) => r.id)).toEqual([
      discardRec["id"] as string,
    ]);
    expect((broken["unreadable"] as unknown[]).length).toBe(1);
  });

  test("resolving a choice outside the enumerated options refuses", async () => {
    const server = new MCPServer({ vault, configPath: null });
    await initialize(server);
    const opened = payload(
      await call(server, {
        action: "open",
        title: "Pick a queue",
        question: "Which queue backs the worker?",
        options: ["postgres", "rabbit"],
      }),
    );
    const res = await call(server, {
      action: "resolve",
      id: opened["id"],
      choice: "kafka",
    });
    expect(res.error).toBeDefined();
  });

  test("resolve and discard answer a below-reach id exactly like an absent one", async () => {
    const { readFileSync, writeFileSync } = await import("node:fs");
    const { join } = await import("node:path");
    const local = new MCPServer({ vault, configPath: null }, { reach: TRANSPORT_REACH.local });
    await initialize(local);
    const opened = payload(
      await call(local, {
        action: "open",
        title: "Reach-gated question",
        question: "May a below-reach caller act on this record?",
        options: ["yes", "no"],
      }),
    );
    // Reserve the record against remote reads, the dead-ends-reach way.
    const path = join(vault, "Brain", "decisions", `${opened["id"] as string}.md`);
    const text = readFileSync(path, "utf8");
    const close = text.indexOf("\n---\n", "---\n".length);
    writeFileSync(
      path,
      `${text.slice(0, close)}\nvisibility: [${REMOTE_DENY_VISIBILITY_TOKEN}]${text.slice(close)}`,
      "utf8",
    );

    // A server with no reach minted is a remote caller: both transitions
    // answer with the absent id's error, never a reach distinction.
    const remote = new MCPServer({ vault, configPath: null });
    await initialize(remote);
    const gatedResolve = await call(remote, {
      action: "resolve",
      id: opened["id"],
      choice: "yes",
    });
    expect(gatedResolve.error).toBeDefined();
    expect(errorMessage(gatedResolve)).toBe(
      `brain_decision: no open decision: ${opened["id"] as string}`,
    );
    const gatedDiscard = await call(remote, { action: "discard", id: opened["id"], reason: "x" });
    expect(errorMessage(gatedDiscard)).toBe(
      `brain_decision: no open decision: ${opened["id"] as string}`,
    );

    // The record was not touched, and a local caller can still act on it.
    const listed = payload(await call(local, { action: "list_open", status: "open" }));
    expect((listed["open_decisions"] as unknown[]).length).toBe(1);
    const resolved = payload(
      await call(local, { action: "resolve", id: opened["id"], choice: "yes" }),
    );
    expect(resolved["decision"]).toBe("decision-reach-gated-question");
  });

  test("no new tool was added: the open actions ride the existing brain_decision tool", async () => {
    const { buildToolTable } = await import("../../src/mcp/tools.ts");
    const table = buildToolTable("full");
    expect(table.find((t) => t.name === "brain_decision")).toBeDefined();
    const action = (
      table.find((t) => t.name === "brain_decision")!.inputSchema as {
        properties: { action: { enum: string[] } };
      }
    ).properties.action.enum;
    for (const wanted of ["open", "list_open", "show_open", "resolve", "discard"]) {
      expect(action).toContain(wanted);
    }
  });
});