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
23.4 KB
Raw Blame

Stable error codes at the MCP boundary - every tool failure and every rerank skip carries a closed, enumerated code

Status: draft (phase 1 spec review applied) Author: release orchestrator (via feature-release-playbook) Audience: implementation Cards: t_40f13576 (stable machine-readable error codes on every MCP tool error), t_c4b85802 (reranker liveness as a typed degradation code, a doctor check, a rerank sunset table) Base: origin/main a1ecfe7b (v1.65.0), branch feat/mcp-error-codes

Problem statement

Open Second Brain is consumed over MCP by Hermes, Claude Code and Codex, and none of them can branch on a tool failure without matching English prose. The server has two error channels and neither carries a stable code consistently: a thrown MCPError becomes a JSON-RPC error whose data holds a string code at about 12 of 373 throw sites, and every other throw inside tools/call becomes an isError: true result with one text block and nothing else. About 28 core error classes already carry a readonly code, and the boundary throws that code away (search, skills) or never had one (workspace, write session). On the retrieval side, a failed cross-encoder rerank is reported only as the warning string rerank_degraded: <raw provider message>, there is no rerank member in the closed RETRIEVAL_DEGRADATION vocabulary, no rerank doctor check, no rerank decommission survey, and a degraded rerank outcome is written to the query cache so a transient endpoint failure is served again from cache.

Premise verification (live source, a1ecfe7b)

Full evidence: the two recon reports of this wave (premise-t_40f13576.md, premise-t_c4b85802.md). The orchestrator re-checked the anchors it relies on (server.ts:357-371, 463-478, 570-597, progress.ts:173-179, post-rank.ts:170-179, search.ts:280-292, 510-517, rerank/index.ts:140-245, rerank/cross-encoder.ts:110-175, embeddings/sunset.ts:12-545, retrieval-trail.ts:60-180, protocol.ts:15-48).

t_40f13576 - partly false, and the true part is wider than the card

  1. Confirmed: toolError (src/mcp/server.ts:570-575) returns {content, isError: true} with no code; the catch at :463-478 routes every non-MCPError there.
  2. Confirmed: skill and workspace errors carry no code on the wire. SkillError has NOT_FOUND | INVALID_PATH but skill-tools.ts:90 rewraps it as MCPError(INVALID_PARAMS, message); unknown skill (:84) and the workspace refusals (workspace-tools.ts:82, 190, 228, 231) are prose only.
  3. Refuted: "search already does this". SEARCH_ERROR_CODES exists only in the core; searchErrorToMcp (search-tools.ts:863-887) builds an MCPError with no data, except the fallback arm which appends [<CODE>] to the prose. recall-tools.ts:959 drops it too.
  4. Missed by the card: there are two channels (JSON-RPC error and isError result), and the error.data.code convention already exists on the first.
  5. Refuted for this tree: the HTTP 429 leg. The MCP server has no rate-limited endpoint; its non-200 replies are 401/403/405 and a draining 503 (http.ts:251-308).
  6. Refuted as named: the engram invalid_session_id / retry_without_session_id pair. The real counterparts are an unknown write session (write-session/engine.ts:273), a terminal one (:284) and a missing session_id (context-tools.ts:73). No retry-without-session semantic exists, so none is invented.

t_c4b85802 - partly false (validator narrowing holds, with four corrections)

  1. Confirmed: RETRIEVAL_DEGRADATION (retrieval-trail.ts:68-150) has no rerank member; the failure travels only as rerank_degraded: (post-rank.ts:178); no rerank hit in doctor; no rerank sunset table.
  2. Refuted: no_key as a degradation. Enabled with a missing key fails closed by contract (rerank/index.ts:15-19, provider-resolve.ts:85-91, pinned by rerank.search.test.ts:80-84). It belongs to doctor; the orchestrator also put missing-key-as-degradation out of scope.
  3. Refuted: disabled as a degradation. Disabled is the default and must keep a healthy answer trail-free (retrieval-trail.test.ts:85, the "absent, not empty" contract).
  4. Corrected: the trail is not an --explain feature. retrieval_trail appears in --json and MCP brain_search whenever anything degraded (outcome-render.ts:152, search-tools.ts:1167); --explain adds receipts only. The human transcript names a trail code only on an empty window, which rerank cannot produce, so the existing rerank_degraded: warning stays the human signal.
  5. Corrected: the upstream claim behind the survey. ZeroEntropy announced (2026-07-24) that its HOSTED /models/rerank and /models/embed endpoints shut down on 2026-09-04, and that its models are open-weight under Apache 2.0 (source: https://zeroentropy.dev/articles/zeroentropy-is-joining-notion/). That is an endpoint going away, not a model being decommissioned. The survey is keyed on the model string and its header rule (embeddings/sunset.ts:66-75) says a negative or positive is a claim about the MODEL: a self-hosted zerank-* checkpoint keeps answering. Shipping a ZeroEntropy positive would make the sunset skip refuse a live self-hosted endpoint. So ZeroEntropy rows, if any, are open-checkpoint negatives, and the dead hosted endpoint is reported by the liveness code (rerank-provider-unavailable with category gone or network). The one sourced positive found for a model reachable through the Cohere-compatible /rerank shape (cross-encoder.ts:5) is the Cohere rerank-*-v2.0 family, retired 2025-04-30 (source: https://docs.cohere.com/docs/deprecations); the implementer re-reads that page and records only what it states.

Scope

  1. A closed MCP-boundary error registry, src/mcp/tool-error-codes.ts, that imports the existing core vocabularies unchanged and adds snake_case tokens for the uncoded remainder.
  2. Channel B (isError results): result._meta["open-second-brain/error"] = { schema: "o2b.error.v1", code }, text body byte-identical, structuredContent never set.
  3. Channel A (JSON-RPC errors): error.data.code on every error response, the default derived in the single builder errorResponse (server.ts) from the numeric JSON-RPC code, a thrower-supplied code always winning.
  4. withProgressRefusal merges into an existing _meta instead of replacing it.
  5. Per-surface precise codes where the generic default would hide a known class: search (SearchError.code), skills, workspace intention and trigger refusals, write session, argument guard, reach refusal, owner-scope refusal.
  6. Rerank: two RETRIEVAL_DEGRADATION members, rerank-provider-unavailable (detail.category from a closed RERANK_FAILURE_CATEGORY) and rerank-model-sunset (no HTTP call once the announced date has passed); a rerank sunset survey that reuses the generic embedding classifier; a degraded rerank-provider-unavailable outcome is not written to the query cache.
  7. A config-only rerankHealthCheck in doctor, its codes registered in DIAGNOSTIC_SIGNALS or DOCTOR_EXIT_EXCLUSIONS as the census test demands.
  8. Docs: a "Tool errors" section in docs/mcp.md; the trail table in docs/cli-reference.md gains the two rerank rows and the missing hybrid-deadline-exceeded row; the doctor codes are documented.

Out of scope

  1. HTTP 429 and any rate-limit envelope (no rate-limited endpoint exists; a rerank endpoint's own 429 is classified transient, with no retry policy added).
  2. The OpenClaw tool envelope (src/openclaw/index.ts does not use MCPServer; the host owns its error shape).
  3. Missing rerank key, base URL or model as a trail degradation (fail-closed by contract; doctor reports it instead).
  4. Moving any error between channels. The MCP spec prefers isError results for tool errors, but changing channel is a wire-shape change for every client and is not what the cards ask for.
  5. Renaming or re-casing any code already on the wire (kebab, snake and UPPER stay as they are).
  6. Retry hints (retryable, retry_after_ms) on the boundary envelope.
  7. A rerank operator declaration key (search_rerank.sunset_at); the survey alone satisfies the card, and the classifier keeps its declaration parameter for a later release.
  8. The CLI bridge (server.callTool has no envelope; its stderr line stays unchanged).
  9. decision-model and local rerank kinds for the sunset skip (no model string to key on, and the decision-model kind has its own fallback record).

Chosen approach

Variant 1 of the consultant ("boundary interceptor with a namespaced _meta error envelope"), with five orchestrator overrides recorded below. The mapping runs at the two boundary seams in server.ts, so coverage of every tool does not depend on editing 373 throw sites; a small number of surface mappers add the precise code where the seam would otherwise only see a generic class. The rerank work stays inside the existing closed-vocabulary and survey conventions.

Design decisions

  1. Where the code lives on channel B: _meta, key open-second-brain/error. (Orchestrator decision 1.) The MCP SDK 1.30 client validates structuredContent against outputSchema even on isError results, and 16 tools declare one, so an error object there breaks strict clients; _meta passes the loose result schema. The repository already chose a namespaced _meta key for progress for the same reason (progress.ts:53, docs/mcp.md:114-119). Hermes _structured() would misread an error placed in structuredContent. Payload: { schema: "o2b.error.v1", code }, mirroring PROGRESS_SCHEMA = "o2b.progress.v1". The text body stays byte-identical because two tests pin it with toBe and Hermes and agents parse it.
  2. Where the code lives on channel A: error.data.code, defaulted inside errorResponse. (Orchestrator decision 1.) It is the convention 12 sites and vault_frozen already use, and error.data is unknown in every client. The default is derived in errorResponse (server.ts:585), the one builder every JSON-RPC error passes through, including the stdio.ts and http.ts transport errors (parse error, invalid request), so "every error response carries a code" holds by construction. The numeric code parameter is narrowed to a closed JsonRpcErrorCode union of the five constants in protocol.ts:15-19, and the default map is a total Record over it, so no unknown numeric code can reach the builder and no runtime fallback is needed.
  3. MCPError.data is narrowed to Readonly<Record<string, unknown>> | undefined. The seam has to merge a code into data; a non-record data would force either a shape change or a silent skip. A scan of the 373 sites found only record literals or record-typed variables, so the type narrowing is checked by tsc instead of a runtime branch. Merge rule: data absent gives { code }; a record without a string code gets code added after its own members; a record with a string code is left untouched.
  4. One closed registry that imports the core vocabularies unchanged. (Orchestrator decision 2.) TOOL_ERROR_CODE is a frozen object of the new generic tokens; TOOL_ERROR_CODES is the membership list built by spreading the new tokens and every imported vocabulary (SEARCH_ERROR_CODES, SHAPE_VIOLATION_CODES, SEMANTIC_VIOLATION_CODES, VAULT_FROZEN_REFUSAL, WRITE_BINDING_REFUSED_CODE, REACH_REFUSAL, OWNER_SCOPE_REFUSALS, and the type-only vocabularies of write batch, create note, note lifecycle, note revert, scaffold stub, note title resolution, note template, pinned, exact state, host memory write, count guard). For a vocabulary that exists only as a TypeScript union, the registry declares its member array with satisfies ReadonlyArray<X> plus a compile-time exhaustiveness assertion, so the core file stays unchanged and a new core member fails tsc until the registry lists it. Duplicate tokens across vocabularies (for example invalid_path) are de-duplicated; the list is unique. Tests already pin budget_exceeded, invalid_action, invalid_target; nothing is renamed.
  5. New tokens are lower snake_case. That is the majority casing on the wire. The generic set is exactly the members that have a producer in this release: parse_error, invalid_request, method_not_found, invalid_params, internal_error (the five JSON-RPC defaults), 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. config_invalid and preference_not_found are already members of imported vocabularies and are reused, not duplicated; the reach refusal keeps its existing kebab token caller-supplied-reach and the owner-scope refusal its foreign-owner / unresolved-identity tokens, which are already named in their messages.
  6. No generic blank code and no silent fallback. (Orchestrator decision 2.) codeForError(exc) classifies by instanceof over a closed table of known classes, walking Error.cause to a fixed depth (the feedback rethrow at feedback-tools.ts:790-795 keeps the original as cause). A class that carries its own code contributes it only when the guard isToolErrorCode accepts it. Anything else maps to the explicit member internal_error and is logged once per occurrence to stderr as warning: unclassified tool error mapped to internal_error: <error name> (name only, never the message, so no path leaks into logs at remote reach). Structural duck-typing on any .code was rejected: Node fs errors carry ENOENT and would leak an unregistered token.
  7. Skill wire tokens are skill_not_found and skill_invalid_path, not NOT_FOUND / INVALID_PATH. The SkillError codes never reached the wire, so no public contract binds their spelling, and a bare NOT_FOUND in a cross-tool registry is ambiguous. The core SkillError vocabulary stays unchanged; skill-tools.ts maps it through a total Record<SkillErrorCode, ToolErrorCode>.
  8. Search keeps its UPPER codes. SearchError.code is already partly public through the fallback [CODE] suffix, so searchErrorToMcp puts the same token in data.code and the suffix stays as legacy text. search-error-mapping.test.ts:16 pins message with toBe; the message does not change.
  9. Privacy: one code for "absent" and "not visible". brain_trigger makes both byte-identical (workspace-tools.ts:213-222); the whole transition catch carries trigger_transition_refused, so the code does not split them either.
  10. withProgressRefusal merges _meta. (Orchestrator decision 1.) { ...result, _meta: { ...result._meta, [PROGRESS_META_KEY]: refusal } }; with no refusal the result stays untouched (byte-identical to v1.65.0). Success results never gain _meta.
  11. Two rerank degradation members, not one. (Orchestrator decision 3.) The vocabulary names cause in the code (semantic-provider-unavailable + detail.category), the lane prefix rule groups both under rerank-*, and each needs its own sentence in describeRetrievalDegradation. Casing is kebab, like every member of that vocabulary.
  12. RERANK_FAILURE_CATEGORY is a closed vocabulary computed from typed errors, never from message text. Members: auth (401, 403), quota (402), gone (404, 410: the decommissioned-endpoint signal), rejected (any other 4xx), transient (408, 429, 5xx), timeout, network, malformed (non-JSON body, wrong score count, out-of-range or duplicate index), unclassified (a throw the cross-encoder did not type, for example from a provider implementation outside cross-encoder.ts; named, not hidden, and its sentence says so). The cross-encoder throws RerankEndpointError extends SearchError with code RERANK_PROVIDER_HTTP unchanged, status where it has one, and a category; the telemetry event gains a required category on status: "error". Messages stay byte-identical, so the rerank_degraded: warning and rerank.search.test.ts:94 keep their text. The plain Error("expected N scores ...") at rerank/index.ts:226 becomes a RerankEndpointError with category malformed and the same message.
  13. How rerank codes reach the trail. PostRankOutcome gains degraded parallel to warnings, merged into the sink at search.ts:485 like every lane's {warnings, degraded}. PostRankInput gains nowMs, taken from the clock already in search.ts scope, so the sunset decision is injectable in tests.
  14. Rerank sunset survey reuses the embedding classifier. src/core/search/rerank/sunset.ts exports RERANK_SUNSET_SURVEY (typed EmbeddingSunsetSurvey) and classifyRerankSunset(model, nowMs, survey = RERANK_SUNSET_SURVEY), a thin delegate to classifyEmbeddingSunset. The states, sources, undetermined reasons, horizon and staleness asymmetry are one mechanism, so no second four-piece vocabulary is created (DRY, and no new census entries for the sunset). Entries only where a source was read, each with its source string; the module header records why ZeroEntropy is an open-checkpoint negative rather than a positive (premise correction 5). embeddings/sunset.ts is not edited.
  15. Sunset skip semantics. Only the announced state with days_remaining < 0 skips the HTTP call and returns the heuristic order with code rerank-model-sunset (detail empty: the model name is configuration, not an identifier the results carry; the doctor check names it). Every other state calls the endpoint exactly as today. Kinds local and decision-model never consult the survey.
  16. Cache rule. (Orchestrator decision 3.) An outcome whose trail carries rerank-provider-unavailable is served but never cached, mirroring the decisionFallback bypass at search.ts:517, so a transient failure is retried on the next identical query. A rerank-model-sunset outcome is deterministic for the build and the date, and is cached as today.
  17. Doctor check is config-only and registered where the census demands. (Orchestrator decision 3.) src/core/brain/doctor/rerank-health-check.ts, failSoft: true, no network, appended after embeddingsHealthCheck in DOCTOR_CHECKS (doctor.ts:185). It runs only when rerank is enabled with kind openai-compat. Codes: rerank-endpoint-unconfigured (error: missing base URL, model or key, or an unregistered search_rerank_provider name, because every search would throw), rerank-model-sunset-announced (warning, inside a 90-day window and past dates included, mirroring the embedding window constant by import), rerank-model-sunset-unsurveyed and rerank-model-sunset-undetermined (uncertain stream). The two actionable codes go to DIAGNOSTIC_SIGNALS with next commands (o2b search rerank-provider list for unconfigured, o2b search rerank-provider add for an announced sunset, since the act is choosing another endpoint or model); the two uncertain codes go to DOCTOR_EXIT_EXCLUSIONS with a reason, as the embedding precedent does (doctor-exits.ts:219-235).
  18. Codes are fixed tokens. visibility-matrix.test.ts sweeps the serialized response including _meta; no code is ever interpolated with a path or a name.
  19. Docs over descriptions. Codes are documented in docs/mcp.md and docs/cli-reference.md, not in tool descriptions, because registry-guard.ts:51-52 caps descriptions; no inputSchema or description changes, so plugins/hermes/_schemas.py needs no regeneration.

Orchestrator overrides of the consultant's Variant 1

  1. Unclassified errors map to internal_error and are logged, not to a new unclassified member: the five JSON-RPC defaults already give internal_error the exact meaning, and a second member would be a blank code by another name.
  2. Classification is by instanceof over a closed table, not by reading any .code structurally (fs ENOENT would leak).
  3. Two rerank codes in kebab case instead of one snake rerank_skipped, matching the vocabulary's casing and cause-in-name precedent.
  4. No surface member in the _meta payload: the tool name is already the request's own, and a second field could drift.
  5. The rerank code is not claimed to appear in search --explain; it appears in --json and MCP brain_search (premise correction 4).

File changes

Lane split and per-file ownership are in plan.md ("File ownership").

New:

  • src/mcp/tool-error-codes.ts (registry, guard, codeForError, defaultCodeForRpc, TOOL_ERROR_META_KEY, TOOL_ERROR_SCHEMA, toolErrorMeta)
  • src/core/search/rerank/failure.ts (RERANK_FAILURE_CATEGORY, list, guard, RerankEndpointError, rerankCategoryForStatus)
  • src/core/search/rerank/sunset.ts (RERANK_SUNSET_SURVEY, classifyRerankSunset)
  • src/core/brain/doctor/rerank-health-check.ts
  • tests: tests/mcp/tool-error-codes.test.ts, tests/mcp/tool-error-envelope.test.ts, tests/mcp/surface-error-codes.test.ts, tests/core/search/rerank-failure.test.ts, tests/core/search/rerank-sunset.test.ts, tests/core/brain/doctor/rerank-health-check.test.ts, helper tests/helpers/tool-error-envelope.ts

Modified:

  • src/mcp/protocol.ts, src/mcp/server.ts, src/mcp/progress.ts, src/mcp/output-contract.ts
  • src/mcp/search-tools.ts, src/mcp/brain/recall-tools.ts, src/mcp/skill-tools.ts, src/mcp/brain/workspace-tools.ts, src/mcp/brain/context-tools.ts, src/core/brain/write-session/engine.ts, src/mcp/argument-guard.ts, src/mcp/reach-refusal.ts, src/mcp/coerce.ts (owner-scope refusal site only)
  • src/core/search/retrieval-trail.ts, src/core/search/rerank/index.ts, src/core/search/rerank/cross-encoder.ts, src/core/search/pipeline/post-rank.ts, src/core/search/search.ts
  • src/core/brain/doctor.ts, src/core/brain/diagnostics.ts, src/core/brain/doctor-exits.ts
  • tests: tests/mcp/mcp.test.ts, tests/mcp/progress-token.test.ts, tests/mcp/search-error-mapping.test.ts, tests/core/search/retrieval-trail.test.ts, tests/core/search/rerank.search.test.ts, tests/core/search/rerank.test.ts, tests/core/architecture/verdict-vocabulary-census.test.ts
  • docs: docs/mcp.md, docs/cli-reference.md, docs/how-it-works.md
  • release (phase 5, in osb-pr-prepare, not in this plan): CHANGELOG.md, package.json minor bump to 1.66.0 plus scripts/sync-version.ts

Risks and open questions

  1. tsc may flag an MCPError site whose data is typed wider than a record once data is narrowed. Mitigation: lane A runs tsc right after narrowing; a flagged site in a lane-B file is fixed by lane B, a flagged site in a file no lane owns is fixed by lane A and added to its ownership in its report (the only edit is the type at the throw). The 373-site scan found no such site.
  2. The _meta merge changes a v1.65.0 behaviour (replace becomes merge). Only an error result with a progress token over HTTP is affected; a test pins both keys present.
  3. The census scan under src/core/brain/doctor/ may require the four doctor codes as code: "..." literals or const *_CODE constants; the check follows the embedding check's spelling so the scan finds them.
  4. The Cohere deprecation page may have changed since 2025; the implementer records only what the page states on the day it is read, and bumps reviewedAt to that day. If the page cannot be read, the survey ships with the ZeroEntropy negatives only (sourced) and rerank-model-sunset is exercised by injected surveys in tests; the producer still exists on the path.
  5. Hermes reads channel B _meta through its whole-result serialization; no Python change is expected. The Python suite runs in phase 4 to confirm.
  6. A new tool added later with a new error class is classified internal_error until it is registered. That is visible (logged by name) rather than silent, which is the intent.