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
/**
* MCP server: JSON-RPC 2.0 dispatcher exposing the five Open Second Brain
* tools over the `2025-06-18` MCP protocol. Mirrors the Python `MCPServer`
* class, including handshake instructions and error semantics.
*/
import {
ConfigReadError,
resolveAgentName,
resolveMcpRouteMetricsEnabled,
} from "../core/config.ts";
import { emitMcpRouteLatency, type McpRouteStatus } from "../core/brain/mcp-route-metrics.ts";
import { createRouteScope } from "../core/route-scope.ts";
import { assertKnownArguments } from "./argument-guard.ts";
import { VaultFrozenError } from "../core/brain/freeze-marker.ts";
import { MigrationInProgressError } from "../core/migration-gate.ts";
import {
migrationInProgressRefusal,
UNRESOLVED_AGENT,
vaultFrozenRefusal,
} from "./frozen-refusal.ts";
import { assertNoCallerSuppliedReach } from "./reach-refusal.ts";
import { withPrivateWithheld } from "../core/store/caller-reach.ts";
import { buildInstructions } from "./instructions.ts";
import {
INTERNAL_ERROR,
INVALID_PARAMS,
INVALID_REQUEST,
JSONRPC_VERSION,
MCPError,
METHOD_NOT_FOUND,
PROTOCOL_VERSION,
SERVER_NAME,
SERVER_VERSION,
} from "./protocol.ts";
import type { JsonRpcErrorCode, JsonRpcNotification, MCPErrorData } from "./protocol.ts";
import {
codeForError,
errorDetailFor,
isToolErrorCode,
defaultCodeForRpc,
TOOL_ERROR_META_KEY,
toolErrorMeta,
type ToolErrorCode,
type ToolErrorDetail,
} from "./tool-error-codes.ts";
import {
META_MEMBER,
PROGRESS_META_KEY,
progressRefusal,
progressSink,
readProgressToken,
withProgressRefusal,
type ProgressRefusal,
} from "./progress.ts";
import { PROGRESS_REASON, type ProgressSink } from "../core/brain/progress.ts";
import { listResources, listResourceTemplates, readResource } from "./resources.ts";
import { buildToolTable, findTool } from "./tools.ts";
import {
VAULT_REQUIRED_CODE,
vaultRequiredToolMessage,
type RequestIdentity,
type RuleScopeSources,
type ServerContext,
type ToolCapabilityReport,
type ToolDefinition,
type ToolScope,
} from "./tool-contract.ts";
import { noVaultRoot } from "../core/platform-dirs.ts";
import { assertOutputContract } from "./output-contract.ts";
import { ArtifactStore } from "./artifact-store.ts";
import { applyPreviewBudget } from "./preview-budget.ts";
import { evaluateToolCapabilities, type RuntimeCapabilityWindow } from "./capabilities.ts";
import { pathsForCaller } from "./brain/device-path.ts";
import { redactErrorForCaller } from "./error-redaction.ts";
import { resolvedSecretLiterals } from "../core/secret-resolver.ts";
import type { InstallTargetId } from "../core/runtime/host-facts.ts";
import type { HarnessId } from "../core/brain/scoped-rules.ts";
import { resolveHarnessScope } from "../core/brain/scope-identity.ts";
import {
resolvedTransportReach,
TRANSPORT_REACH,
type TransportReach,
} from "../core/graph/transport-reach.ts";
/** TTL after which a prior process's artifact run directory is pruned. */
const ARTIFACT_TTL_MS = 24 * 60 * 60 * 1000;
export interface MCPServerOptions {
/** The vault served, or `null` for a server with no vault (design D14). */
readonly vault: string | null;
readonly configPath?: string | null;
readonly repoRoot?: string | null;
}
export interface MCPServerRuntimeOptions {
readonly serverName?: string;
readonly scope?: ToolScope;
readonly capabilityWindow?: RuntimeCapabilityWindow;
/**
* The runtime that launched this process, from `o2b mcp
* --host-target` in a generated registration. Only the capability
* report reads it, and only to name the host's published tool
* ceiling; absent means the ceiling is reported as unchecked.
*/
readonly hostTarget?: InstallTargetId;
/**
* The harness that launched this process, from `o2b mcp --harness` in a
* packaged registration. Only the scoped standing rules read it, to pick
* `Brain/standing-rules/harness/<id>.md`; absent falls back to
* {@link hostTarget}, since every install target is a harness.
*/
readonly harness?: HarnessId;
/**
* The working directory this process was launched in, captured once by
* the CLI. The scoped standing rules resolve the project from the
* nearest vault pointer above it; absent means no project.
*/
readonly workspaceDir?: string;
/**
* Run id grouping this process's preview artifacts under
* `Brain/.artifacts/<run-id>/`. Defaults to a per-process id;
* injectable so tests get a deterministic directory.
*/
readonly artifactRunId?: string;
/**
* How this transport writes a frame nobody asked for.
*
* Supplied by stdio, which owns a duplex newline-delimited stream and
* can interleave notifications with responses. NOT supplied by the
* HTTP transport, which answers one request with one response and
* closes it - and its absence is what makes a `tools/call` carrying a
* progress token refuse by name there instead of accepting the token
* and dropping the events.
*
* Synchronous, because the progress sink it feeds is: the long
* operations that emit are synchronous functions and cannot await a
* write inside their own loops.
*/
readonly sendNotification?: (notification: JsonRpcNotification) => void;
/**
* The reach this transport establishes for every caller it accepts
* (`src/core/graph/transport-reach.ts`).
*
* Absent means no transport minted one - an embedded caller, a probe,
* a test - and that resolves to {@link TRANSPORT_REACH.remote}, the
* narrowest. A transport that owns the fact sets it AFTER spreading a
* caller's options, exactly as `sendNotification` is set, so a runtime
* option cannot override what the transport established.
*/
readonly reach?: TransportReach;
}
export interface JsonRpcRequest {
readonly jsonrpc?: string;
readonly id?: unknown;
readonly method?: unknown;
readonly params?: unknown;
}
export interface JsonRpcResponse {
readonly jsonrpc: string;
readonly id: unknown;
readonly result?: unknown;
readonly error?: JsonRpcErrorBody;
}
/**
* The per-request identity a transport resolved from a credential
* (write-side-trust, Task 7). Declared on the tool-contract leaf beside
* {@link ServerContext.requestIdentity} - the context carries it and
* every writer tool reads it there - and re-exported here so the
* transport-facing spelling does not move.
*/
export type { RequestIdentity };
/**
* The `error` member of a JSON-RPC answer. `data` is always present and
* always carries the string code, because {@link errorResponse} is the
* one builder and adds it when the thrower did not.
*/
export interface JsonRpcErrorBody {
readonly code: JsonRpcErrorCode;
readonly message: string;
readonly data: JsonRpcErrorData;
}
/** `error.data`: the thrower's record plus the stable string code. */
export type JsonRpcErrorData = MCPErrorData & { readonly code: string };
/** The refusal a vault-adapter tool gives on a server with no vault. */
function vaultRequired(tool: string | undefined): MCPError {
return new MCPError(INVALID_PARAMS, vaultRequiredToolMessage(tool), {
code: VAULT_REQUIRED_CODE,
});
}
export class MCPServer {
readonly vault: string | null;
readonly configPath: string | null;
readonly repoRoot: string | null;
readonly tools: ReadonlyArray<ToolDefinition>;
private readonly serverName: string;
private readonly scope: ToolScope;
private readonly artifactStore: ArtifactStore;
private readonly capabilityReport: ToolCapabilityReport;
/**
* Route-level latency metrics gate (config `mcp_route_metrics_enabled`),
* resolved once at construction by {@link routeMetricsGate}. Off by
* default; when on, every tool call is timed and a payload-safe
* `mcp_route_latency` continuity record is emitted (fail-open).
*/
private readonly routeMetricsEnabled: boolean;
/** See {@link MCPServerRuntimeOptions.sendNotification}. */
private readonly sendNotification: ((notification: JsonRpcNotification) => void) | undefined;
/** See {@link MCPServerRuntimeOptions.reach}; fail-closed when unminted. */
readonly reach: TransportReach;
/** Launch-time scope sources for the scoped standing rules. */
private readonly ruleScope: RuleScopeSources;
constructor(opts: MCPServerOptions, runtimeOpts: MCPServerRuntimeOptions = {}) {
this.vault = opts.vault;
this.configPath = opts.configPath ?? null;
this.repoRoot = opts.repoRoot ?? null;
this.serverName = runtimeOpts.serverName ?? SERVER_NAME;
this.scope = runtimeOpts.scope ?? "full";
const evaluated = evaluateToolCapabilities(buildToolTable(this.scope), {
scope: this.scope,
serverName: this.serverName,
window: runtimeOpts.capabilityWindow,
hostTarget: runtimeOpts.hostTarget,
});
this.tools = evaluated.tools;
this.capabilityReport = evaluated.report;
this.routeMetricsEnabled = routeMetricsGate(this.configPath ?? undefined);
this.sendNotification = runtimeOpts.sendNotification;
this.reach = resolvedTransportReach(runtimeOpts.reach);
this.ruleScope = Object.freeze({
workspaceDir: runtimeOpts.workspaceDir ?? null,
harness: resolveHarnessScope(runtimeOpts.harness, runtimeOpts.hostTarget),
});
const runId = runtimeOpts.artifactRunId ?? `run-${process.pid}-${Date.now().toString(36)}`;
this.artifactStore = new ArtifactStore({
// A server with no vault keeps its payloads in this machine's
// device-local state, as a switched machine does: the no-vault
// stand-in is what `state/machine-state.ts` maps there (a resolved
// state folder would read as a fresh vault of its own).
vault: this.vault ?? noVaultRoot(),
runId,
});
// Best-effort housekeeping: clear prior processes' stale artifacts.
// Never fatal - a missing/unwritable vault just yields zero pruned.
try {
this.artifactStore.prune(ARTIFACT_TTL_MS);
} catch {
// ignore
}
}
get context(): ServerContext {
return this.contextFor();
}
/**
* The server context for ONE request. `identity` is what the transport
* resolved from the request's credential; when it is absent (stdio,
* the CLI bridge, a probe) the context falls back to the process
* config identity exactly as the plain getter always did - including
* deferring `resolveAgentName`'s refusal to the point of use. The
* identity rides the context as `requestIdentity`, so a writer tool
* can answer for the credential's agent rather than the config's.
*/
private contextFor(identity?: RequestIdentity, toolName?: string): ServerContext {
const configPath = this.configPath ?? undefined;
const served = this.vault;
return {
// With no vault, reading `vault` is the uniform refusal (design D14):
// a vault-adapter tool refuses at its first use, every other tool
// reads `vaultOrNull` or never asks.
get vault(): string {
if (served === null) throw vaultRequired(toolName);
return served;
},
vaultOrNull: served,
configPath: this.configPath,
repoRoot: this.repoRoot,
capabilityReport: this.capabilityReport,
artifactStore: this.artifactStore,
reach: this.reach,
ruleScope: this.ruleScope,
// Present only when a transport minted one: the two nulls (no
// credential, no identity) stay spelled as absence, and a
// hand-built context keeps its validity.
...(identity !== undefined ? { requestIdentity: identity } : {}),
// Owner-scope isolation (context-integrity-gates, Unit A): the
// only source of identity for `brain_context`, which takes no
// arguments. A transport-minted credential wins; otherwise the
// config is resolved per access, like `resolveAgentName`'s other
// callers, so a config edit takes effect without a restart.
//
// A GETTER, not a value, and that is the whole separation this
// context makes. `resolveAgentName` raises on a config that is
// present but unreadable, and it is right to: the alternative is a
// guessed identity, and every write path that takes one records
// under it. Resolved eagerly here, that refusal ran before EVERY
// handler, including the two read-only diagnostics whose entire job
// is to name the file that is broken - so the payload naming it was
// computed and then discarded by the condition it described.
// Deferred to the point of use, the refusal reaches exactly the
// handlers that need an identity (as a tool-level error carrying the
// file name), and the handlers that never ask answer normally.
get agentName(): string {
return identity?.agent ?? resolveAgentName(configPath);
},
};
}
/** Public method for CLI tool-call bridge — the legacy code reached into `_tools`. */
async callTool(name: string, args: Record<string, unknown>): Promise<Record<string, unknown>> {
const tool = findTool(this.tools, name);
// The same scope `tools/call` runs in: below local reach the readers
// answer without what only the `private` partition knows.
return withPrivateWithheld(this.reach !== TRANSPORT_REACH.local, async () =>
toolResult(
tool,
this.forCaller(await this.invokeToolHandler(tool, args, undefined, undefined)),
),
);
}
/**
* Whether this request must run behind the stdio transport's write
* gate rather than on the concurrent read path.
*
* Everything that is not a `tools/call` is a read. A `tools/call` is a
* write when its tool's `kind` is `write` - and every failure to KNOW
* is a write too, because the gate only ever costs serialization while
* guessing "read" could run a mutator beside another dispatch: a
* malformed `params`, an unknown tool name (refused shortly, but never
* parallelized), and a definition that carries no `kind` (a hand-built
* one that cast the field away) all take the gate. No argument is ever
* inspected: classification is per tool, never per call. This consults
* the registry only - it performs none of the work `handleRequest`
* will redo, and transport code may call it before dispatching.
*/
classifiesWrite(request: JsonRpcRequest): boolean {
if (request.method !== "tools/call") return false;
const name = (request.params as { readonly name?: unknown } | null | undefined)?.["name"];
if (typeof name !== "string") return true;
try {
return findTool(this.tools, name).kind !== "read";
} catch {
return true;
}
}
/**
* A tool result, resource body or refusal as this server's caller may
* see it: below local reach no string names a host path
* (`brain/device-path.ts` `pathsForCaller`).
*/
private forCaller(result: unknown): unknown {
return pathsForCaller(result, this.vault, this.reach, this.configPath ?? undefined);
}
/**
* Single seam through which every tool handler runs, for both the CLI
* bridge (`callTool`) and the JSON-RPC `tools/call` path. With route
* metrics off it is a transparent pass-through; with them on it times
* the handler and emits one payload-safe `mcp_route_latency` record
* (status `error` on throw), then re-raises so error handling upstream
* is unchanged. One route scope per call carries the decision time and
* the write stages the handler notes; neither ever reaches the response.
* The emit is gated and fail-open, so it can never fail or slow-fail the
* call beyond one synchronous continuity append.
*
* The unknown-argument gate runs FIRST, before the timer and before the
* handler, because a refused call is not a route to measure. Placing it
* here rather than in `handleToolsCall` is what makes it cover the CLI
* bridge too, while leaving the many tests that call `tool.handler`
* directly exactly as they were.
*
* `onProgress` is the per-request half of the same idea: one seam, so
* the request-scoped sink reaches every handler without editing any of
* the registrations. The CLI bridge passes none - a `callTool` has no
* client and therefore no token.
*/
private async invokeToolHandler(
tool: ToolDefinition,
args: Record<string, unknown>,
onProgress?: ProgressSink,
identity?: RequestIdentity,
): Promise<unknown> {
// Before the unknown-argument gate: a caller naming the visibility
// boundary is told about the boundary, not offered a typo suggestion
// for it - and the rule holds for an open schema, which that gate
// cannot see.
assertNoCallerSuppliedReach(tool, args);
assertKnownArguments(tool, args);
if (!this.routeMetricsEnabled) {
try {
return await tool.handler(this.contextFor(identity, tool.name), args, onProgress);
} catch (exc) {
throw this.mapFrozen(tool, exc, identity);
}
}
const start = performance.now();
let status: McpRouteStatus = "ok";
const routeScope = createRouteScope();
try {
return await routeScope.run(async () =>
tool.handler(this.contextFor(identity, tool.name), args, onProgress),
);
} catch (exc) {
status = "error";
throw this.mapFrozen(tool, exc, identity);
} finally {
// The route metric is a vault continuity record: none without a vault.
if (this.vault !== null) {
emitMcpRouteLatency(
this.vault,
{
tool: tool.name,
scope: this.scope,
status,
durationMs: performance.now() - start,
argKeys: Object.keys(args),
...(routeScope.decisionMs() !== undefined
? { decisionMs: routeScope.decisionMs() }
: {}),
...(routeScope.stages() !== undefined ? { stages: routeScope.stages() } : {}),
},
this.routeMetricsEnabled,
);
}
}
}
/**
* Map a frozen-vault refusal onto the structured error a caller can
* act on, recording one `write-refused` event on the way through.
*
* Here rather than in each write tool because the freeze is enforced
* at the vault guard, so ANY handler can raise it - including the
* internal writers a tool composes - and a per-tool `catch` would
* cover the ones somebody remembered. Every other exception passes
* through untouched.
*/
private mapFrozen(tool: ToolDefinition, exc: unknown, identity?: RequestIdentity): unknown {
// A store migration running on this machine refuses like a freeze.
if (exc instanceof MigrationInProgressError) return migrationInProgressRefusal(tool.name, exc);
if (!(exc instanceof VaultFrozenError) || this.vault === null) return exc;
// `agentName` is optional on the context - a transport may supply
// none - so an absent identity is recorded as the named absence
// rather than as a plausible-looking name nobody claimed.
return vaultFrozenRefusal(
this.vault,
tool.name,
exc,
() => this.contextFor(identity).agentName ?? UNRESOLVED_AGENT,
);
}
/** Process one JSON-RPC request or notification. Returns null for notifications. */
async handleRequest(
request: JsonRpcRequest,
identity?: RequestIdentity,
): Promise<JsonRpcResponse | null> {
if (typeof request !== "object" || request === null) {
return errorResponse(null, INVALID_REQUEST, "request must be an object");
}
if (request.jsonrpc !== JSONRPC_VERSION) {
return errorResponse(request.id ?? null, INVALID_REQUEST, "unsupported jsonrpc version");
}
const method = request.method;
if (typeof method !== "string") {
return errorResponse(request.id ?? null, INVALID_REQUEST, "method must be a string");
}
const paramsRaw = request.params ?? {};
if (typeof paramsRaw !== "object" || paramsRaw === null || Array.isArray(paramsRaw)) {
return errorResponse(request.id ?? null, INVALID_PARAMS, "params must be an object");
}
const params = paramsRaw as Record<string, unknown>;
// JSON-RPC 2.0 §4.1: `id` MUST be a string, number, or null. Anything
// else (objects, symbols, arrays) is a protocol violation — respond
// with INVALID_REQUEST and id: null so a non-compliant client sees a
// well-formed error frame instead of getting our object back as `id`.
const isNotification = !("id" in request);
if (!isNotification) {
const idType = typeof request.id;
if (idType !== "string" && idType !== "number" && request.id !== null) {
return errorResponse(null, INVALID_REQUEST, "id must be string, number, or null");
}
}
const requestId = request.id;
try {
let result: unknown;
if (method === "initialize") {
result = this.handleInitialize(params);
} else if (method === "notifications/initialized") {
// No internal state to flip — protocol parity only.
return null;
} else if (method === "ping") {
result = {};
} else if (method === "tools/list") {
result = this.handleToolsList();
} else if (method === "tools/call") {
// Below local reach every reader answers without what only the
// `private` partition knows, down to the folds' derived counters.
result = await withPrivateWithheld(this.reach !== TRANSPORT_REACH.local, () =>
this.handleToolsCall(params, identity),
);
} else if (method === "resources/list") {
result = this.handleResourcesList();
} else if (method === "resources/templates/list") {
result = this.handleResourcesTemplatesList();
} else if (method === "resources/read") {
// A resource body is prose the brain rendered; it may name a host path.
result = this.forCaller(
await withPrivateWithheld(this.reach !== TRANSPORT_REACH.local, () =>
this.handleResourcesRead(params, identity),
),
);
} else if (method.startsWith("notifications/")) {
return null;
} else {
throw new MCPError(METHOD_NOT_FOUND, `unknown method: ${method}`);
}
if (isNotification) return null;
return { jsonrpc: JSONRPC_VERSION, id: requestId, result };
} catch (exc) {
if (isNotification) return null;
if (exc instanceof MCPError) {
// A refusal's prose and data may name a host path too.
const { message, data } = this.forCaller({ message: exc.message, data: exc.data }) as {
message: string;
data: typeof exc.data;
};
return errorResponse(requestId, exc.code, message, data);
}
// A channel that forwards raw exception prose to the caller. Node's
// fs errors embed the absolute path of whatever the caller's last
// bad argument named, so before this leaves the process it goes
// through the redactor - at remote reach with the vault, home and
// temp roots replaced too: a caller probing with traversal paths
// learns that a file is missing, not the host layout behind it.
return internalErrorResponse(requestId, exc, this.vault, this.reach);
}
}
private handleInitialize(params: Record<string, unknown>): Record<string, unknown> {
const clientVersion = params["protocolVersion"];
const negotiated = typeof clientVersion === "string" ? clientVersion : PROTOCOL_VERSION;
// The handshake is the third site that read the config before any
// handler could run, and the one that mattered most: a client whose
// `initialize` fails never issues a `tools/call` at all, so a refusal
// here withholds the diagnostics along with everything else. It does
// not become a guess either - `buildInstructions` renders the reason
// in place of the identity line, so the agent is told there is no
// identity to log under rather than handed one.
const identity = resolveIdentityOrReason(this.configPath ?? undefined);
return {
protocolVersion: negotiated,
capabilities: {
tools: { listChanged: false },
resources: { listChanged: false, subscribe: false },
},
serverInfo: { name: this.serverName, version: SERVER_VERSION },
instructions: buildInstructions({
agent: identity,
scope: this.scope,
// Computed in the constructor and held on the instance, so the
// handshake states what this runtime actually left callable
// without evaluating the window a second time.
capabilities: this.capabilityReport,
}),
};
}
private handleToolsList(): Record<string, unknown> {
// Hidden tools (deprecated aliases) stay callable but are not
// advertised - the list is what every client pays tokens for.
return {
tools: this.tools
.filter((t) => t.hidden !== true)
.map((t) => ({
name: t.name,
description: t.description,
inputSchema: t.inputSchema,
...(t.outputSchema ? { outputSchema: t.outputSchema } : {}),
})),
};
}
private handleResourcesList(): Record<string, unknown> {
return { resources: listResources() };
}
private handleResourcesTemplatesList(): Record<string, unknown> {
return { resourceTemplates: listResourceTemplates() };
}
private handleResourcesRead(
params: Record<string, unknown>,
identity?: RequestIdentity,
): Record<string, unknown> {
const uri = params["uri"];
if (typeof uri !== "string") {
throw new MCPError(INVALID_PARAMS, "resources/read requires a string `uri`");
}
// TODO(task 2.10 WP2a): resources served from the folds need no vault.
if (this.vault === null) throw vaultRequired(undefined);
const content = readResource(
{
vault: this.vault,
agentName: this.contextFor(identity).agentName,
reach: this.reach,
configPath: this.configPath,
},
uri,
);
return { contents: [content] };
}
private async handleToolsCall(
params: Record<string, unknown>,
identity?: RequestIdentity,
): Promise<Record<string, unknown>> {
const name = params["name"];
if (typeof name !== "string") {
throw new MCPError(INVALID_PARAMS, "tools/call requires a string name");
}
const tool = findTool(this.tools, name);
const argsRaw = params["arguments"] ?? {};
if (typeof argsRaw !== "object" || argsRaw === null || Array.isArray(argsRaw)) {
throw new MCPError(INVALID_PARAMS, "tools/call arguments must be an object");
}
const args = argsRaw as Record<string, unknown>;
// Read before the handler runs: a malformed token is a request
// defect, and refusing it after the work has been done would leave
// the caller unable to tell which half failed.
const token = readProgressToken(params);
const onProgress = progressSink(token, this.sendNotification);
// A token this transport cannot honour is refused by name on the way
// out - on an isError result and on a JSON-RPC error too, because a
// call that asked for progress and then failed still never got any.
const refusal: ProgressRefusal | undefined =
token !== undefined && onProgress === undefined
? progressRefusal(token, PROGRESS_REASON.transportSingleResponse)
: undefined;
try {
const structured = this.forCaller(
await this.invokeToolHandler(tool, args, onProgress, identity),
);
return withProgressRefusal(buildMcpToolResult(tool, structured, this.artifactStore), refusal);
} catch (exc) {
if (exc instanceof MCPError) {
if (refusal === undefined) throw exc;
throw new MCPError(exc.code, exc.message, { ...exc.data, [PROGRESS_META_KEY]: refusal });
}
// The tool-level twin of the INTERNAL_ERROR channel: the same raw
// exception prose, so the same host-path redaction at remote reach.
// A local caller already holds the filesystem, and these messages
// carry operator remediation (a config path to chmod) verbatim.
const raw = (exc as Error).message ?? String(exc);
const message =
this.reach === TRANSPORT_REACH.local
? raw
: redactedErrorMessage(raw, this.vault, this.reach);
// ValueError/TypeError semantics in Python → tool-level error envelope.
// OSError in Python → "filesystem error" prefix. We collapse both to a
// single tool-level error since JS doesn't distinguish.
return withProgressRefusal(
toolError(message, codeForError(exc), errorDetailFor(exc)),
refusal,
);
}
}
}
/**
* The route-metrics gate for this process, with a config that is present
* but UNREADABLE folded to the gate's own default rather than raised.
*
* This is the only config read on the construction path, so raising here
* cost the entire process - no `tools/list`, no `tools/call`, and in
* particular no `vault_health`, the surface whose whole job is to name
* the file that is broken. It is the same trade `appendLogEvent` makes
* with `resolveDeviceId` (see `AppendLogEventOptions.deviceId`): a read
* that sits in front of everything turns one bad file mode into a dead
* runtime, and the fallback is not a neutral value invented to make a
* broken install look healthy - it is this gate's documented default-OFF
* state, it loses only telemetry, and nothing else absorbs the condition.
* `second_brain_status` and `vault_health` still report the file by name,
* and every identity-bearing write still refuses on it.
*
* Deliberately NOT the same answer as the identity resolvers, because it
* is not the same class of problem: an unresolvable identity has no
* neutral value - every candidate is a guess that gets written into the
* vault under someone's name - while an unresolvable observability toggle
* has exactly one, and choosing it writes nothing at all.
*
* Narrow on purpose: only {@link ConfigReadError} is absorbed, so an
* unsupported platform or any other failure to locate the config at all
* is still fatal at construction. `OPEN_SECOND_BRAIN_MCP_ROUTE_METRICS_ENABLED`
* remains the escape hatch - it is read before the file is opened, so an
* operator who wants the metrics on can have them on a broken config.
*/
function routeMetricsGate(configPath: string | undefined): boolean {
try {
return resolveMcpRouteMetricsEnabled(configPath);
} catch (err) {
if (err instanceof ConfigReadError) return false;
throw err;
}
}
/**
* The agent identity for the handshake instructions, or the error saying
* why there is none. Never a substitute name: see
* {@link MCPServer.context} for why `resolveAgentName`'s refusal is kept
* rather than defaulted, and `buildInstructions` for what the caller is
* told in its place.
*/
function resolveIdentityOrReason(configPath: string | undefined): string | ConfigReadError {
try {
return resolveAgentName(configPath);
} catch (err) {
if (err instanceof ConfigReadError) return err;
throw err;
}
}
function toolResult(tool: ToolDefinition, structured: unknown): Record<string, unknown> {
assertOutputContract(tool.name, tool.outputSchema, structured);
const text = JSON.stringify(structured, sortedReplacer, 2);
return {
content: [{ type: "text", text }],
structuredContent: structured,
isError: false,
};
}
/**
* MCP `tools/call` result builder. Identical to {@link toolResult} for
* tools with no `previewBudget` or small outputs, but when a budgeted
* tool's serialized output exceeds the budget it parks the full payload
* in `store` and swaps `content[0].text` for a bounded preview envelope.
* `structuredContent` is always the full, contract-validated object, so
* programmatic consumers and `outputSchema` are untouched. Exported for
* direct unit testing of the seam.
*/
export function buildMcpToolResult(
tool: ToolDefinition,
structured: unknown,
store: ArtifactStore,
): Record<string, unknown> {
assertOutputContract(tool.name, tool.outputSchema, structured);
const serialized = JSON.stringify(structured, sortedReplacer, 2);
const outcome = applyPreviewBudget(serialized, tool.previewBudget, store);
return {
content: [{ type: "text", text: outcome.text }],
structuredContent: structured,
isError: false,
};
}
/**
* An `isError` tool result. The text is the message alone, as it always
* was; the stable code rides on `_meta` because strict clients validate
* `structuredContent` against the tool's output schema even on an error.
*/
function toolError(
message: string,
code: ToolErrorCode,
detail?: ToolErrorDetail,
): Record<string, unknown> {
return {
content: [{ type: "text", text: message }],
isError: true,
[META_MEMBER]: { [TOOL_ERROR_META_KEY]: toolErrorMeta(code, detail) },
};
}
function sortedReplacer(_key: string, value: unknown): unknown {
if (value !== null && typeof value === "object" && !Array.isArray(value)) {
const entries = Object.entries(value).toSorted(([a], [b]) => a.localeCompare(b));
return Object.fromEntries(entries);
}
return value;
}
/** The member of `error.data` every JSON-RPC error answer carries. */
const ERROR_DATA_CODE_KEY = "code";
/** The stderr line a thrower-supplied code outside the registry is named on. */
const UNREGISTERED_CODE_WARNING = "warning: unregistered error code on the wire: ";
/** The longest quoted code that warning line repeats. */
const UNREGISTERED_CODE_LOG_MAX = 120;
/**
* `data` with its stable string code. A thrower-supplied string code
* always wins; otherwise the default derived from the numeric JSON-RPC
* code is added after the thrower's own members, so a record such as the
* argument guard's keeps its shape and gains one key.
*
* A supplied code outside {@link isToolErrorCode} is still sent as it
* is - replacing it would hide which producer chose it - and is named on
* stderr. Every producer passes a constant token, never prose, but the
* line exists to catch one that breaks that rule, so the code is written
* JSON-quoted and capped: a newline in it cannot forge a second line.
*/
function withDefaultCode(code: JsonRpcErrorCode, data: MCPErrorData | undefined): JsonRpcErrorData {
const supplied: unknown = (data as { readonly [ERROR_DATA_CODE_KEY]?: unknown } | undefined)?.[
ERROR_DATA_CODE_KEY
];
if (data !== undefined && typeof supplied === "string") {
if (!isToolErrorCode(supplied)) {
const quoted = JSON.stringify(supplied).slice(0, UNREGISTERED_CODE_LOG_MAX);
process.stderr.write(`${UNREGISTERED_CODE_WARNING}${quoted}\n`);
}
return data as JsonRpcErrorData;
}
return { ...data, [ERROR_DATA_CODE_KEY]: defaultCodeForRpc(code) };
}
/**
* The one builder every JSON-RPC error answer passes through, including
* the transport errors of `stdio.ts` and `http.ts`, so "every error
* response carries `error.data.code`" holds by construction.
*/
export function errorResponse(
requestId: unknown,
code: JsonRpcErrorCode,
message: string,
data?: MCPErrorData,
): JsonRpcResponse {
return {
jsonrpc: JSONRPC_VERSION,
id: requestId ?? null,
error: { code, message, data: withDefaultCode(code, data) },
};
}
/**
* The prefix of the INTERNAL_ERROR answer {@link internalErrorResponse}
* builds for an unmapped throw. Handlers that throw their own
* INTERNAL_ERROR keep their own message; `error.data.code` is the stable
* signal, not this prefix.
*/
const INTERNAL_ERROR_PREFIX = "internal error: ";
/**
* The INTERNAL_ERROR answer for a throw no handler mapped: the raw prose
* through the redactor for the bind's reach, the code from the
* classifier, which names an unknown class on stderr. One builder for the
* dispatcher and the HTTP catch-all, so the two channels cannot drift.
*/
export function internalErrorResponse(
requestId: unknown,
exc: unknown,
vault: string | null,
reach: TransportReach,
): JsonRpcResponse {
const raw = (exc as Error).message ?? String(exc);
const message = redactedErrorMessage(raw, vault, reach);
const detail = errorDetailFor(exc);
return errorResponse(requestId, INTERNAL_ERROR, `${INTERNAL_ERROR_PREFIX}${message}`, {
code: codeForError(exc),
...(detail === undefined ? {} : { reason: detail.reason, remedy: detail.remedy }),
});
}
/**
* Error prose for a caller, with the vault's KNOWN credential values
* scrubbed. The fourth composition this redaction gained: the shapes-only
* passes cannot see a resolved credential under a quiet key name, and an
* exception is exactly where one travels (a fetch failure echoing the URL
* it was handed, a refusal naming the field it rejected). The values come
* from {@link resolvedSecretLiterals}, which contributes NOTHING when the
* store is absent, empty, unreadable or locked - so a boundary that
* cannot know the values answers byte-identically to the pre-literal
* redactor instead of pretending to redact.
*/
function redactedErrorMessage(raw: string, vault: string | null, reach: TransportReach): string {
// With no vault there is no vault path to hide and no custody store to
// read literals from; the home and temp roots are still redacted.
if (vault === null) return redactErrorForCaller(raw, "", reach, []);
return redactErrorForCaller(raw, vault, reach, resolvedSecretLiterals(vault));
}
// Re-exports so callers that previously imported these names from
// `open_second_brain.mcp` keep working.
export { PROTOCOL_VERSION, SERVER_NAME, SERVER_VERSION, JSONRPC_VERSION };