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
13.1 KB
Raw Blame
/**
 * Helpers shared by the Brain MCP domain modules: argument
 * coercion, vault-relative path rendering, and the consolidated
 * view dispatcher used by brain_brief / brain_analytics.
 */

import { isAbsolute, relative, resolve } from "node:path";
import { toPosix } from "../../core/path-safety.ts";
import { resolveTimezone } from "../../core/config.ts";
import { RECALL_CHANNEL, type RecallTelemetryOptions } from "../../core/brain/recall-telemetry.ts";
import { isoSecond } from "../../core/brain/time.ts";
import { formatLocalTimestamp } from "../../core/brain/present-time.ts";
import { INTERNAL_ERROR, INVALID_PARAMS, MCPError } from "../protocol.ts";
import type { ServerContext } from "../tool-contract.ts";
import { coerceBool } from "../coerce.ts";
import {
  CountGuardError,
  assertExpectedCount,
  type CountGuardOptions,
} from "../../core/brain/count-guard.ts";
import type { ProgressSink } from "../../core/brain/progress.ts";
import {
  createSafeguard,
  resolveSafeguardTimeoutMs,
  type Operation,
  type Safeguard,
} from "../../core/brain/safeguard.ts";

/**
 * Read the shared `--expect` / `--strict` count-guard arguments from an MCP
 * tool payload. `expect` absent means no assertion; a non-integer or negative
 * value is a client error.
 */
export function readCountGuardArgs(args: Record<string, unknown>): {
  expect: number | null;
  strict: boolean;
} {
  const raw = args["expect"];
  let expect: number | null = null;
  if (raw !== undefined && raw !== null) {
    const n = typeof raw === "number" ? raw : Number(raw);
    if (!Number.isInteger(n) || n < 0) {
      throw new MCPError(INVALID_PARAMS, "'expect' must be a non-negative integer");
    }
    expect = n;
  }
  return { expect, strict: coerceBool(args, "strict") === true };
}

/**
 * Run the count guard, mapping a {@link CountGuardError} to INVALID_PARAMS so
 * the caller (not the server) is blamed for the mismatch / guardless mutation.
 */
export function enforceCountGuard(opts: CountGuardOptions): void {
  try {
    assertExpectedCount(opts);
  } catch (err) {
    if (err instanceof CountGuardError) throw new MCPError(INVALID_PARAMS, err.message);
    throw err;
  }
}

/**
 * A cooperative deadline for one long MCP operation, resolved through the
 * documented ladder: `safeguard_timeout_<operation>_seconds`, then
 * `safeguard_timeout_seconds`, then the built-in default.
 *
 * One factory rather than one per domain module. Three had grown - the
 * maintenance lane's, the graph tools', and none at all for `brain_dream`
 * - and the gap was invisible precisely because each module answered the
 * question locally. `docs/mcp.md` states the ladder once; this is the one
 * place that implements it for the MCP surface, so a tool that reaches a
 * long operation and forgets the deadline is a missing call to a named
 * helper rather than a missing copy of a three-line idiom.
 */
export function toolSafeguard(ctx: ServerContext, operation: Operation): Safeguard {
  return createSafeguard({
    operation,
    timeoutMs: resolveSafeguardTimeoutMs(operation, ctx.configPath ?? undefined),
  });
}

export const ISO_DATE_ONLY_RE = /^\d{4}-\d{2}-\d{2}$/;

/**
 * Run a tool handler body, classifying a thrown error into the right MCP
 * error code: a client-resolvable input problem (any class in
 * `validationClasses`, or an already-typed `MCPError`) surfaces as
 * `INVALID_PARAMS`; anything else is a server fault (`INTERNAL_ERROR`).
 * This mapping is safety-relevant - it decides whether the CALLER or the
 * SERVER is blamed for a failure - and was previously copy-pasted
 * identically across derive-tools, ingest-tools, ner-tools, and
 * research-tools, one drift away from silently reclassifying an error.
 */
export async function wrapToolErrors<T>(
  tool: string,
  validationClasses: ReadonlyArray<new (...args: never[]) => Error>,
  fn: () => Promise<T>,
): Promise<T> {
  try {
    return await fn();
  } catch (err) {
    if (validationClasses.some((cls) => err instanceof cls)) {
      throw new MCPError(INVALID_PARAMS, `${tool}: ${(err as Error).message}`);
    }
    if (err instanceof MCPError) throw err;
    const reason = err instanceof Error ? err.message : String(err);
    throw new MCPError(INTERNAL_ERROR, `${tool}: ${reason}`);
  }
}

export function coerceIsoTimestampOrDate(
  tool: string,
  field: string,
  raw: unknown,
  shape: "date-only" | "date-or-timestamp" = "date-or-timestamp",
): string | undefined {
  if (raw === undefined || raw === null) return undefined;
  if (typeof raw !== "string" || raw.trim().length === 0) {
    throw new MCPError(
      INVALID_PARAMS,
      `${tool}: ${field} must be an ISO date${shape === "date-or-timestamp" ? " or ISO timestamp" : " (YYYY-MM-DD)"}`,
    );
  }
  const v = raw.trim();
  if (shape === "date-only" && !ISO_DATE_ONLY_RE.test(v)) {
    throw new MCPError(
      INVALID_PARAMS,
      `${tool}: ${field} must be an ISO date (YYYY-MM-DD); got ${JSON.stringify(v)}`,
    );
  }
  // Validate by parsing - rejects "2026-13-99" / "garbage" / etc.
  const ms = Date.parse(v);
  if (!Number.isFinite(ms)) {
    throw new MCPError(
      INVALID_PARAMS,
      `${tool}: ${field} must be a parseable ISO date${shape === "date-or-timestamp" ? " or timestamp" : ""}; got ${JSON.stringify(v)}`,
    );
  }
  return v;
}

export function coercePositiveInteger(
  tool: string,
  field: string,
  raw: unknown,
): number | undefined {
  if (raw === undefined || raw === null) return undefined;
  if (typeof raw === "number") {
    if (!Number.isInteger(raw) || raw < 1) {
      throw new MCPError(INVALID_PARAMS, `${tool}: ${field} must be a positive integer`);
    }
    return raw;
  }
  if (typeof raw === "string") {
    const trimmed = raw.trim();
    if (trimmed === "" || !/^[0-9]+$/.test(trimmed)) {
      throw new MCPError(INVALID_PARAMS, `${tool}: ${field} must be a positive integer`);
    }
    const parsed = Number.parseInt(trimmed, 10);
    if (parsed < 1) {
      throw new MCPError(INVALID_PARAMS, `${tool}: ${field} must be a positive integer`);
    }
    return parsed;
  }
  throw new MCPError(INVALID_PARAMS, `${tool}: ${field} must be a positive integer`);
}

/**
 * Coerce an optional integer argument that MAY be zero (non-negative).
 * Distinct from {@link coercePositiveInteger}: some core builders accept
 * `0` (e.g. a zero-day activity window or a zero-entry limit), and the MCP
 * surface must not reject a value the core and CLI honour.
 */
export function coerceNonNegativeInteger(
  tool: string,
  field: string,
  raw: unknown,
): number | undefined {
  if (raw === undefined || raw === null) return undefined;
  if (typeof raw === "number") {
    if (!Number.isInteger(raw) || raw < 0) {
      throw new MCPError(INVALID_PARAMS, `${tool}: ${field} must be a non-negative integer`);
    }
    return raw;
  }
  if (typeof raw === "string") {
    const trimmed = raw.trim();
    if (trimmed === "" || !/^[0-9]+$/.test(trimmed)) {
      throw new MCPError(INVALID_PARAMS, `${tool}: ${field} must be a non-negative integer`);
    }
    return Number.parseInt(trimmed, 10);
  }
  throw new MCPError(INVALID_PARAMS, `${tool}: ${field} must be a non-negative integer`);
}

/**
 * Route one consolidated tool's `view` argument to its per-view handler.
 *
 * The progress sink is forwarded rather than dropped. It is optional at
 * every link, so a view that has nothing to report ignores it - but a
 * dispatcher that silently swallowed it would make a view which DOES run
 * long, such as the operator brief's dry-run consolidation pass, look
 * like a tool that emits no progress rather than one whose progress was
 * discarded in transit. Those are the two cases this release exists to
 * keep apart.
 */
export function dispatchByView(
  table: Readonly<
    Record<
      string,
      (
        ctx: ServerContext,
        args: Record<string, unknown>,
        onProgress?: ProgressSink,
      ) => Promise<unknown> | unknown
    >
  >,
  ctx: ServerContext,
  args: Record<string, unknown>,
  onProgress?: ProgressSink,
): Promise<unknown> | unknown {
  const view = typeof args["view"] === "string" ? args["view"] : "";
  const handler = table[view];
  if (handler === undefined) {
    throw new MCPError(
      INVALID_PARAMS,
      `view must be one of ${Object.keys(table).join(", ")}; got ${JSON.stringify(args["view"])}`,
    );
  }
  return handler(ctx, args, onProgress);
}

/**
 * Timezone presentation (t_2ccadc6a): when the operator configured an
 * IANA zone, brief/analytics envelopes gain two ADDITIVE fields - a
 * `timezone` echo and `local_time` (the render instant in that zone).
 * Stored timestamps inside the envelope stay canonical UTC; with no
 * timezone configured the envelope is byte-identical to 0.45.0.
 */
export function localizeEnvelope(ctx: ServerContext, result: unknown): unknown {
  if (result === null || typeof result !== "object" || Array.isArray(result)) return result;
  const tz = resolveTimezone(ctx.configPath ?? undefined);
  if (tz === null) return result;
  return {
    ...(result as Record<string, unknown>),
    timezone: tz,
    local_time: formatLocalTimestamp(isoSecond(new Date()), tz),
  };
}

export function optionalStringArg(
  tool: string,
  args: Record<string, unknown>,
  key: string,
  maxLength?: number,
): string | undefined {
  const raw = args[key];
  if (raw === undefined || raw === null) return undefined;
  if (typeof raw !== "string" || raw.trim().length === 0) {
    throw new MCPError(INVALID_PARAMS, `${tool}: ${key} must be a non-empty string`);
  }
  const value = raw.trim();
  if (maxLength !== undefined && value.length > maxLength) {
    throw new MCPError(INVALID_PARAMS, `${tool}: ${key} must be at most ${maxLength} characters`);
  }
  return value;
}

export function requiredStringArg(
  tool: string,
  args: Record<string, unknown>,
  key: string,
): string {
  const value = optionalStringArg(tool, args, key);
  if (value === undefined) throw new MCPError(INVALID_PARAMS, `${tool}: ${key} is required`);
  return value;
}

// ----- brain_recall_telemetry ---------------------------------------------

/**
 * Telemetry options for an MCP tool handler, or `undefined` when the
 * caller did not opt in.
 *
 * `channel` is fixed at {@link RECALL_CHANNEL.mcp} rather than taken from
 * the caller: every caller of this helper IS an MCP tool handler, so the
 * transport is a fact about the seam, not an argument. `telemetry_host`
 * stays the caller's to set, and stays a runtime identity - which is the
 * separation the channel dimension exists to make.
 */
export function telemetryOptionsFromArgs(
  tool: string,
  args: Record<string, unknown>,
  defaultHost: string,
): RecallTelemetryOptions | undefined {
  if (!coerceBool(args, "telemetry")) return undefined;
  // Each id parsed ONCE. The conditional-spread idiom used to call the
  // parser twice per field, so a validating parser ran its checks twice
  // and any future non-idempotent one would have diverged silently.
  const sessionId = optionalStringArg(tool, args, "session_id");
  const turnId = optionalStringArg(tool, args, "turn_id");
  return {
    host: optionalStringArg(tool, args, "telemetry_host") ?? defaultHost,
    channel: RECALL_CHANNEL.mcp,
    ...(sessionId !== undefined ? { sessionId } : {}),
    ...(turnId !== undefined ? { turnId } : {}),
  };
}

/**
 * Produce a vault-relative path, swallowing errors (a defensive pattern
 * for output rendering). Exported for unit tests
 * — internal callers stay inside this module.
 *
 * Contract: an in-vault answer is forward-slash on EVERY host, Windows
 * included (`Brain/inbox/sig-x.md`). It is the note's portable,
 * Obsidian-style vault identity, so devices sharing one vault return the
 * same string whatever their OS. A target outside the vault comes back
 * unchanged, in its host form. See "Vault-relative paths are
 * forward-slash on every host" in `docs/mcp.md`.
 *
 * @internal
 */
export function vaultRelativeSafe(vault: string, target: string): string {
  const absVault = resolve(vault);
  const absTarget = resolve(target);
  // Use Node's path.relative so containment is decided with the host's
  // own separator and drive rules. The prior implementation hard-coded
  // `"/"` and silently broke on Windows when the vault sat under e.g.
  // `C:\Users\...`.
  const rel = relative(absVault, absTarget);
  if (rel === "") return "";
  // `relative()` returns a path starting with `..` (or, in rare drive-
  // mismatch cases on Windows, an absolute path) when the target sits
  // outside the vault. In both situations we return the original target
  // unchanged — callers treat that as "not under vault" and render it
  // as-is.
  if (rel.startsWith("..") || isAbsolute(rel)) return target;
  // The in-vault answer goes on the wire in the vault's own POSIX form
  // (`Brain/inbox/sig-x.md`), whatever the host separator. It is a vault
  // identity, not a host path: agents feed it back into tools, match it
  // against wikilinks and compare it across a Syncthing peer set that
  // mixes Windows and POSIX devices, and every core reader already keys
  // notes by the forward-slash form (`vaultRelative`, `canonicalNotePath`).
  // A Windows server answering `Brain\inbox\sig-x.md` would name a note
  // no other surface recognises.
  return toPosix(rel);
}

// ----- Tool registration ---------------------------------------------------