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
8.9 KB
Raw Blame
/**
 * Tension-object lifecycle MCP tool (Belief lifecycle suite, S2,
 * t_0e3f2bee).
 *
 * One tool, `brain_tension`, dispatching on `action`:
 *   - `detect`    scan the note corpus and persist detected contradictions
 *   - `list`      list persisted tensions (optionally unresolved only)
 *   - `show`      read one tension
 *   - `confirm`   open -> confirmed
 *   - `dismiss`   open|confirmed -> dismissed
 *   - `resolve`   open|confirmed -> resolved
 *   - `verify`    read-only: an advisory decision-model verdict per
 *                 tension (one slug, or every unresolved tension); needs
 *                 the optional `tension` decision-model use
 *
 * MCP mirror of the `o2b brain tension` CLI verb; both delegate to the
 * core tensions module so the on-disk shape cannot drift.
 */

import {
  confirmTension,
  detectTensionsInVault,
  dismissTension,
  listTensions,
  listUnresolvedTensions,
  resolveTension,
  showTension,
  TensionError,
  type TensionRecord,
} from "../../core/brain/tensions.ts";
import { verifyTensions } from "../../core/brain/tension-verdicts.ts";
import { verdictFields } from "../../core/decision-model/pair-verdict.ts";
import { vaultRelative } from "../../core/path-safety.ts";
import { INVALID_PARAMS, MCPError } from "../protocol.ts";
import { MCP_PREVIEW_BUDGET } from "../preview-budget.ts";
import type { ServerContext, ToolDefinition } from "../tool-contract.ts";
import { coerceBool, coerceStr, unknownOperationError } from "../coerce.ts";
import { readableAtContextReachOrUndefined, type ReadablePredicate } from "./reach-readable.ts";
import { wrapToolErrors } from "./shared.ts";
import { laneVault, vaultForNoteAction } from "./lane-vault.ts";

const TOOL = "brain_tension";

/** Project a tension record into the tool's snake_cased response shape. */
function renderRow(t: TensionRecord): Record<string, unknown> {
  return {
    id: t.id,
    slug: t.slug,
    status: t.status,
    subject_a: t.subjectA,
    subject_b: t.subjectB,
    stance_a: t.stanceA,
    stance_b: t.stanceB,
    detected_count: t.detectedCount,
    resolution_reason: t.resolutionReason,
  };
}

/**
 * May the caller read this tension page? The page carries the stricter
 * `visibility:` of its two source notes, so the page's own rule is the
 * notes' rule. `readable` undefined withholds nothing.
 */
function tensionReadable(
  vault: string,
  readable: ReadablePredicate | undefined,
  t: TensionRecord,
): boolean {
  return readable === undefined || readable(vaultRelative(t.path, vault));
}

/**
 * One tension by slug, or a typed `no tension` error when it is absent
 * or withheld from the caller: the two answer alike, so the error does
 * not confirm the page exists.
 */
function readableTension(
  vault: string,
  readable: ReadablePredicate | undefined,
  slug: string,
): TensionRecord {
  const t = showTension(vault, slug);
  if (t === null || !tensionReadable(vault, readable, t)) {
    throw new TensionError(`no tension: ${slug}`);
  }
  return t;
}

async function toolBrainTension(
  ctx: ServerContext,
  args: Record<string, unknown>,
): Promise<Record<string, unknown>> {
  return wrapToolErrors(TOOL, [TensionError], async () => {
    const action = coerceStr(args, "action", true)!;
    const agent = coerceStr(args, "agent", false) ?? undefined;
    const reason = coerceStr(args, "reason", false) ?? undefined;
    // Every action answers at the caller's reach: detect reads only the
    // notes it may read, and a tension page it may not read is left out
    // of list and verify and answered as absent by show and the
    // transitions, before anything is written.
    const readable = readableAtContextReachOrUndefined(ctx);
    // A record-lane tool works with no vault: its pages are store records
    // then; detect alone reads the vault's notes and needs one.
    const vault = laneVault(ctx);
    const visible = (rows: ReadonlyArray<TensionRecord>): TensionRecord[] =>
      rows.filter((t) => tensionReadable(vault, readable, t));

    switch (action) {
      case "detect":
      case "scan": {
        const rawJaccard = args["jaccard"];
        let jaccard: number | undefined;
        if (rawJaccard !== undefined && rawJaccard !== null) {
          if (typeof rawJaccard !== "number" || !Number.isFinite(rawJaccard)) {
            throw new MCPError(INVALID_PARAMS, `${TOOL}: 'jaccard' must be a number`);
          }
          if (rawJaccard <= 0 || rawJaccard > 1) {
            throw new MCPError(INVALID_PARAMS, `${TOOL}: 'jaccard' must be in (0, 1]`);
          }
          jaccard = rawJaccard;
        }
        const res = detectTensionsInVault(vaultForNoteAction(ctx, "brain_tension action=detect"), {
          ...(jaccard !== undefined ? { jaccard } : {}),
          ...(agent ? { agent } : {}),
          ...(readable !== undefined ? { readable } : {}),
        });
        return {
          action,
          created: res.created,
          updated: res.updated,
          scanned_files: res.scannedFiles,
          tensions: res.records.map(renderRow),
        };
      }
      case "list": {
        const unresolved = coerceBool(args, "unresolved");
        const rows = unresolved ? listUnresolvedTensions(vault) : listTensions(vault);
        return { action, tensions: visible(rows).map(renderRow) };
      }
      case "show": {
        const slug = coerceStr(args, "slug", true)!;
        const t = readableTension(vault, readable, slug);
        return {
          action,
          ...renderRow(t),
          subject: t.subject,
          jaccard: t.jaccard,
          quote_a: t.quoteA,
          quote_b: t.quoteB,
          created_at: t.createdAt,
          detected_at: t.detectedAt,
          status_changed_at: t.statusChangedAt,
        };
      }
      case "confirm":
      case "dismiss":
      case "resolve": {
        const slug = coerceStr(args, "slug", true)!;
        const opts = {
          ...(reason ? { reason } : {}),
          ...(agent ? { agent } : {}),
        };
        const fn =
          action === "confirm"
            ? confirmTension
            : action === "dismiss"
              ? dismissTension
              : resolveTension;
        readableTension(vault, readable, slug);
        const t = fn(vault, slug, opts);
        return { action, ...renderRow(t) };
      }
      case "verify": {
        // The verdicts quote the subject notes, so they need the user's
        // vault: refused first, whatever the other arguments name.
        vaultForNoteAction(ctx, "brain_tension action=verify");
        const slug = coerceStr(args, "slug", false);
        let records: TensionRecord[];
        if (slug) {
          records = [readableTension(vault, readable, slug)];
        } else {
          records = visible(listUnresolvedTensions(vault));
        }
        const verified = await verifyTensions(vault, records, { configPath: ctx.configPath });
        return {
          action,
          available: verified.available,
          ...(verified.available ? { mode: verified.mode } : { reason: verified.reason }),
          tensions: verified.rows.map((row) => ({ ...renderRow(row.item), ...verdictFields(row) })),
        };
      }
      default:
        throw unknownOperationError(
          `${TOOL}: 'action' must be one of detect, list, show, confirm, dismiss, resolve, verify`,
        );
    }
  });
}

export const TENSION_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([
  {
    name: TOOL,
    kind: "write",
    description:
      "Persisted-contradiction (tension) lifecycle. detect persists contradictions from notes.read_paths as open tensions (idempotent); list/show read; confirm, dismiss, resolve transition. verify: read-only advisory verdict from the optional tension decision-model use; never changes a tension.",
    inputSchema: {
      type: "object",
      properties: {
        action: {
          type: "string",
          enum: ["detect", "list", "show", "confirm", "dismiss", "resolve", "verify"],
          description: "Which tension operation to run.",
        },
        slug: {
          type: "string",
          description:
            "show/confirm/dismiss/resolve: the tension slug. verify: optional; without it every unresolved tension is verified.",
        },
        jaccard: {
          type: "number",
          description:
            "detect: minimum prose token overlap (0, 1] for two notes to count as the same subject. Defaults to the shared health threshold.",
        },
        unresolved: {
          type: "boolean",
          description: "list: return only open/confirmed (unresolved) tensions.",
        },
        reason: {
          type: "string",
          description: "dismiss/resolve: operator reason recorded on the transition.",
        },
        agent: {
          type: "string",
          description: "Optional agent identity override; defaults to the server-resolved name.",
        },
      },
      required: ["action"],
      additionalProperties: false,
    },
    previewBudget: MCP_PREVIEW_BUDGET,
    handler: toolBrainTension,
  },
]);