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
17.9 KB
Raw Blame
/**
 * The truth tools of the knowledge family (task 3.19):
 * `brain_truth`, `brain_dead_ends` and `brain_codegraph_report`, the
 * operator and agent surfaces over the claim ledger's verdicts. Split
 * from `knowledge-tools.ts`; registration happens through that module's
 * registry, which preserves the public KNOWLEDGE_TOOLS surface.
 */

import { resolveAgentName } from "../../core/config.ts";
import { isoSecond } from "../../core/brain/time.ts";
import { normalizeAgentArgument } from "../../core/agent-identity.ts";
import { normalizeEntityName } from "../../core/brain/entities/canonical.ts";
import {
  appendStatedClaims,
  StatedClaimsRefusal,
  type StatedClaim,
} from "../../core/brain/truth/stated-claims.ts";
import { listDeadEnds, recordDeadEnd } from "../../core/brain/dead-ends.ts";
import { lanePath, laneVault } from "./lane-vault.ts";
import { buildCodegraphReport, type CodegraphReport } from "../../core/partner/codegraph-report.ts";
import { toolPath } from "./device-path.ts";
import { aggregateQuantities } from "../../core/brain/truth/aggregate.ts";
import { detectAgentCollisions } from "../../core/brain/truth/collision.ts";
import { computeTruthStateWithConflicts } from "../../core/brain/truth/conflicts.ts";
import {
  appendClaimEvent,
  ClaimWindowRefusal,
  readClaimEvents,
} from "../../core/brain/truth/store.ts";
import { claimEventLimit } from "../../core/brain/truth/events-window.ts";
import { everyArtifactRefView } from "../../core/brain/artifact-ref-view.ts";
import { gatedOwnerScopeView } from "../../core/brain/owner-scope-view.ts";
import { reachView } from "../../core/brain/reach-view.ts";
import { INVALID_PARAMS, MCPError } from "../protocol.ts";
import { contextReach, contextVault } from "../tool-contract.ts";
import type { ServerContext } from "../tool-contract.ts";
import { unknownOperationError } from "../coerce.ts";
import { vaultRelativeSafe } from "./shared.ts";
import { resolveTimeBounds } from "./time-bounds.ts";
import { readableAtContextReachOrUndefined } from "./reach-readable.ts";
import { claimEventsReport, statedClaimEntities } from "./knowledge-claim-tools.ts";

// ----- brain_context_pack (v0.10.15) ---------------------------------------

/**
 * Operator/agent surface over the entity claim ledger: ingest one
 * claim, render slots/conflicts from the fold, aggregate exact-match
 * quantities, report cross-agent collisions, recall a windowed slice of
 * the ledger via the events operation, and commit grounded agent-stated
 * claims via the state operation with per-claim anchoring verdicts. The
 * read ops are pure folds over the append-only ledger.
 */
export function toolBrainTruth(
  ctx: ServerContext,
  args: Record<string, unknown>,
): Record<string, unknown> {
  const op = args["operation"];
  if (
    op !== "ingest" &&
    op !== "slots" &&
    op !== "conflicts" &&
    op !== "aggregate" &&
    op !== "collisions" &&
    op !== "events" &&
    op !== "state"
  ) {
    throw unknownOperationError(
      "brain_truth: operation must be ingest|slots|conflicts|aggregate|collisions|events|state",
    );
  }
  const requireStr = (name: string): string => {
    const value = args[name];
    if (typeof value !== "string" || value.trim() === "") {
      throw new MCPError(INVALID_PARAMS, `brain_truth ${op}: ${name} must be a non-empty string`);
    }
    return value;
  };
  // An optional string parameter is either a string or absent; any other
  // type is refused rather than silently ignored - a mistyped bound that
  // read as "no filter" would widen what the caller sees.
  const optionalStr = (name: string): string | undefined => {
    const value = args[name];
    if (value === undefined) return undefined;
    if (typeof value !== "string") {
      throw new MCPError(INVALID_PARAMS, `brain_truth ${op}: ${name} must be a string`);
    }
    return value;
  };

  if (op === "ingest") {
    const quantityValue = args["quantity_value"];
    if (
      (quantityValue === undefined || quantityValue === null) &&
      (typeof args["quantity_unit"] === "string" || typeof args["quantity_action"] === "string")
    ) {
      throw new MCPError(
        INVALID_PARAMS,
        "brain_truth ingest: quantity_value is required when quantity_unit or quantity_action is provided",
      );
    }
    let quantity: { value: number; unit: string | null; action: string | null } | undefined;
    if (quantityValue !== undefined && quantityValue !== null) {
      if (typeof quantityValue !== "number" || !Number.isFinite(quantityValue)) {
        throw new MCPError(INVALID_PARAMS, "brain_truth ingest: quantity_value must be a number");
      }
      quantity = {
        value: quantityValue,
        unit: typeof args["quantity_unit"] === "string" ? (args["quantity_unit"] as string) : null,
        action:
          typeof args["quantity_action"] === "string" ? (args["quantity_action"] as string) : null,
      };
    }
    const agentArg = args["agent"];
    const agent =
      normalizeAgentArgument(typeof agentArg === "string" ? agentArg : null) ??
      resolveAgentName(ctx.configPath ?? undefined);
    // Declared optional validity fields (design decision 3): explicit
    // input wins outright, bound by bound, over what ingest resolves
    // from the source record's frontmatter; absent fields leave every
    // line byte-identical to the pre-window ledger.
    const validFrom = optionalStr("valid_from");
    const validUntil = optionalStr("valid_until");
    // The source's window resolves at the CALLER's reach: a source page
    // the caller cannot read is treated exactly like an absent one -
    // windowless claim, no validity keys in the response, no signal
    // distinguishing withheld from absent. Without this gate the ingest
    // response would read a withheld page's validity frontmatter back
    // and triple as an existence oracle. (The CLI verb runs at operator
    // reach and passes no gate.)
    const readable = readableAtContextReachOrUndefined(ctx);
    // The store's window refusal is strict by design; here it is a
    // mistyped parameter, so it answers as the same failure class as the
    // sibling mistyped inputs (entity, since/until, limit) - typed
    // INVALID_PARAMS, never an internal error.
    let result;
    try {
      result = appendClaimEvent(
        ctx.vault,
        {
          ts: isoSecond(new Date()),
          agent,
          entity: requireStr("entity"),
          aspect: requireStr("aspect"),
          value: requireStr("value"),
          ...(quantity !== undefined ? { valueKind: "quantity" as const, quantity } : {}),
          ...(validFrom !== undefined ? { validFrom } : {}),
          ...(validUntil !== undefined ? { validUntil } : {}),
          source: requireStr("source"),
        },
        readable !== undefined ? { readableSource: readable } : {},
      );
    } catch (exc) {
      if (exc instanceof ClaimWindowRefusal) {
        throw new MCPError(INVALID_PARAMS, `brain_truth ingest: ${(exc as Error).message}`);
      }
      throw exc;
    }
    return {
      ok: true,
      entity: result.event.entity,
      aspect: result.event.aspect,
      path: result.path,
      ...(result.event.validFrom !== undefined ? { valid_from: result.event.validFrom } : {}),
      ...(result.event.validUntil !== undefined ? { valid_until: result.event.validUntil } : {}),
    };
  }

  // Windowed recall over the ledger (truth-correctable-time-aware,
  // Task 8): the response body is the shared claimEventsReport, so the
  // CLI subcommand answers byte-identically at the same query.
  if (op === "events") {
    const bounds = resolveTimeBounds(optionalStr("since"), optionalStr("until"));
    let limit: number;
    try {
      limit = claimEventLimit(args["limit"]);
    } catch (exc) {
      throw new MCPError(INVALID_PARAMS, `brain_truth events: ${(exc as Error).message}`);
    }
    return claimEventsReport(ctx.vault, ctx.agentName, contextReach(ctx), {
      entity: optionalStr("entity"),
      sinceMs: bounds.sinceMs,
      untilMs: bounds.untilMs,
      limit,
    });
  }

  // Grounded agent-stated claims (truth-correctable-time-aware, Task 8),
  // through lane 1's grounded-claim core: the payload boundary refuses
  // WHOLE calls (unknown relation, missing text, missing source, empty
  // agent, malformed ts) before ANY write, and anchoring verdicts are
  // per claim - the one
  // partial-commit lane in this subsystem, safe because each event is an
  // independent append in an append-only ledger and the response reports
  // exactly what landed.
  if (op === "state") {
    const claims = args["claims"];
    if (!Array.isArray(claims) || claims.length === 0) {
      throw new MCPError(INVALID_PARAMS, "brain_truth state: claims must be a non-empty array");
    }
    const stated = claims.map((raw, index): StatedClaim => {
      if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
        throw new MCPError(INVALID_PARAMS, `brain_truth state: claims[${index}] must be an object`);
      }
      const claim = raw as Record<string, unknown>;
      // Type-shaped fields only; an empty subject or object is not a
      // refusal here but a per-claim ungrounded verdict downstream.
      const readField = (name: string): string => {
        const value = claim[name];
        if (typeof value !== "string") {
          throw new MCPError(
            INVALID_PARAMS,
            `brain_truth state: claims[${index}].${name} must be a string`,
          );
        }
        return value;
      };
      return {
        subject: readField("subject"),
        relation: readField("relation"),
        object: readField("object"),
      };
    });
    const agentArg = args["agent"];
    if (agentArg !== undefined && typeof agentArg !== "string") {
      throw new MCPError(INVALID_PARAMS, "brain_truth state: agent must be a string");
    }
    const agent =
      normalizeAgentArgument(typeof agentArg === "string" ? agentArg : null) ??
      resolveAgentName(ctx.configPath ?? undefined);
    // Sample id (answer-trust, task B4): an optional call-level id naming
    // the recall/context-pack quality-sample these claims were stated
    // against. A non-string type is refused here as a mistyped parameter;
    // a blank string flows to the payload boundary's named refusal below
    // (mapped to the same failure class), so an empty id is never coerced
    // to an absent one. Committed events echo the id verbatim.
    const sampleId = optionalStr("sample_id");
    // The source's frontmatter window resolves at the CALLER's reach,
    // exactly as ingest gates it: a withheld source freezes a windowless
    // event and the committed rows carry no validity keys, so the state
    // response reads a withheld page's frontmatter no more than an
    // absent one's.
    const readable = readableAtContextReachOrUndefined(ctx);
    try {
      const outcome = appendStatedClaims(
        ctx.vault,
        {
          claims: stated,
          text: requireStr("text"),
          agent,
          ts: isoSecond(new Date()),
          source: requireStr("source"),
          ...(sampleId !== undefined ? { sampleId } : {}),
        },
        {
          entities: statedClaimEntities(ctx.vault),
          ...(ctx.configPath !== null ? { configPath: ctx.configPath } : {}),
          ...(readable !== undefined ? { readableSource: readable } : {}),
        },
      );
      return {
        ok: true,
        operation: "state",
        committed: outcome.committed.map((result) => ({ ...result.event })),
        ungrounded: outcome.ungrounded.map(({ claim, reasons }) => ({
          subject: claim.subject,
          relation: claim.relation,
          object: claim.object,
          reasons,
        })),
      };
    } catch (exc) {
      // Both refusal channels are mistyped-input refusals - the payload
      // boundary's, and the store's when the stated claim's window
      // resolves from the source record's frontmatter and inverts there
      // - so both answer as the same failure class the ingest operation
      // maps, never an internal error.
      if (exc instanceof StatedClaimsRefusal || exc instanceof ClaimWindowRefusal) {
        throw new MCPError(INVALID_PARAMS, `brain_truth state: ${exc.message}`);
      }
      throw exc;
    }
  }

  // The fold operations answer at the caller's view, the same one the
  // events operation applies to its rows: slots, conflicts, aggregates
  // and collisions all name claim values, quantities, agents and source
  // paths, so an unfiltered fold would hand a narrower caller what
  // `events` withholds. The filter is applied BEFORE the fold - the
  // identical-to-absent convention the views hold everywhere else - so a
  // claim from a source the caller cannot read is absent from the slots,
  // the totals and the collision pairs alike, exactly as it is from the
  // event list.
  const view = everyArtifactRefView(
    gatedOwnerScopeView(ctx.vault, ctx.agentName),
    reachView(ctx.vault, contextReach(ctx)),
  );
  const allEvents = readClaimEvents(ctx.vault).events;
  const events = view.filtersNothing ? allEvents : allEvents.filter((e) => view.row(e.source));
  if (op === "slots" || op === "conflicts") {
    const state = computeTruthStateWithConflicts(events);
    if (op === "conflicts") return { events: state.events, conflicts: state.conflicts };
    const entityFilter = args["entity"];
    const slots =
      typeof entityFilter === "string" && entityFilter.trim() !== ""
        ? state.slots.filter((s) => s.entity === normalizeEntityName(entityFilter))
        : state.slots;
    return { events: state.events, slots };
  }
  if (op === "aggregate") {
    const state = computeTruthStateWithConflicts(events);
    return {
      ...aggregateQuantities(state.slots, {
        ...(typeof args["action"] === "string" ? { action: args["action"] as string } : {}),
        unit: typeof args["unit"] === "string" ? (args["unit"] as string) : null,
        ...(typeof args["entity"] === "string" ? { entity: args["entity"] as string } : {}),
      }),
    };
  }
  return {
    collisions: detectAgentCollisions(events, { now: new Date() }),
  };
}

// ----- brain_concept_synthesis (v0.10.17) ----------------------------------

/**
 * Negative-knowledge registry: record one tried-and-failed approach
 * or list the bounded active set, newest first.
 */
export function toolBrainDeadEnds(
  ctx: ServerContext,
  args: Record<string, unknown>,
): Record<string, unknown> {
  const op = args["operation"];
  if (op !== "record" && op !== "list") {
    throw unknownOperationError("brain_dead_ends: operation must be record|list");
  }
  // A dead-end page the caller cannot read at its reach is treated as
  // absent: `list` leaves it out of the entries and the warnings.
  const readable = readableAtContextReachOrUndefined(ctx);
  const vault = laneVault(ctx);
  if (op === "list") {
    const listed = listDeadEnds(vault);
    // With no vault a dead-end page is a store record: named `Brain/...`.
    const named = <T extends { path: string }>(row: T): T =>
      contextVault(ctx) === null ? { ...row, path: lanePath(ctx, row.path) } : row;
    // The reach filter judges the absolute paths, before any is renamed:
    // a renamed `Brain/...` path would resolve against the working
    // directory, not the vault.
    const shown = (row: { path: string }): boolean =>
      readable === undefined || readable(vaultRelativeSafe(vault, row.path));
    return {
      entries: listed.entries.filter(shown).map(named),
      warnings: listed.warnings.filter(shown).map(named),
    };
  }
  const approach = args["approach"];
  const reason = args["reason"];
  if (typeof approach !== "string" || approach.trim() === "") {
    throw new MCPError(INVALID_PARAMS, "brain_dead_ends record: approach must be non-empty");
  }
  if (typeof reason !== "string" || reason.trim() === "") {
    throw new MCPError(INVALID_PARAMS, "brain_dead_ends record: reason must be non-empty");
  }
  const agentArg = args["agent"];
  const agent =
    normalizeAgentArgument(typeof agentArg === "string" ? agentArg : null) ??
    resolveAgentName(ctx.configPath ?? undefined);
  const result = recordDeadEnd(vault, {
    approach,
    reason,
    ...(typeof args["context"] === "string" ? { context: args["context"] as string } : {}),
    agent,
    now: new Date(),
    ...(readable !== undefined ? { readable } : {}),
  });
  // The overflow trim walks every active dead end, so below local reach the
  // ids it archived are left out: they would name or count withheld pages.
  // It archives only pages the caller can read; a withheld one stays put.
  return {
    ok: true,
    id: result.entry.id,
    path: contextVault(ctx) === null ? lanePath(ctx, result.entry.path) : result.entry.path,
    ...(readable === undefined ? { archived: result.archived } : {}),
  };
}

// ----- brain_codegraph_report (t_a1e76788) -----------------------------------

/**
 * Read-only codegraph partner report: index status plus structural Cargo
 * workspace membership. Never installs, initializes, extracts, or mutates a
 * partner index or the vault - a missing CLI, missing index, or non-Rust
 * project are honest report states, not errors.
 */
export function toolBrainCodegraphReport(
  ctx: ServerContext,
  _args: Record<string, unknown>,
): Record<string, unknown> {
  const report = buildCodegraphReport({ cwd: process.cwd(), vault: ctx.vault });
  // The CLI binary, the project and the Cargo manifest are host paths
  // that may sit outside every root the server's egress pass knows (a
  // package manager's bin folder, a checkout under /srv): each is named
  // at the caller's reach here, as `toolPath` names any host path.
  const at = (path: string): string => toolPath(ctx, path);
  const named: CodegraphReport = {
    ...report,
    project: report.project === null ? null : at(report.project),
    cli: { ...report.cli, path: report.cli.path === null ? null : at(report.cli.path) },
    cargo_workspace:
      report.cargo_workspace === null
        ? null
        : { ...report.cargo_workspace, manifestPath: at(report.cargo_workspace.manifestPath) },
  };
  return named as unknown as Record<string, unknown>;
}