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 registry of error codes the MCP boundary answers with.
*
* Open Second Brain answers a failed tool call on one of two channels: a
* JSON-RPC error (`error.data.code`) or an `isError` result
* (`_meta["open-second-brain/error"].code`). Both carry one member of
* {@link TOOL_ERROR_CODES}, so a client branches on a token instead of
* matching English prose.
*
* The registry does not rename anything already on the wire. It imports
* the core vocabularies verbatim - kebab, snake and UPPER spellings stay
* as their owners chose them - and adds lower snake_case tokens
* ({@link TOOL_ERROR_CODE}) only for the failures that had no code at all.
*
* Core vocabularies that exist only as a TypeScript union are listed here
* through {@link exhaustiveMembers}, which fails `tsc` both when an entry
* is not a member of the union and when a union member is missing, so a
* code added in the core cannot reach the wire unregistered.
*
* {@link codeForError} classifies a thrown value by `instanceof` over a
* closed table and never reads a `.code` structurally: a Node fs error
* carries `ENOENT`, which is no member of this registry. Anything the
* table does not know is the explicit {@link TOOL_ERROR_CODE.internalError}
* and is named on stderr by its class name only, never by its message, so
* no vault path reaches a log at remote reach.
*/
import { BrainPreferenceNotFoundError } from "../core/brain/apply-evidence.ts";
import { CountGuardError } from "../core/brain/count-guard.ts";
import { QuoteCheckError } from "../core/brain/distill/quote-verdict.ts";
import type { ExactStateErrorCode } from "../core/brain/exact-state.ts";
import { ExactStateError } from "../core/brain/exact-state.ts";
import {
EXPIRATION_REFUSAL_CODE,
EXPIRATION_REFUSAL_CODES,
ExpirationTargetNotFoundError,
ExpirationValueError,
InvalidExpirationTargetError,
} from "../core/brain/expiration-set.ts";
import { VaultFrozenError } from "../core/brain/freeze-marker.ts";
import { MigrationInProgressError } from "../core/migration-gate.ts";
import type { HostMemoryWriteErrorCode } from "../core/brain/host-memory-write.ts";
import { HostMemoryWriteError } from "../core/brain/host-memory-write.ts";
import type { CreateNoteErrorCode } from "../core/brain/notes/create-note.ts";
import { CreateNoteError } from "../core/brain/notes/create-note.ts";
import type { NoteLifecycleErrorCode } from "../core/brain/notes/lifecycle.ts";
import { NoteLifecycleError } from "../core/brain/notes/lifecycle.ts";
import type { NoteTemplateErrorCode } from "../core/brain/notes/note-template.ts";
import { NoteTemplateError } from "../core/brain/notes/note-template.ts";
import type { NoteTitleResolutionErrorCode } from "../core/brain/notes/note-title-resolver.ts";
import { NoteTitleResolutionError } from "../core/brain/notes/note-title-resolver.ts";
import { NOTE_REVERT_ERROR, NoteRevertError } from "../core/brain/notes/revert.ts";
import type { ScaffoldStubErrorCode } from "../core/brain/notes/scaffold-stub.ts";
import { ScaffoldStubError } from "../core/brain/notes/scaffold-stub.ts";
import { BrainParseError } from "../core/brain/parse-error.ts";
import type { PinnedBatchErrorCode } from "../core/brain/pinned.ts";
import { PinnedBatchError } from "../core/brain/pinned.ts";
import { BrainConfigError } from "../core/brain/policy/errors.ts";
import {
BrainSettingError,
type BrainSettingErrorCode,
} from "../core/brain/policy/settings-write.ts";
import { ResponseCheckError, SEMANTIC_VIOLATION_CODES } from "../core/brain/response-checks.ts";
import { ResponseShapeError, SHAPE_VIOLATION_CODES } from "../core/brain/response-shape.ts";
import { SafeguardAbortError, SafeguardTimeoutError } from "../core/brain/safeguard.ts";
import type { StorageErrorCode } from "../core/brain/storage/capacity-error.ts";
import { StorageCapacityError } from "../core/brain/storage/capacity-error.ts";
import type { WriteBatchErrorCode } from "../core/brain/write-batch.ts";
import { WriteBatchError } from "../core/brain/write-batch.ts";
import { ConfigReadError } from "../core/config.ts";
import { SEARCH_ERROR_CODES, SearchError } from "../core/search/search-error.ts";
import { StoreWriteError, type StoreWriteFailure } from "../core/store/store-write.ts";
import { WRITE_BINDING_REFUSED_CODE } from "../core/write-binding/index.ts";
import {
VAULT_ADAPTER_REQUIRED_CODE,
VAULT_BINDING_MISMATCH_CODE,
VaultAdapterRequiredError,
VaultBindingMismatchError,
VaultBindingsUnreadableError,
} from "../core/vault-adapter/index.ts";
import {
WRITE_REFUSAL_CODES,
PENDING_STAGE_CONFLICT_CODE,
} from "../core/brain/pending/pending-lanes.ts";
import { MIGRATION_IN_PROGRESS_REFUSAL, VAULT_FROZEN_REFUSAL } from "./frozen-refusal.ts";
import { OWNER_SCOPE_REFUSALS } from "./owner-scope-refusal.ts";
import {
INTERNAL_ERROR,
INVALID_PARAMS,
INVALID_REQUEST,
type JsonRpcErrorCode,
METHOD_NOT_FOUND,
PARSE_ERROR,
} from "./protocol.ts";
import { OutputContractError } from "./output-contract.ts";
import { REACH_REFUSAL } from "./reach-refusal.ts";
/** The `_meta` key an `isError` result carries its code under. */
export const TOOL_ERROR_META_KEY = "open-second-brain/error";
/** Payload schema tag, versioned like `o2b.progress.v1`. */
export const TOOL_ERROR_SCHEMA = "o2b.error.v1";
/**
* The generic tokens this registry adds: one per failure that reaches the
* boundary with no code of its own. Each has a producer in this release.
*/
export const TOOL_ERROR_CODE = Object.freeze({
/** The five JSON-RPC defaults, one per {@link JsonRpcErrorCode}. */
parseError: "parse_error",
invalidRequest: "invalid_request",
methodNotFound: "method_not_found",
invalidParams: "invalid_params",
/** A throw the classifier does not know; logged by name on stderr. */
internalError: "internal_error",
/** A safeguard deadline aborted the operation at a checkpoint. */
safeguardTimeout: "safeguard_timeout",
/** The operation's abort signal fired on demand. */
safeguardAborted: "safeguard_aborted",
/** A tool's result did not match its declared output schema. */
outputContractFailed: "output_contract_failed",
/** The plugin config file exists and could not be read. */
configUnreadable: "config_unreadable",
/** A `SkillError` of kind `NOT_FOUND`. */
skillNotFound: "skill_not_found",
/** A `SkillError` of kind `INVALID_PATH`. */
skillInvalidPath: "skill_invalid_path",
/** A skill name the registry does not hold. */
unknownSkill: "unknown_skill",
/** An `operation` argument outside the tool's closed set. */
unknownOperation: "unknown_operation",
/** A `status` argument outside the tool's closed set. */
invalidStatus: "invalid_status",
/** A trigger transition refused; absent and not-visible share it. */
triggerTransitionRefused: "trigger_transition_refused",
/** A `session_id` that names no write session. */
writeSessionUnknown: "write_session_unknown",
/** A write session that is already committed or aborted. */
writeSessionTerminal: "write_session_terminal",
/** An operation that needs a write session was sent without one. */
sessionIdRequired: "session_id_required",
/** An argument the tool's input schema does not declare. */
unknownArgument: "unknown_argument",
/** A Brain artifact file could not be parsed (`BrainParseError`). */
brainArtifactUnparseable: "brain_artifact_unparseable",
/** An argument that belongs to another action of the same tool. */
argumentForbidden: "argument_forbidden",
/** A strict distillation refused a quoted span it could not verify. */
quoteUnverified: "quote_unverified",
/**
* A store-only write did not land (`StoreWriteError`, design D14 item
* 1); the payload names its reason and remedy ({@link ToolErrorDetail}).
*/
storeWriteFailed: "store_write_failed",
} as const);
/** Closed union over {@link TOOL_ERROR_CODE}. */
export type GenericToolErrorCode = (typeof TOOL_ERROR_CODE)[keyof typeof TOOL_ERROR_CODE];
/** Membership list of the generic tokens alone. */
export const GENERIC_TOOL_ERROR_CODES: ReadonlyArray<GenericToolErrorCode> = Object.freeze(
Object.values(TOOL_ERROR_CODE),
);
const GENERIC_TOOL_ERROR_CODE_SET: ReadonlySet<string> = new Set(GENERIC_TOOL_ERROR_CODES);
/** Narrow a value to one of the generic tokens this registry adds. */
export function isGenericToolErrorCode(value: unknown): value is GenericToolErrorCode {
return typeof value === "string" && GENERIC_TOOL_ERROR_CODE_SET.has(value);
}
/**
* The members `Union` lacks from `List`, or `never` when `List` names them
* all. A non-`never` result is what makes {@link exhaustiveMembers} fail.
*/
type MissingMembers<Union, List extends ReadonlyArray<Union>> = Exclude<Union, List[number]>;
/**
* Freeze the member list of a type-only core vocabulary, checked by `tsc`
* in both directions: an entry outside `Union` is rejected by the element
* type, and a member of `Union` absent from the list turns the argument
* type into an object naming it, which no array literal satisfies.
*/
function exhaustiveMembers<Union extends string>() {
return <const List extends ReadonlyArray<Union>>(
list: List &
([MissingMembers<Union, List>] extends [never]
? unknown
: { readonly missingMembers: MissingMembers<Union, List> }),
): List => Object.freeze([...list]) as unknown as List;
}
const WRITE_BATCH_CODES = exhaustiveMembers<WriteBatchErrorCode>()([
"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",
]);
const CREATE_NOTE_CODES = exhaustiveMembers<CreateNoteErrorCode>()([
"invalid_path",
"excluded",
"exists",
"outside_vault",
"invalid_document",
"invalid_template",
"write_binding",
"config_invalid",
"owner_write_refused",
]);
const NOTE_LIFECYCLE_CODES = exhaustiveMembers<NoteLifecycleErrorCode>()([
"source_missing",
"destination_required",
"destination_forbidden",
"destination_occupied",
"destination_unchanged",
"destination_inside_source",
"move_set_empty",
"wrong_action",
"not_confirmed",
"already_archived",
"cascade_forbidden",
]);
const SCAFFOLD_STUB_CODES = exhaustiveMembers<ScaffoldStubErrorCode>()([
"empty_target",
"target_resolves",
"target_ambiguous",
"unknown_source",
]);
const NOTE_TITLE_RESOLUTION_CODES = exhaustiveMembers<NoteTitleResolutionErrorCode>()([
"empty_target",
"path_not_found",
"not_found",
"ambiguous",
]);
const NOTE_TEMPLATE_CODES = exhaustiveMembers<NoteTemplateErrorCode>()([
"unbalanced_section",
"section_too_deep",
"invalid_variable",
]);
const PINNED_BATCH_CODES = exhaustiveMembers<PinnedBatchErrorCode>()([
"invalid_operation",
"replace_target_missing",
"budget_exceeded",
]);
const BRAIN_SETTING_CODES = exhaustiveMembers<BrainSettingErrorCode>()([
"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",
]);
const EXACT_STATE_CODES = exhaustiveMembers<ExactStateErrorCode>()([
"budget_exceeded",
"invalid_aspect",
]);
const HOST_MEMORY_WRITE_CODES = exhaustiveMembers<HostMemoryWriteErrorCode>()([
"invalid_action",
"invalid_target",
"empty_content",
]);
/**
* The storage-capacity vocabulary. The leaf owns the canonical member
* list as `STORAGE_ERROR_CODES`; the literals are spelled out here so
* `exhaustiveMembers` fails `tsc` the moment the leaf grows a code this
* table has not answered for - the same two-direction check every other
* imported union gets.
*/
const STORAGE_CAPACITY_CODES = exhaustiveMembers<StorageErrorCode>()([
"capacity_unmeasurable",
"capacity_exhausted",
]);
/**
* The leaf vocabulary, re-exported under the one name consumers of the
* wire vocabulary already import from here. The canonical home stays in
* the leaf; this only spares callers a second import path.
*/
export { STORAGE_ERROR_CODES } from "../core/brain/storage/capacity-error.ts";
/**
* The token a count-guard refusal is reported under on the wire. The core
* `CountGuardError` carries `COUNT_GUARD`; `brain_note_lifecycle` has
* always answered it as this lower-case token, and this registry keeps the
* wire spelling rather than the class field. `brain_note_lifecycle` imports
* it, so the spelling has one definition.
*/
export const COUNT_GUARD_WIRE_CODE = "count_guard";
/**
* Every code the MCP boundary may answer with: the generic tokens plus
* each imported vocabulary, de-duplicated (several core vocabularies share
* a token such as `invalid_path`, and it means the same thing in each).
*/
export const TOOL_ERROR_CODES = Object.freeze([
...new Set([
...GENERIC_TOOL_ERROR_CODES,
...SEARCH_ERROR_CODES,
...Object.values(SHAPE_VIOLATION_CODES),
...Object.values(SEMANTIC_VIOLATION_CODES),
VAULT_FROZEN_REFUSAL,
MIGRATION_IN_PROGRESS_REFUSAL,
WRITE_BINDING_REFUSED_CODE,
// The vault adapter's refusals: no vault for a note feature, and a
// note write to a vault that is not the one bound to the store.
VAULT_ADAPTER_REQUIRED_CODE,
VAULT_BINDING_MISMATCH_CODE,
...Object.values(WRITE_REFUSAL_CODES),
// A write retried while its first run is still staged: the queue's
// own refusal code, carried by `PendingStageConflictError` beside the
// `WriteRefusedError` handlers that answer it.
PENDING_STAGE_CONFLICT_CODE,
REACH_REFUSAL,
...OWNER_SCOPE_REFUSALS,
...WRITE_BATCH_CODES,
...CREATE_NOTE_CODES,
...NOTE_LIFECYCLE_CODES,
...Object.values(NOTE_REVERT_ERROR),
...SCAFFOLD_STUB_CODES,
...NOTE_TITLE_RESOLUTION_CODES,
...NOTE_TEMPLATE_CODES,
...PINNED_BATCH_CODES,
...BRAIN_SETTING_CODES,
...EXACT_STATE_CODES,
...HOST_MEMORY_WRITE_CODES,
...STORAGE_CAPACITY_CODES,
COUNT_GUARD_WIRE_CODE,
...EXPIRATION_REFUSAL_CODES,
] as const),
]);
/** Closed union over {@link TOOL_ERROR_CODES}. */
export type ToolErrorCode = (typeof TOOL_ERROR_CODES)[number];
const TOOL_ERROR_CODE_SET: ReadonlySet<string> = new Set(TOOL_ERROR_CODES);
/** Narrow a value read back off the wire to a registered code. */
export function isToolErrorCode(value: unknown): value is ToolErrorCode {
return typeof value === "string" && TOOL_ERROR_CODE_SET.has(value);
}
/**
* What a failure carries beside its code, for the failures whose class
* names a machine-readable reason and the remedy for it: today a
* store-only write that did not land (`store_write_failed`).
*/
export interface ToolErrorDetail {
readonly reason: StoreWriteFailure;
readonly remedy: string;
}
/** The `_meta` payload an `isError` result carries. */
export interface ToolErrorMeta extends Partial<ToolErrorDetail> {
readonly schema: typeof TOOL_ERROR_SCHEMA;
readonly code: ToolErrorCode;
}
/** Build the `_meta["open-second-brain/error"]` payload for `code`. */
export function toolErrorMeta(code: ToolErrorCode, detail?: ToolErrorDetail): ToolErrorMeta {
return detail === undefined
? { schema: TOOL_ERROR_SCHEMA, code }
: { schema: TOOL_ERROR_SCHEMA, code, reason: detail.reason, remedy: detail.remedy };
}
/**
* The reason and remedy of a thrown value, walking `cause` like
* {@link codeForError}; `undefined` for a failure that carries none. The
* remedy is fixed prose per reason (`store/store-write.ts`) and names no
* path, so it is safe at every reach.
*/
export function errorDetailFor(exc: unknown): ToolErrorDetail | undefined {
let current: unknown = exc;
for (let depth = 0; depth <= MAX_CAUSE_DEPTH && current !== undefined; depth += 1) {
if (current instanceof StoreWriteError) {
return { reason: current.reason, remedy: current.remedy };
}
current = current instanceof Error ? current.cause : undefined;
}
return undefined;
}
/** Total map from each JSON-RPC error code to its string default. */
const RPC_DEFAULT_CODE: Readonly<Record<JsonRpcErrorCode, GenericToolErrorCode>> = Object.freeze({
[PARSE_ERROR]: TOOL_ERROR_CODE.parseError,
[INVALID_REQUEST]: TOOL_ERROR_CODE.invalidRequest,
[METHOD_NOT_FOUND]: TOOL_ERROR_CODE.methodNotFound,
[INVALID_PARAMS]: TOOL_ERROR_CODE.invalidParams,
[INTERNAL_ERROR]: TOOL_ERROR_CODE.internalError,
});
/** The code a JSON-RPC error carries when its thrower named none. */
export function defaultCodeForRpc(code: JsonRpcErrorCode): ToolErrorCode {
return RPC_DEFAULT_CODE[code];
}
/** A class constructor, matched by `instanceof`. */
type ErrorClass<E extends Error> = abstract new (...args: never[]) => E;
/** How one known class is classified: a fixed code, or the code it carries. */
interface ClassificationRule {
readonly matches: (exc: unknown) => boolean;
readonly code: (exc: Error) => string;
}
function fixed<E extends Error>(ctor: ErrorClass<E>, code: ToolErrorCode): ClassificationRule {
return { matches: (exc) => exc instanceof ctor, code: () => code };
}
function carried<E extends Error & { readonly code: string }>(
ctor: ErrorClass<E>,
): ClassificationRule {
return { matches: (exc) => exc instanceof ctor, code: (exc) => (exc as E).code };
}
/**
* The closed classification table. A carried code still has to pass
* {@link isToolErrorCode} before it reaches the wire.
*/
const CLASSIFICATION: ReadonlyArray<ClassificationRule> = Object.freeze([
carried(WriteBatchError),
carried(CreateNoteError),
carried(NoteLifecycleError),
carried(NoteRevertError),
carried(ScaffoldStubError),
carried(NoteTitleResolutionError),
carried(NoteTemplateError),
carried(PinnedBatchError),
carried(BrainSettingError),
carried(ExactStateError),
carried(HostMemoryWriteError),
carried(StorageCapacityError),
carried(SearchError),
carried(ResponseShapeError),
carried(ResponseCheckError),
carried(VaultAdapterRequiredError),
carried(VaultBindingMismatchError),
// Carries the mismatch's code on purpose (see its class): the message
// tells a damaged binding file from a swapped vault.
carried(VaultBindingsUnreadableError),
fixed(CountGuardError, COUNT_GUARD_WIRE_CODE),
fixed(VaultFrozenError, VAULT_FROZEN_REFUSAL),
fixed(MigrationInProgressError, MIGRATION_IN_PROGRESS_REFUSAL),
fixed(SafeguardTimeoutError, TOOL_ERROR_CODE.safeguardTimeout),
fixed(SafeguardAbortError, TOOL_ERROR_CODE.safeguardAborted),
fixed(ConfigReadError, TOOL_ERROR_CODE.configUnreadable),
fixed(OutputContractError, TOOL_ERROR_CODE.outputContractFailed),
fixed(BrainConfigError, "config_invalid"),
fixed(BrainPreferenceNotFoundError, "preference_not_found"),
fixed(BrainParseError, TOOL_ERROR_CODE.brainArtifactUnparseable),
fixed(ExpirationValueError, EXPIRATION_REFUSAL_CODE.invalidValue),
fixed(ExpirationTargetNotFoundError, EXPIRATION_REFUSAL_CODE.targetNotFound),
fixed(InvalidExpirationTargetError, EXPIRATION_REFUSAL_CODE.invalidTarget),
fixed(QuoteCheckError, TOOL_ERROR_CODE.quoteUnverified),
fixed(StoreWriteError, TOOL_ERROR_CODE.storeWriteFailed),
]);
/**
* How many `cause` links the classifier follows. A tool that rethrows a
* typed error as a plain one keeps the original as `cause` (the feedback
* rethrow does); a bounded walk also stops a cyclic chain.
*/
const MAX_CAUSE_DEPTH = 4;
const UNCLASSIFIED_WARNING = "warning: unclassified tool error mapped to internal_error: ";
function classifyOne(exc: unknown): ToolErrorCode | undefined {
if (!(exc instanceof Error)) return undefined;
for (const rule of CLASSIFICATION) {
if (!rule.matches(exc)) continue;
const code = rule.code(exc);
return isToolErrorCode(code) ? code : undefined;
}
return undefined;
}
/**
* The name an unclassified throw is logged under; never its message. The
* constructor's name comes first because several core error classes never
* set `this.name`, and would all be logged as `Error`.
*/
function unclassifiedName(exc: unknown): string {
return exc instanceof Error ? exc.constructor?.name || exc.name : typeof exc;
}
/**
* The registered code for a thrown value. Walks `cause` up to
* {@link MAX_CAUSE_DEPTH} links; a throw no rule classifies is
* `internal_error`, and one stderr line names its class.
*/
export function codeForError(exc: unknown): ToolErrorCode {
let current: unknown = exc;
for (let depth = 0; depth <= MAX_CAUSE_DEPTH && current !== undefined; depth += 1) {
const code = classifyOne(current);
if (code !== undefined) return code;
current = current instanceof Error ? current.cause : undefined;
}
process.stderr.write(`${UNCLASSIFIED_WARNING}${unclassifiedName(exc)}\n`);
return TOOL_ERROR_CODE.internalError;
}