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
/**
* The closed MCP-boundary error registry.
*
* Every tool failure the server answers carries one code from
* `TOOL_ERROR_CODES`. The registry imports the core vocabularies verbatim
* and adds lower snake_case tokens for the uncoded remainder, so these
* tests pin three things: the list is closed and complete, the tokens the
* wire already carries are members unchanged, and the classifier never
* invents a code - an error it does not know is `internal_error`, named on
* stderr by its class name only.
*/
import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
import type { Mock } from "bun:test";
import { BrainPreferenceNotFoundError } from "../../src/core/brain/apply-evidence.ts";
import { CountGuardError } from "../../src/core/brain/count-guard.ts";
import {
ExpirationTargetNotFoundError,
ExpirationValueError,
InvalidExpirationTargetError,
} from "../../src/core/brain/expiration-set.ts";
import {
QUOTE_CHECK_OUTCOME,
QUOTE_UNVERIFIED_CODE,
QuoteCheckError,
} from "../../src/core/brain/distill/quote-verdict.ts";
import { BrainParseError } from "../../src/core/brain/parse-error.ts";
import { BrainStatusFolderMismatchError } from "../../src/core/brain/preference.ts";
import { PinnedBatchError } from "../../src/core/brain/pinned.ts";
import { BrainConfigError } from "../../src/core/brain/policy/errors.ts";
import { SHAPE_VIOLATION_CODES } from "../../src/core/brain/response-shape.ts";
import { SEMANTIC_VIOLATION_CODES } from "../../src/core/brain/response-checks.ts";
import { SafeguardAbortError, SafeguardTimeoutError } from "../../src/core/brain/safeguard.ts";
import { STORAGE_ERROR_CODES } from "../../src/core/brain/storage/capacity-error.ts";
import { WriteBatchError } from "../../src/core/brain/write-batch.ts";
import { ConfigReadError } from "../../src/core/config.ts";
import { SEARCH_ERROR_CODES, SearchError } from "../../src/core/search/search-error.ts";
import { WRITE_BINDING_REFUSED_CODE } from "../../src/core/write-binding/index.ts";
import {
VAULT_ADAPTER_REQUIRED_CODE,
VAULT_BINDING_MISMATCH_CODE,
VaultAdapterRequiredError,
VaultBindingMismatchError,
VaultBindingsUnreadableError,
} from "../../src/core/vault-adapter/index.ts";
import {
PENDING_STAGE_CONFLICT_CODE,
WRITE_REFUSAL_CODES,
} from "../../src/core/brain/pending/pending-lanes.ts";
import {
MIGRATION_IN_PROGRESS_REFUSAL,
VAULT_FROZEN_REFUSAL,
} from "../../src/mcp/frozen-refusal.ts";
import { OutputContractError } from "../../src/mcp/output-contract.ts";
import { OWNER_SCOPE_REFUSALS } from "../../src/mcp/owner-scope-refusal.ts";
import {
INTERNAL_ERROR,
INVALID_PARAMS,
INVALID_REQUEST,
METHOD_NOT_FOUND,
PARSE_ERROR,
} from "../../src/mcp/protocol.ts";
import { REACH_REFUSAL } from "../../src/mcp/reach-refusal.ts";
import {
GENERIC_TOOL_ERROR_CODES,
TOOL_ERROR_CODE,
TOOL_ERROR_CODES,
TOOL_ERROR_META_KEY,
TOOL_ERROR_SCHEMA,
codeForError,
defaultCodeForRpc,
isGenericToolErrorCode,
isToolErrorCode,
toolErrorMeta,
} from "../../src/mcp/tool-error-codes.ts";
/**
* Decision 5 of the design plus `brain_artifact_unparseable` and
* `argument_forbidden` (on the wire before the registry existed): the generic
* tokens this release adds.
*/
const NEW_TOKENS = [
"parse_error",
"invalid_request",
"method_not_found",
"invalid_params",
"internal_error",
"safeguard_timeout",
"safeguard_aborted",
"output_contract_failed",
"config_unreadable",
"skill_not_found",
"skill_invalid_path",
"unknown_skill",
"unknown_operation",
"invalid_status",
"trigger_transition_refused",
"write_session_unknown",
"write_session_terminal",
"session_id_required",
"unknown_argument",
"brain_artifact_unparseable",
"argument_forbidden",
"quote_unverified",
"store_write_failed",
] as const;
/**
* Members of the type-only core vocabularies, spelled out here as the
* independent oracle: the registry's own arrays are checked against the
* core unions by `tsc`, and against this list by the test.
*/
const TYPE_ONLY_MEMBERS = [
// shared brain settings (brain_settings)
"unknown_setting",
"device_setting",
"not_a_setting",
"field_required",
"invalid_setting_value",
"human_value_in_force",
"operator_only_setting",
"private_setting_value",
"no_settings_file",
"settings_unreadable",
// write batch
"invalid_operation",
"invalid_path",
"excluded",
"outside_vault",
"exists",
"target_missing",
"target_unreadable",
"target_frontmatter_lossy",
"blank_overwrite_refused",
"reserved_frontmatter_key",
"owner_write_refused",
"duplicate_target",
"too_many_operations",
"preference_not_found",
"write_binding",
"invalid_document",
"invalid_template",
"config_invalid",
// note lifecycle
"source_missing",
"destination_required",
"destination_forbidden",
"destination_occupied",
"destination_unchanged",
"destination_inside_source",
"move_set_empty",
"wrong_action",
"not_confirmed",
"already_archived",
"cascade_forbidden",
// note revert
"unbounded_selector",
"digest_mismatch",
"nothing_to_apply",
// scaffold stub
"empty_target",
"target_resolves",
"target_ambiguous",
"unknown_source",
// note title resolution
"path_not_found",
"not_found",
"ambiguous",
// note template
"unbalanced_section",
"section_too_deep",
"invalid_variable",
// pinned
"replace_target_missing",
"budget_exceeded",
// exact state
"invalid_aspect",
// host memory write
"invalid_action",
"invalid_target",
"empty_content",
// count guard, as the lifecycle tool reports it
"count_guard",
// the brain_expire refusals, reported under their class names
"ExpirationValueError",
"ExpirationTargetNotFoundError",
"InvalidExpirationTargetError",
] as const;
/** A core-style error class that, like several real ones, never sets `this.name`. */
class Nameless extends Error {}
const UNCLASSIFIED_PREFIX = "warning: unclassified tool error mapped to internal_error: ";
describe("TOOL_ERROR_CODES", () => {
test("registers the no-vault refusal, so it reaches the wire without a warning", () => {
expect(isToolErrorCode("vault_required")).toBe(true);
});
test("is frozen and unique", () => {
expect(Object.isFrozen(TOOL_ERROR_CODES)).toBe(true);
expect(new Set(TOOL_ERROR_CODES).size).toBe(TOOL_ERROR_CODES.length);
});
test("is exactly the imported vocabularies plus the 23 new tokens", () => {
const expected = new Set<string>([
...NEW_TOKENS,
...SEARCH_ERROR_CODES,
...STORAGE_ERROR_CODES,
...Object.values(SHAPE_VIOLATION_CODES),
...Object.values(SEMANTIC_VIOLATION_CODES),
VAULT_FROZEN_REFUSAL,
MIGRATION_IN_PROGRESS_REFUSAL,
WRITE_BINDING_REFUSED_CODE,
VAULT_ADAPTER_REQUIRED_CODE,
VAULT_BINDING_MISMATCH_CODE,
...Object.values(WRITE_REFUSAL_CODES),
PENDING_STAGE_CONFLICT_CODE,
REACH_REFUSAL,
...OWNER_SCOPE_REFUSALS,
...TYPE_ONLY_MEMBERS,
]);
expect([...TOOL_ERROR_CODES].toSorted() as string[]).toEqual([...expected].toSorted());
expect([...GENERIC_TOOL_ERROR_CODES].toSorted()).toEqual([...NEW_TOKENS].toSorted());
expect(Object.values(TOOL_ERROR_CODE).toSorted()).toEqual([...NEW_TOKENS].toSorted());
expect(Object.isFrozen(TOOL_ERROR_CODE)).toBe(true);
});
test("keeps the pinned wire tokens verbatim", () => {
for (const token of ["budget_exceeded", "invalid_action", "invalid_target", "vault_frozen"]) {
expect(isToolErrorCode(token)).toBe(true);
}
});
test("the guards accept members only", () => {
for (const outsider of ["", "ENOENT", "INTERNAL_ERROR", "unclassified", 42, null, undefined]) {
expect(isToolErrorCode(outsider)).toBe(false);
expect(isGenericToolErrorCode(outsider)).toBe(false);
}
expect(isGenericToolErrorCode("INDEX_MISSING")).toBe(false);
expect(isToolErrorCode("INDEX_MISSING")).toBe(true);
});
});
describe("toolErrorMeta", () => {
test("names the schema and the code", () => {
expect(TOOL_ERROR_META_KEY).toBe("open-second-brain/error");
expect(TOOL_ERROR_SCHEMA).toBe("o2b.error.v1");
expect(toolErrorMeta("safeguard_timeout")).toEqual({
schema: "o2b.error.v1",
code: "safeguard_timeout",
});
});
});
describe("defaultCodeForRpc", () => {
test("maps each JSON-RPC constant to its snake token", () => {
expect(defaultCodeForRpc(PARSE_ERROR)).toBe("parse_error");
expect(defaultCodeForRpc(INVALID_REQUEST)).toBe("invalid_request");
expect(defaultCodeForRpc(METHOD_NOT_FOUND)).toBe("method_not_found");
expect(defaultCodeForRpc(INVALID_PARAMS)).toBe("invalid_params");
expect(defaultCodeForRpc(INTERNAL_ERROR)).toBe("internal_error");
});
});
describe("codeForError", () => {
let stderr: Mock<typeof process.stderr.write>;
let lines: string[];
beforeEach(() => {
lines = [];
stderr = spyOn(process.stderr, "write").mockImplementation((chunk) => {
lines.push(String(chunk));
return true;
});
});
afterEach(() => {
stderr.mockRestore();
});
test("returns the code a typed core error carries", () => {
expect(codeForError(new WriteBatchError("invalid_path", 0, "bad path"))).toBe("invalid_path");
expect(codeForError(new SearchError("INDEX_MISSING", "no index"))).toBe("INDEX_MISSING");
expect(codeForError(new PinnedBatchError("budget_exceeded", -1, "too big"))).toBe(
"budget_exceeded",
);
expect(codeForError(new VaultAdapterRequiredError("create note"))).toBe("vault_required");
expect(codeForError(new VaultBindingMismatchError("/v", "detail"))).toBe(
"vault_binding_mismatch",
);
// The same code on purpose: the binding cannot vouch for the vault either way.
expect(codeForError(new VaultBindingsUnreadableError("/state/vault-binding.json"))).toBe(
"vault_binding_mismatch",
);
expect(lines).toEqual([]);
});
test("names the safeguard, config and count-guard errors", () => {
expect(codeForError(new SafeguardTimeoutError("dream", 10))).toBe("safeguard_timeout");
expect(codeForError(new SafeguardAbortError("dream"))).toBe("safeguard_aborted");
expect(codeForError(new ConfigReadError("config.yaml", "EACCES"))).toBe("config_unreadable");
expect(codeForError(new BrainConfigError("bad", "dream.x", "_brain.yaml"))).toBe(
"config_invalid",
);
expect(codeForError(new CountGuardError("mismatch", 2, 1, ["a", "b"]))).toBe("count_guard");
expect(codeForError(new OutputContractError("probe", ["$.ok: expected boolean"]))).toBe(
"output_contract_failed",
);
expect(lines).toEqual([]);
});
test("an expiration refusal keeps its class name as its code", () => {
expect(codeForError(new ExpirationValueError("soon", "bad date"))).toBe("ExpirationValueError");
expect(codeForError(new ExpirationTargetNotFoundError("sig-x", ["Brain/inbox"]))).toBe(
"ExpirationTargetNotFoundError",
);
expect(codeForError(new InvalidExpirationTargetError("x"))).toBe(
"InvalidExpirationTargetError",
);
expect(lines).toEqual([]);
});
test("a Brain artifact parse failure is brain_artifact_unparseable, subclasses included", () => {
const path = "/vault/Brain/retired/ret-broken.md";
expect(codeForError(new BrainParseError("missing retired_at", path))).toBe(
"brain_artifact_unparseable",
);
expect(
codeForError(
new BrainStatusFolderMismatchError(
"status disagrees with folder",
path,
"retired",
"preferences",
),
),
).toBe("brain_artifact_unparseable");
expect(lines).toEqual([]);
});
test("a strict quote refusal is quote_unverified", () => {
const error = new QuoteCheckError([
{ claim: 0, outcome: QUOTE_CHECK_OUTCOME.notInBlock, span: "x" },
]);
expect(codeForError(error)).toBe("quote_unverified");
expect(TOOL_ERROR_CODE.quoteUnverified).toBe(QUOTE_UNVERIFIED_CODE);
expect(lines).toEqual([]);
});
test("walks the cause chain of a rethrown error", () => {
const original = new BrainPreferenceNotFoundError("pref-x", "Brain/preferences/pref-x.md");
const rethrown = new Error(original.message, { cause: original });
expect(codeForError(rethrown)).toBe("preference_not_found");
expect(lines).toEqual([]);
});
test("an unknown error is internal_error, logged once by name only", () => {
const privatePath = "/home/someone/vault/private.md";
const cases: ReadonlyArray<readonly [unknown, string]> = [
[new Error(`boom at ${privatePath}`), "Error"],
[Object.assign(new Error(`ENOENT: ${privatePath}`), { code: "ENOENT" }), "Error"],
[`thrown string ${privatePath}`, "string"],
// A class that never sets `this.name` is still named by its class.
[new Nameless(`boom at ${privatePath}`), "Nameless"],
];
for (const [thrown, name] of cases) {
lines = [];
expect(codeForError(thrown)).toBe("internal_error");
expect(lines).toEqual([`${UNCLASSIFIED_PREFIX}${name}\n`]);
expect(lines[0]).not.toContain(privatePath);
}
});
});