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.7 KB
Raw Blame
/**
 * `brain_write_session` MCP tool (Agent Write Contract Suite,
 * t_bc36a8a2 + t_0cc6fdff): one tool, op + kind discriminators, the
 * same envelopes as the CLI.
 */

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

import { buildToolTable, findTool } from "../../src/mcp/tools.ts";
import type { ServerContext } from "../../src/mcp/tool-contract.ts";
import {
  VISIBILITY_SURFACE_CATEGORY,
  VISIBILITY_SURFACE_KIND,
  VISIBILITY_SURFACE_REGISTRY,
} from "../../src/core/search/visibility-surface-registry.ts";

let tmp: string;
let vault: string;
let configPath: string;

const GOOD = "---\nkind: note\n---\n\n# MCP note\n\nBody.\n";

beforeEach(() => {
  tmp = mkdtempSync(join(tmpdir(), "o2b-mcp-ws-"));
  vault = join(tmp, "vault");
  mkdirSync(join(vault, "Brain"), { recursive: true });
  configPath = join(tmp, "config.yaml");
  writeFileSync(configPath, `vault: "${vault}"\n`);
});

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

function ctx(): ServerContext {
  return { vault, configPath, repoRoot: null };
}

function tool() {
  return findTool(buildToolTable("full"), "brain_write_session");
}

test("artifact flow: open -> bad submit -> corrected submit -> done", async () => {
  const opened = (await tool().handler(ctx(), {
    op: "open",
    kind: "artifact",
    target: "Brain/notes/mcp.md",
    agent: "mcp-agent",
  })) as Record<string, unknown>;
  expect(opened["status"]).toBe("needs-llm-step");
  const id = opened["session_id"] as string;

  const bad = (await tool().handler(ctx(), {
    op: "submit",
    session_id: id,
    text: "no frontmatter",
  })) as Record<string, unknown>;
  expect(bad["status"]).toBe("needs-correction");
  expect((bad["errors"] as Array<{ code: string }>).map((e) => e.code)).toContain(
    "frontmatter-missing",
  );

  const done = (await tool().handler(ctx(), {
    op: "submit",
    session_id: id,
    text: GOOD,
  })) as Record<string, unknown>;
  expect(done["status"]).toBe("done");
  expect(readFileSync(join(vault, "Brain", "notes", "mcp.md"), "utf8")).toContain("# MCP note");
});

test("panel flow: open -> persona steps -> synthesis -> committed note", async () => {
  const opened = (await tool().handler(ctx(), {
    op: "open",
    kind: "panel",
    topic: "Adopt MCP sessions",
    personas: ["technical", "risk"],
    agent: "mcp-agent",
  })) as Record<string, unknown>;
  expect(opened["step"]).toBe("persona:technical");
  const id = opened["session_id"] as string;

  await tool().handler(ctx(), { op: "submit", session_id: id, text: "Feasible." });
  await tool().handler(ctx(), { op: "submit", session_id: id, text: "Low risk." });
  const done = (await tool().handler(ctx(), {
    op: "submit",
    session_id: id,
    text: "Adopt.",
  })) as Record<string, unknown>;
  expect(done["status"]).toBe("done");
  expect(readFileSync(join(vault, done["target_path"] as string), "utf8")).toContain(
    "## Synthesis",
  );
});

test("status, list, abandon ops round-trip", async () => {
  const opened = (await tool().handler(ctx(), {
    op: "open",
    kind: "artifact",
    target: "Brain/notes/s.md",
  })) as Record<string, unknown>;
  const id = opened["session_id"] as string;

  const status = (await tool().handler(ctx(), { op: "status", session_id: id })) as Record<
    string,
    unknown
  >;
  expect(status["status"]).toBe("needs-llm-step");

  const list = (await tool().handler(ctx(), { op: "list" })) as Record<string, unknown>;
  expect((list["sessions"] as unknown[]).length).toBe(1);

  const abandoned = (await tool().handler(ctx(), { op: "abandon", session_id: id })) as Record<
    string,
    unknown
  >;
  expect(abandoned["status"]).toBe("failed");
});

test("structured request errors surface as MCP invalid-params", async () => {
  await expect(
    tool().handler(ctx(), { op: "open", kind: "artifact", target: "Brain/preferences/x.md" }),
  ).rejects.toThrow(/target rejected/);
  await expect(tool().handler(ctx(), { op: "bogus" })).rejects.toThrow(/op/);
  await expect(tool().handler(ctx(), { op: "submit" })).rejects.toThrow(/session_id/);
});

test("the tool is advertised in full scope but not writer scope", () => {
  expect(() => findTool(buildToolTable("full"), "brain_write_session")).not.toThrow();
  expect(() => findTool(buildToolTable("writer"), "brain_write_session")).toThrow();
});

test("op=list declares a described cursor property", () => {
  const schema = tool().inputSchema as {
    properties: Record<string, { type?: string; maxLength?: number; description?: string }>;
  };
  expect(schema.properties["cursor"]).toMatchObject({ type: "string", maxLength: 32 });
  expect(schema.properties["cursor"]?.description).toBeTruthy();
});

test("op=list walks by cursor: the pages reassemble every session, the last page is null", async () => {
  const ids: string[] = [];
  for (const name of ["walk-a", "walk-b", "walk-c"]) {
    const opened = (await tool().handler(ctx(), {
      op: "open",
      kind: "artifact",
      target: `Brain/notes/${name}.md`,
    })) as Record<string, unknown>;
    ids.push(opened["session_id"] as string);
  }

  const total = 3;
  const limit = 2;
  // Bound the walk by the page arithmetic: ceil(total/limit) pages plus one
  // slack step, so a next_cursor that never turns null (an ignored or
  // never-exhausting cursor) exhausts the budget and fails here instead of
  // hanging the suite.
  const maxSteps = Math.ceil(total / limit) + 1;
  const walked: string[] = [];
  let cursor: string | null = null;
  for (let step = 0; step < maxSteps; step += 1) {
    const page = (await tool().handler(ctx(), {
      op: "list",
      limit,
      ...(cursor !== null ? { cursor } : {}),
    })) as Record<string, unknown>;
    expect(page["total"]).toBe(total);
    // Guard the walk protocol: an ignored cursor is a shape violation,
    // not a stop condition.
    const next = page["next_cursor"];
    expect(next === null || typeof next === "string").toBe(true);
    walked.push(
      ...(page["sessions"] as ReadonlyArray<Record<string, unknown>>).map(
        (s) => s["session_id"] as string,
      ),
    );
    cursor = next as string | null;
    if (cursor === null) break;
  }
  expect(cursor).toBeNull();
  expect(walked.toSorted()).toEqual(ids.toSorted());
  expect(new Set(walked).size).toBe(3);
});

test("op=list refuses a malformed cursor as invalid params", async () => {
  await expect(tool().handler(ctx(), { op: "list", cursor: "!!!not-base64!!!" })).rejects.toThrow(
    /malformed cursor/,
  );
});

test("op=list's all-agents view is the visibility registry's recorded exclusion, not an oversight", () => {
  // The cursor walk over op=list answers every live agent's sessions
  // (target_path, prompt), where the pre-cursor read bounded a single
  // answer at 500. That is a recorded decision, not a gap: the vault's
  // visibility census classifies this surface as deliberately outside
  // the page-visibility model - write-session records are Brain's own
  // transient queue (TTL-swept, operator-shared; the CLI verb
  // `brain write-session list` prints every agent's sessions
  // unfiltered, and op=status/approve/abandon already addressed any
  // session by id), not general vault notes carrying an `owner:` scope
  // the walk could cross. The pin below fails if that verdict is ever
  // silently reclassified, so the boundary stays an argued decision.
  const entry = VISIBILITY_SURFACE_REGISTRY.find(
    (e) => e.surface === "brain_write_session" && e.kind === VISIBILITY_SURFACE_KIND.mcpTool,
  );
  expect(entry?.category).toBe(VISIBILITY_SURFACE_CATEGORY.excluded);
  expect(entry?.reason).toContain("listWriteSessions");
  expect(entry?.reason).toContain("no visibility check");
});