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
22.6 KB
Raw Blame
/**
 * Per-surface error codes at the MCP boundary.
 *
 * The boundary seam can only see a class; the surfaces below know a more
 * precise reason and name it in `error.data.code` from the closed registry
 * in `src/mcp/tool-error-codes.ts`. Every message stays byte-identical to
 * the one it replaced, because agents and the Hermes bridge parse it.
 *
 * Handlers are called directly: the precise code is set at the throw, and
 * the seam keeps a thrower-supplied code untouched.
 */

import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import { 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 { brainConfigPath } from "../../src/core/brain/paths.ts";
import { writePreference } from "../../src/core/brain/preference.ts";
import { createTriggers } from "../../src/core/brain/triggers/store.ts";
import type { InsightCandidate } from "../../src/core/brain/triggers/types.ts";
import { BRAIN_CONFIDENCE, BRAIN_PREFERENCE_STATUS } from "../../src/core/brain/types.ts";
import { GATE_MODE } from "../../src/core/integrity/stamp.ts";
import { assertKnownArguments } from "../../src/mcp/argument-guard.ts";
import { FEEDBACK_TOOLS } from "../../src/mcp/brain/feedback-tools.ts";
import { LIFECYCLE_FILE_TOOLS } from "../../src/mcp/brain/lifecycle-file-tools.ts";
import { AGENT_SCOPE_ARG_NAME, coerceAgentScope } from "../../src/mcp/coerce.ts";
import { OWNER_SCOPE_REFUSAL } from "../../src/mcp/owner-scope-refusal.ts";
import { INVALID_PARAMS, MCPError } from "../../src/mcp/protocol.ts";
import { assertNoCallerSuppliedReach, REACH_REFUSAL } from "../../src/mcp/reach-refusal.ts";
import { MCPServer } from "../../src/mcp/server.ts";
import { SKILL_TOOLS } from "../../src/mcp/skill-tools.ts";
import type { ServerContext, ToolDefinition } from "../../src/mcp/tool-contract.ts";
import { isToolErrorCode } from "../../src/mcp/tool-error-codes.ts";
import { buildToolTable, findTool } from "../../src/mcp/tools.ts";
import { readRpcErrorCode } from "../helpers/tool-error-envelope.ts";

const TOOLS = buildToolTable("full");

/** The `MCPError` a call raised; fails the test when it answered instead. */
async function raised(run: () => unknown): Promise<MCPError> {
  let thrown: unknown;
  try {
    await run();
  } catch (exc) {
    thrown = exc;
  }
  expect(thrown).toBeInstanceOf(MCPError);
  return thrown as MCPError;
}

/** The code a raised error carries, checked against the closed registry. */
function codeOf(err: MCPError): string {
  const code = (err.data as { readonly code?: unknown } | undefined)?.code;
  expect(typeof code).toBe("string");
  expect(isToolErrorCode(code)).toBe(true);
  return code as string;
}

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

beforeEach(() => {
  tmp = mkdtempSync(join(tmpdir(), "o2b-surface-codes-"));
  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 });
});

// ----- skills -----------------------------------------------------------------

function skillCtx(): ServerContext {
  const skillDir = join(tmp, "skills", "demo-skill");
  mkdirSync(skillDir, { recursive: true });
  writeFileSync(
    join(skillDir, "SKILL.md"),
    "---\nname: demo-skill\ndescription: Demonstration skill.\n---\n\n# Demo\n",
  );
  return { vault, configPath: null, repoRoot: tmp };
}

const getSkill = (): ToolDefinition => SKILL_TOOLS.find((t) => t.name === "get_skill")!;

describe("skill errors", () => {
  test("an unknown skill answers unknown_skill", async () => {
    const err = await raised(() => getSkill().handler(skillCtx(), { name: "no-such-skill" }));
    expect(err.code).toBe(INVALID_PARAMS);
    expect(err.message).toBe("unknown skill: no-such-skill. Known skills: demo-skill");
    expect(codeOf(err)).toBe("unknown_skill");
  });

  test("a missing skill file answers skill_not_found", async () => {
    const err = await raised(() =>
      getSkill().handler(skillCtx(), { name: "demo-skill", file_path: "missing.md" }),
    );
    expect(err.message).toBe("skill file not found: missing.md");
    expect(codeOf(err)).toBe("skill_not_found");
  });

  test("an escaping skill file path answers skill_invalid_path", async () => {
    const err = await raised(() =>
      getSkill().handler(skillCtx(), { name: "demo-skill", file_path: "../outside.md" }),
    );
    expect(err.message).toBe("skill file path must stay inside the skill directory");
    expect(codeOf(err)).toBe("skill_invalid_path");
  });
});

// ----- workspace refusals ------------------------------------------------------

const OWNER_A = "agent-a";
const OWNER_B = "agent-b";
const TRIGGER_NOW = new Date("2099-06-03T10:00:00Z");

function candidate(source: string): InsightCandidate {
  return {
    kind: "contradiction",
    urgency: "high",
    reason: `${source} contradicts pref-other`,
    suggestedAction: "Review the pair",
    sourceArtifacts: [`[[${source}]]`],
    contextSnippets: [],
    cooldownKey: `contradiction:${source}:pref-other`,
  };
}

function workspaceCtx(agentName?: string): ServerContext {
  return { vault, configPath, repoRoot: null, ...(agentName ? { agentName } : {}) };
}

describe("workspace refusals", () => {
  test("an unknown brain_intention operation answers unknown_operation", async () => {
    const err = await raised(() =>
      findTool(TOOLS, "brain_intention").handler(workspaceCtx(), {
        operation: "rename",
        scope: "w",
      }),
    );
    expect(err.message).toBe("brain_intention operation must be one of: set, show, list, move");
    expect(codeOf(err)).toBe("unknown_operation");
  });

  test("an unknown brain_trigger operation answers unknown_operation", async () => {
    const err = await raised(() =>
      findTool(TOOLS, "brain_trigger").handler(workspaceCtx(), { operation: "rename" }),
    );
    expect(err.message).toStartWith("brain_trigger operation must be one of: ");
    expect(codeOf(err)).toBe("unknown_operation");
  });

  test("an unknown trigger status answers invalid_status", async () => {
    const err = await raised(() =>
      findTool(TOOLS, "brain_trigger").handler(workspaceCtx(), {
        operation: "list",
        status: "bogus",
      }),
    );
    expect(err.message).toBe("brain_trigger: unknown status 'bogus'");
    expect(codeOf(err)).toBe("invalid_status");
  });

  test("an absent id and an id the caller may not see answer the same code and message", async () => {
    mkdirSync(join(vault, "Brain", "preferences"), { recursive: true });
    writePreference(vault, {
      slug: "owned-by-a",
      topic: "owned-by-a",
      principle: "principle for owned-by-a",
      created_at: "2026-05-01T00:00:00Z",
      unconfirmed_until: "2026-05-08T00:00:00Z",
      status: BRAIN_PREFERENCE_STATUS.confirmed,
      evidenced_by: ["[[sig-2026-05-01-owned-by-a]]"],
      confirmed_at: "2026-05-02T00:00:00Z",
      applied_count: 1,
      violated_count: 0,
      last_evidence_at: "2026-05-02T00:00:00Z",
      confidence: BRAIN_CONFIDENCE.high,
      confidence_value: 0.8,
      owner: OWNER_A,
    });
    const { created } = createTriggers(vault, [candidate("pref-owned-by-a")], { now: TRIGGER_NOW });
    const hiddenId = created[0]!.id;
    writeFileSync(
      brainConfigPath(vault),
      `schema_version: 1\nintegrity:\n  owner_scope_delivery: ${GATE_MODE.fail}\n`,
    );
    const absentId = `${hiddenId.slice(0, -4)}zzzz`;
    const trigger = findTool(TOOLS, "brain_trigger");

    const hidden = await raised(() =>
      trigger.handler(workspaceCtx(OWNER_B), { operation: "acknowledge", id: hiddenId }),
    );
    const absent = await raised(() =>
      trigger.handler(workspaceCtx(OWNER_B), { operation: "acknowledge", id: absentId }),
    );

    expect(codeOf(hidden)).toBe("trigger_transition_refused");
    expect(codeOf(absent)).toBe("trigger_transition_refused");
    expect(hidden.message.replace(hiddenId, "<id>")).toBe(absent.message.replace(absentId, "<id>"));
    expect(hidden.data).toEqual(absent.data);
  });
});

// ----- write session ----------------------------------------------------------

const writeSession = (): ToolDefinition => findTool(TOOLS, "brain_write_session");
const sessionCtx = (): ServerContext => ({ vault, configPath, repoRoot: null });

describe("write-session codes", () => {
  test("an op that needs a session but names none answers session_id_required", async () => {
    const err = await raised(() => writeSession().handler(sessionCtx(), { op: "approve" }));
    expect(err.message).toBe("brain_write_session: op 'approve' requires session_id");
    expect(codeOf(err)).toBe("session_id_required");
  });

  test("an unknown session id answers write_session_unknown on every op", async () => {
    const errors = await Promise.all(
      ["approve", "abandon", "status"].map((op) =>
        raised(() => writeSession().handler(sessionCtx(), { op, session_id: "ws-does-not-exist" })),
      ),
    );
    for (const err of errors) {
      expect(err.message).toBe("unknown write-session: ws-does-not-exist");
      expect(codeOf(err)).toBe("write_session_unknown");
    }
  });

  test("a terminal session answers write_session_terminal", async () => {
    const opened = (await writeSession().handler(sessionCtx(), {
      op: "open",
      kind: "artifact",
      target: "Brain/notes/terminal.md",
      agent: "mcp-agent",
    })) as Record<string, unknown>;
    const id = opened["session_id"] as string;
    await writeSession().handler(sessionCtx(), { op: "abandon", session_id: id });

    const err = await raised(() =>
      writeSession().handler(sessionCtx(), { op: "approve", session_id: id }),
    );
    expect(err.message).toStartWith(`write-session ${id} is terminal (`);
    expect(codeOf(err)).toBe("write_session_terminal");
  });
});

describe("write-session codes at the boundary", () => {
  test("a structured request failure gains the invalid_params default after its errors", async () => {
    const server = new MCPServer({ vault });
    const response = await server.handleRequest({
      jsonrpc: "2.0",
      id: 1,
      method: "tools/call",
      params: {
        name: "brain_write_session",
        arguments: { op: "open", kind: "artifact", target: "../outside.md", agent: "mcp-agent" },
      },
    });
    expect(response?.error?.code).toBe(INVALID_PARAMS);
    expect(response?.error?.message).toStartWith("target rejected: ");
    // Byte-identical to v1.65.0 up to the default: the handler hands over
    // the list alone, and the boundary seam adds `invalid_params` after it.
    const data = response?.error?.data as {
      readonly errors: ReadonlyArray<unknown>;
      readonly code: string;
    };
    expect(Object.keys(data)).toEqual(["errors", "code"]);
    expect(data.errors.length).toBeGreaterThan(0);
    expect(readRpcErrorCode(response)).toBe("invalid_params");
  });
});

// ----- argument guard, reach refusal, owner-scope refusal -----------------------

describe("refusal codes", () => {
  const CLOSED_TOOL: ToolDefinition = {
    name: "demo_tool",
    description: "A demo tool.",
    inputSchema: {
      type: "object",
      properties: { query: { type: "string", description: "The search text." } },
      additionalProperties: false,
    },
    kind: "read",
    handler: () => ({}),
  };

  test("an undeclared argument answers unknown_argument with its data unchanged", async () => {
    const err = await raised(() => assertKnownArguments(CLOSED_TOOL, { quiery: "x" }));
    expect(codeOf(err)).toBe("unknown_argument");
    expect(err.data).toEqual({
      tool: "demo_tool",
      unknown_arguments: [{ name: "quiery", suggestion: "query" }],
      declared_arguments: ["query"],
      code: "unknown_argument",
    });
  });

  test("a caller-supplied reach answers its own refusal token", async () => {
    const err = await raised(() => assertNoCallerSuppliedReach(CLOSED_TOOL, { reach: "local" }));
    expect(codeOf(err)).toBe(REACH_REFUSAL);
    const data = err.data as Record<string, unknown>;
    expect(data["refused_arguments"]).toEqual(["reach"]);
    expect(data["tool"]).toBe("demo_tool");
  });

  test("an owner-scope refusal answers the outcome it names", async () => {
    writeFileSync(
      brainConfigPath(vault),
      `schema_version: 1\nintegrity:\n  owner_scope_delivery: ${GATE_MODE.fail}\n`,
    );
    const foreign = await raised(() =>
      coerceAgentScope(
        { vault, agentName: "agent-b" },
        { [AGENT_SCOPE_ARG_NAME]: "agent-a" },
        false,
      ),
    );
    expect(foreign.message).toContain(OWNER_SCOPE_REFUSAL.foreignOwner);
    expect(codeOf(foreign)).toBe(OWNER_SCOPE_REFUSAL.foreignOwner);

    const unresolved = await raised(() =>
      coerceAgentScope({ vault, agentName: "agent" }, { [AGENT_SCOPE_ARG_NAME]: "agent-a" }, false),
    );
    expect(unresolved.message).toContain(OWNER_SCOPE_REFUSAL.unresolvedIdentity);
    expect(codeOf(unresolved)).toBe(OWNER_SCOPE_REFUSAL.unresolvedIdentity);
  });
});

// ----- codes a refusing site supplies itself ------------------------------------

const expireTool = (): ToolDefinition => FEEDBACK_TOOLS.find((t) => t.name === "brain_expire")!;
const stubTool = (): ToolDefinition =>
  LIFECYCLE_FILE_TOOLS.find((t) => t.name === "brain_scaffold_stub")!;

describe("thrower-supplied codes are registry members", () => {
  // The boundary keeps a code the refusing site chose, so each of these
  // producers has to name a registered token itself: a client narrowing
  // `error.data.code` with `isToolErrorCode` would reject anything else.
  test("each brain_expire refusal answers a registered code", async () => {
    bootstrapBrain(vault, { configPath });
    const ctx: ServerContext = { vault, configPath, repoRoot: null };
    const refusal = (args: Record<string, unknown>) =>
      raised(() => expireTool().handler(ctx, args));
    const [badDate, missing, unaddressable] = await Promise.all([
      refusal({ id: "sig-2026-01-01-demo", expires: "soon" }),
      refusal({ id: "sig-2026-01-01-demo", expires: "2026-12-31" }),
      refusal({ id: "not-an-id", expires: "2026-12-31" }),
    ]);
    expect(codeOf(badDate)).toBe("ExpirationValueError");
    expect(codeOf(missing)).toBe("ExpirationTargetNotFoundError");
    expect(codeOf(unaddressable)).toBe("InvalidExpirationTargetError");
  });

  test("an argument of the other brain_scaffold_stub action answers a registered code", async () => {
    const ctx: ServerContext = { vault, configPath, repoRoot: null };
    const err = await raised(() =>
      stubTool().handler(ctx, { action: "list", target: "Foo", apply: true }),
    );
    expect(codeOf(err)).toBe("argument_forbidden");
  });
});

// ----- unknown operations ------------------------------------------------------

describe("every operation-dispatching tool answers unknown_operation", () => {
  // One case per dispatch: the argument that selects the operation, set to
  // a value outside the tool's closed set, and the message the refusal has
  // always carried, which stays byte-identical.
  const BOGUS = "no_such_operation";
  const CASES: ReadonlyArray<readonly [string, Record<string, unknown>, string]> = [
    [
      "brain_skill_proposals",
      { operation: BOGUS },
      "brain_skill_proposals: operation must be one of " +
        "learn|list|accept|reject|recover|usage|evidence|page_candidates|page_draft",
    ],
    [
      "brain_procedural_memory",
      { operation: BOGUS },
      "brain_procedural_memory: operation must be one of reconcile|list|mark_used|mark_outcome",
    ],
    [
      "brain_recurrence",
      { operation: BOGUS },
      "brain_recurrence: operation must be one of list|show|learn|forget|purge_source",
    ],
    [
      "brain_procedural_graph",
      { operation: BOGUS },
      "brain_procedural_graph: operation must be one of rebuild|show|hints",
    ],
    [
      "brain_obligation",
      // `slug` is read before the last branch, so the refusal needs one.
      { operation: BOGUS, slug: "demo" },
      "brain_obligation operation must be one of: add, done, list, show, remove",
    ],
    [
      "brain_context_receipts",
      { operation: BOGUS },
      "brain_context_receipts: operation must be list, show, summary, or verify",
    ],
    [
      "brain_attestations",
      { operation: BOGUS },
      "brain_attestations: operation must be list|verify " +
        "(keygen and sign are operator CLI verbs: o2b brain attest)",
    ],
    [
      "brain_context_presets",
      { operation: BOGUS },
      "brain_context_presets: operation must be show, suggest, or diff",
    ],
    [
      "brain_write_session",
      { op: BOGUS },
      `brain_write_session: op must be open|submit|approve|abandon|status|list, got '${BOGUS}'`,
    ],
    [
      "brain_pinned_context",
      { operation: BOGUS },
      "brain_pinned_context operation must be one of: read, write, append, clear",
    ],
    [
      "brain_session_summary",
      { operation: BOGUS },
      "brain_session_summary: operation must be write|get|list",
    ],
    ["brain_benchmark", { operation: BOGUS }, "brain_benchmark: operation must be run"],
    ["brain_tune", { operation: BOGUS }, "brain_tune: operation must be run|status|reset"],
    [
      "brain_recall_telemetry",
      { operation: BOGUS },
      "brain_recall_telemetry: operation must be list, summary, gate_list, gate_summary, observed_reuse, cost, or dead_weight",
    ],
    [
      "brain_route_metrics",
      { operation: BOGUS },
      "brain_route_metrics: operation must be list or summary",
    ],
    [
      "brain_token_impact",
      { operation: BOGUS },
      "brain_token_impact: operation must be record, outcome, list, or summary",
    ],
    [
      "brain_context_pack_outcome",
      { operation: BOGUS },
      "brain_context_pack_outcome: operation must be post, list, or summary",
    ],
    [
      "brain_analytics",
      { view: "attention_flows", operation: BOGUS },
      "brain_analytics view=attention_flows: operation must be one of list|evaluate|render",
    ],
    [
      "brain_bridges",
      { operation: BOGUS },
      "brain_bridges: operation must be discover|list|accept|dismiss",
    ],
    ["brain_clusters", { operation: BOGUS }, "brain_clusters: operation must be run|list"],
    [
      "brain_truth",
      { operation: BOGUS },
      "brain_truth: operation must be ingest|slots|conflicts|aggregate|collisions|events|state",
    ],
    ["brain_dead_ends", { operation: BOGUS }, "brain_dead_ends: operation must be record|list"],
    [
      "brain_claims",
      { operation: BOGUS },
      "brain_claims: 'operation' must be one of current, at, history, replaced, contests, rebuild",
    ],
    [
      "brain_generation_reports",
      { action: BOGUS },
      "brain_generation_reports: action must be record, list, or summary",
    ],
    [
      "brain_labels",
      { operation: BOGUS },
      "brain_labels: operation must be assign|remove|show|suggest",
    ],
    ["brain_tiers", { operation: BOGUS }, "brain_tiers: operation must be check|restore|accept"],
    ["brain_secrets", { operation: BOGUS }, "brain_secrets: operation must be list|run"],
    ["brain_maintenance", { operation: BOGUS }, "brain_maintenance: operation must be run|status"],
    [
      "brain_dream",
      { action: BOGUS },
      "brain_dream: action must be run|stage|validate|apply|retriage|discard|list",
    ],
    [
      "brain_tension",
      { action: BOGUS },
      "brain_tension: 'action' must be one of detect, list, show, confirm, dismiss, resolve, verify",
    ],
    [
      "brain_decision",
      { action: BOGUS },
      "brain_decision: 'action' must be one of record, outcome, rate, show, list, compare, similar, history, recall, open, list_open, show_open, resolve, discard",
    ],
    [
      "brain_lifecycle",
      { action: BOGUS },
      "brain_lifecycle: 'action' must be one of tombstone, supersede, temporal-replace, tip, curator, correct",
    ],
    ["brain_writes", { action: BOGUS }, "brain_writes: 'action' must be one of list, plan_revert"],
    [
      "brain_settings",
      { action: BOGUS },
      "brain_settings: 'action' must be one of get, list, set, unset",
    ],
    [
      "brain_topic",
      { action: BOGUS },
      "brain_topic: 'action' must be one of list, show, review, create, rename, status, goal, assign, unassign, merge, split, link, archive, undo, record",
    ],
    [
      "brain_note_lifecycle",
      { action: BOGUS },
      "brain_note_lifecycle: 'action' must be one of rename, move, archive, delete, move-folder, rename-folder",
    ],
    [
      "brain_scaffold_stub",
      { action: BOGUS },
      "brain_scaffold_stub: 'action' must be one of list, write",
    ],
    [
      "brain_pledge",
      // slug is coerced before the operation dispatch, so the fallthrough
      // refusal only answers once every shared argument is well-formed.
      { operation: BOGUS, slug: "probe-pledge" },
      "brain_pledge operation must be one of: add, fulfill, list, show, remove",
    ],
    [
      "brain_session_grep",
      { operation: BOGUS },
      "brain_session_grep: operation must be 'match' or 'coverage'",
    ],
  ];

  for (const [tool, args, message] of CASES) {
    test(`${tool} answers unknown_operation with its message unchanged`, async () => {
      const err = await raised(() => findTool(TOOLS, tool).handler(workspaceCtx(), args));
      expect(err.message).toBe(message);
      expect(codeOf(err)).toBe("unknown_operation");
    });
  }

  test("the table covers every tool whose schema declares a dispatch enum", () => {
    // Derived from the catalog, so a new dispatcher that forgets the shared
    // code fails here instead of shipping (brain_claims was found by hand).
    const covered = new Set<string>([
      ...CASES.map(([tool]) => tool),
      // pinned by the workspace refusal tests above
      "brain_intention",
      "brain_trigger",
    ]);
    // A host write whose `action` refusal keeps the pinned `invalid_action`.
    const exempt = new Set<string>(["brain_memory_bridge"]);
    const declared = TOOLS.filter((tool) => {
      const props =
        (tool.inputSchema as { readonly properties?: Record<string, { readonly enum?: unknown }> })
          .properties ?? {};
      return ["operation", "op", "action"].some((arg) => Array.isArray(props[arg]?.enum));
    }).map((tool) => tool.name);
    expect(declared.filter((name) => !covered.has(name) && !exempt.has(name))).toEqual([]);
  });

  test("a write batch operation of an unknown kind answers unknown_operation", async () => {
    const err = await raised(() =>
      findTool(TOOLS, "brain_write_batch").handler(workspaceCtx(), {
        operations: [{ op: BOGUS, path: "notes/x.md" }],
      }),
    );
    expect(err.message).toStartWith("brain_write_batch: operations[0].op must be one of ");
    expect(codeOf(err)).toBe("unknown_operation");
  });
});