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.4 KB
Raw Blame
/**
 * The vault-policy tools of the admin family: the label vocabulary
 * (`brain_labels`), the frontmatter tier guard (`brain_tiers`) and the
 * secret custody surface (`brain_secrets`). Split from `admin-tools.ts`
 * (task 3.19); registration happens through that module's registry,
 * which preserves the public ADMIN_TOOLS surface.
 */

import { existsSync } from "node:fs";
import { relative } from "node:path";
import { toPosix } from "../../core/path-safety.ts";
import { reachView } from "../../core/brain/reach-view.ts";
import { resolveAgentName } from "../../core/config.ts";
import { resolveSearchConfig } from "../../core/search/index.ts";
import { Store } from "../../core/search/store.ts";
import {
  assignNoteLabel,
  LabelVocabularyError,
  readLabels,
  removeNoteLabel,
} from "../../core/brain/labels.ts";
import { LabelSuggestPrivateNoteError, suggestNoteLabels } from "../../core/brain/label-suggest.ts";
import { StandingRulesWriteRefusedError } from "../../core/brain/standing-rules.ts";
import { GovernedPathWriteRefusedError } from "../../core/write-binding/index.ts";
import { assertVaultIdentityForWrite } from "../../core/brain/vault-identity.ts";
import { loadSchemaPack } from "../../core/brain/schema-pack.ts";
import { listSecrets } from "../../core/brain/secrets/store.ts";
import { runWithSecret, SecretExecDeniedError } from "../../core/brain/secrets/exec.ts";
import { readableAtContextReach, readableAtContextReachOrUndefined } from "./reach-readable.ts";
import { requiredStringArg } from "./shared.ts";
import { writeFrontmatterAtomic } from "../../core/vault.ts";
import { resolveNotePath } from "../../core/brain/note-path.ts";
import type { FrontmatterMap } from "../../core/types.ts";
import { parseFrontmatter } from "../../core/vault.ts";
import { normalizeAgentArgument } from "../../core/agent-identity.ts";
import { coerceStrList, unknownOperationError } from "../coerce.ts";
import { INVALID_PARAMS, MCPError } from "../protocol.ts";
import type { ServerContext } from "../tool-contract.ts";
import { contextReach } from "../tool-contract.ts";

/**
 * `brain_labels suggest`: advisory decision-model suggestions (use
 * `labels`). Read-only; never assigns.
 */
export async function labelsSuggest(
  ctx: ServerContext,
  args: Record<string, unknown>,
  path: string,
): Promise<Record<string, unknown>> {
  const abs = vaultContainedPath(ctx.vault, path, "brain_labels suggest");
  // Same reach rule as `show`: a page reserved against remote reads
  // answers exactly as an absent one.
  const view = reachView(ctx.vault, contextReach(ctx));
  if (!view.visible(toPosix(relative(ctx.vault, abs)))) {
    throw new MCPError(INVALID_PARAMS, `brain_labels suggest: note does not exist: ${path}`);
  }
  const dimensions = coerceStrList(args, "dimensions");
  try {
    const result = await suggestNoteLabels(ctx.vault, path, {
      pack: loadSchemaPack(ctx.vault),
      ...(dimensions.length > 0 ? { dimensions } : {}),
      configPath: ctx.configPath,
    });
    return { ...result };
  } catch (exc) {
    if (exc instanceof LabelVocabularyError || exc instanceof LabelSuggestPrivateNoteError) {
      throw new MCPError(INVALID_PARAMS, `brain_labels suggest: ${exc.message}`);
    }
    throw exc;
  }
}

/** Controlled-vocabulary classification over the schema pack's labels. */
export function toolBrainLabels(
  ctx: ServerContext,
  args: Record<string, unknown>,
): Record<string, unknown> | Promise<Record<string, unknown>> {
  const op = args["operation"];
  if (op !== "assign" && op !== "remove" && op !== "show" && op !== "suggest") {
    throw unknownOperationError("brain_labels: operation must be assign|remove|show|suggest");
  }
  // a-label-is-not-a-boundary, U12: the ARGUMENT is right and the
  // VALIDATOR's message was wrong. `path` is the only name this tool
  // declares for the note - a caller passing `id` is refused by name by
  // the unknown-argument gate (`src/mcp/argument-guard.ts`) before the
  // handler runs - but this check answered an ABSENT `path` with a
  // sentence about its SHAPE, so a caller who sent the wrong name read
  // it as "my path is malformed" and retried the same call. The shared
  // coercion already tells absence and malformation apart, and stamps
  // the operation into both, so the two failures no longer share a
  // sentence.
  const path = requiredStringArg(`brain_labels ${op}`, args, "path");
  if (op === "suggest") return labelsSuggest(ctx, args, path);
  if (op === "show") {
    const abs = vaultContainedPath(ctx.vault, path, "brain_labels show");
    // A metadata oracle otherwise (audit L8): at remote reach a page
    // reserved against remote reads answers exactly as an absent one, so
    // the reply cannot prove it exists. At local reach the view is a no-op.
    const view = reachView(ctx.vault, contextReach(ctx));
    if (!view.visible(toPosix(relative(ctx.vault, abs)))) {
      throw new MCPError(INVALID_PARAMS, `brain_labels show: note does not exist: ${path}`);
    }
    const [metadata] = parseFrontmatter(abs);
    return { path, labels: readLabels(metadata) };
  }
  const pack = loadSchemaPack(ctx.vault);
  const dimension = args["dimension"];
  if (typeof dimension !== "string" || dimension.trim() === "") {
    throw new MCPError(INVALID_PARAMS, `brain_labels ${op}: dimension must be non-empty`);
  }
  // A note the caller may not read at its reach is refused as a missing
  // one, before its frontmatter is read or written.
  const readable = readableAtContextReachOrUndefined(ctx);
  const reach = readable !== undefined ? { readable } : {};
  try {
    if (op === "remove") {
      return { ...removeNoteLabel(ctx.vault, path, { dimension, pack, ...reach }) };
    }
    const value = args["value"];
    if (typeof value !== "string" || value.trim() === "") {
      throw new MCPError(INVALID_PARAMS, "brain_labels assign: value must be non-empty");
    }
    const agentArg = args["agent"];
    const agent =
      normalizeAgentArgument(typeof agentArg === "string" ? agentArg : null) ??
      resolveAgentName(ctx.configPath ?? undefined);
    return {
      ...assignNoteLabel(ctx.vault, path, {
        dimension,
        value,
        pack,
        agent,
        now: new Date(),
        ...reach,
      }),
    };
  } catch (exc) {
    if (exc instanceof LabelVocabularyError) {
      throw new MCPError(INVALID_PARAMS, `brain_labels ${op}: ${exc.message}`);
    }
    // A refused target is a bad argument, not a server fault: the caller
    // named a file this surface will not rewrite, and the message says
    // which one so the agent stops trying rather than retrying blind.
    if (exc instanceof StandingRulesWriteRefusedError) {
      throw new MCPError(INVALID_PARAMS, `brain_labels ${op}: ${exc.message}`);
    }
    // The Brain machinery root and the operator's declared write binding
    // refuse the same way: the caller named a target the governance
    // envelope does not admit, and naming it back is the whole answer.
    if (exc instanceof GovernedPathWriteRefusedError) {
      throw new MCPError(INVALID_PARAMS, `brain_labels ${op}: ${exc.message}`);
    }
    throw exc;
  }
}

// ----- brain_tiers (t_3f92d3f1) ----------------------------------------------

/** Staged repair surface for identity-tier frontmatter hand-edits. */
export async function toolBrainTiers(
  ctx: ServerContext,
  args: Record<string, unknown>,
): Promise<Record<string, unknown>> {
  const op = args["operation"];
  if (op !== "check" && op !== "restore" && op !== "accept") {
    throw unknownOperationError("brain_tiers: operation must be check|restore|accept");
  }
  const searchConfig = resolveSearchConfig({
    vault: ctx.vault,
    configPath: ctx.configPath ?? undefined,
  });
  if (op === "check") {
    // Fail-soft: a vault that was never indexed has no snapshots and
    // therefore no drift - not an error.
    if (!existsSync(searchConfig.dbPath)) return { findings: [] };
    // A drift row names a page's path and both values of one of its
    // identity fields, so only the rows of pages the caller may read at
    // its reach are listed.
    const readable = readableAtContextReach(ctx);
    const store = await Store.open(searchConfig, { mode: "read" });
    try {
      return { findings: store.listTierDrift().filter((row) => readable(row.path)) };
    } finally {
      await store.close();
    }
  }
  // Same conflation as `brain_labels` above, same cure: `path` is
  // optional for `check` and required for the two write operations, and
  // "you did not send it" is a different sentence from "what you sent is
  // not a path".
  const path = requiredStringArg(`brain_tiers ${op}`, args, "path");
  if (op === "restore" && args["apply"] !== true) {
    throw new MCPError(
      INVALID_PARAMS,
      "brain_tiers restore: pass apply=true - restore writes the file",
    );
  }
  // Both remaining operations WRITE - `restore` rewrites the note's
  // frontmatter, `accept` rewrites the tier snapshot - so both answer to
  // the freeze the way every other content write does. The dispatcher
  // turns the thrown `VaultFrozenError` into the structured refusal and
  // records the attempt, so a frozen vault is not writable through this
  // surface merely because it is a repair surface.
  assertVaultIdentityForWrite(ctx.vault);
  const field = typeof args["field"] === "string" ? (args["field"] as string) : undefined;
  if (!existsSync(searchConfig.dbPath)) {
    throw new MCPError(INVALID_PARAMS, `brain_tiers ${op}: the vault has no search index yet`);
  }
  const store = await Store.open(searchConfig, { mode: "write" });
  try {
    // A page the caller may not read at its reach is refused as one the
    // index never saw, before anything about its drift is read or written.
    const docId = readableAtContextReach(ctx)(path) ? store.getDocumentIdByPath(path) : null;
    if (docId === null) {
      throw new MCPError(INVALID_PARAMS, `brain_tiers ${op}: not indexed: ${path}`);
    }
    const rows = store
      .listTierDrift()
      .filter((r) => r.documentId === docId && (field === undefined || r.field === field));
    if (rows.length === 0) {
      throw new MCPError(INVALID_PARAMS, `brain_tiers ${op}: no open drift for ${path}`);
    }
    if (op === "restore") {
      const absolute = vaultContainedPath(ctx.vault, path, "brain_tiers restore");
      const [metadata, body] = parseFrontmatter(absolute);
      const next = { ...metadata };
      for (const r of rows) {
        next[r.field] = frontmatterValueFromSnapshot(r.expected, r.field);
      }
      writeFrontmatterAtomic(absolute, next, body, { overwrite: true });
      for (const r of rows) store.clearTierDrift(docId, r.field);
      return { restored: rows.map((r) => r.field), path };
    }
    const snapshot: Record<string, unknown> = { ...store.getTierSnapshot(docId) };
    for (const r of rows) {
      snapshot[r.field] = r.actual;
      store.clearTierDrift(docId, r.field);
    }
    store.setTierSnapshot(docId, snapshot);
    return { accepted: rows.map((r) => r.field), path };
  } finally {
    await store.close();
  }
}

/** Resolve a vault-relative path, refusing traversal and symlink escapes. */
export function vaultContainedPath(vault: string, relPath: string, label: string): string {
  try {
    return resolveNotePath(vault, relPath);
  } catch (exc) {
    throw new MCPError(INVALID_PARAMS, `${label}: ${(exc as Error).message}`);
  }
}

/** Narrow a snapshot value to the shapes frontmatter can carry. */
export function frontmatterValueFromSnapshot(
  value: unknown,
  field: string,
): FrontmatterMap[string] {
  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
    return value;
  }
  if (Array.isArray(value) && value.every((v): v is string => typeof v === "string")) {
    return value;
  }
  throw new MCPError(
    INVALID_PARAMS,
    `brain_tiers restore: snapshot value for "${field}" is not a frontmatter scalar or string array`,
  );
}

// ----- brain_secrets (t_0b134404) ---------------------------------------------

/**
 * Capability-gated custody, agent-facing subset: list metadata and
 * run an allowlisted command. Deliberately NO set/get over MCP - the
 * material enters via the operator's CLI and leaves only into a
 * subprocess env.
 */
export async function toolBrainSecrets(
  ctx: ServerContext,
  args: Record<string, unknown>,
): Promise<Record<string, unknown>> {
  const op = args["operation"];
  if (op !== "list" && op !== "run") {
    throw unknownOperationError("brain_secrets: operation must be list|run");
  }
  if (op === "list") {
    return { secrets: listSecrets(ctx.vault) };
  }
  const name = args["name"];
  if (typeof name !== "string" || name.trim() === "") {
    throw new MCPError(INVALID_PARAMS, "brain_secrets run: name must be non-empty");
  }
  const command = args["command"];
  if (
    !Array.isArray(command) ||
    command.length === 0 ||
    !command.every((part): part is string => typeof part === "string")
  ) {
    throw new MCPError(
      INVALID_PARAMS,
      "brain_secrets run: command must be a non-empty array of strings",
    );
  }
  const agentArg = args["agent"];
  const agent =
    normalizeAgentArgument(typeof agentArg === "string" ? agentArg : null) ??
    resolveAgentName(ctx.configPath ?? undefined);
  try {
    const result = await runWithSecret(ctx.vault, name, command, { agent, now: new Date() });
    return { exit_code: result.exitCode, stdout: result.stdout, stderr: result.stderr };
  } catch (exc) {
    if (exc instanceof SecretExecDeniedError) {
      throw new MCPError(INVALID_PARAMS, `brain_secrets run: ${exc.message}`);
    }
    throw exc;
  }
}