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
20.5 KB
Raw Blame
/**
 * 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;
}