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
9.0 KB
Raw Blame
/**
 * Source-distillation tool (Ingestion & Import Robustness suite, t_2e2e959f).
 *
 * The calling agent reads a source and distills it into atomic claims, each
 * with an optional block id pointing back to the source block it came from,
 * and submits them here. Open Second Brain runs no model - it validates the
 * claims, checks every quoted span in them against the cited block or the
 * source, and writes one idempotent distillation page per source, listing
 * each claim with its block-level citation and a provenance section. The
 * response names the capture scope and, when spans were checked, the quotes
 * report; `strict_quotes` turns an unverified span into a refusal carrying
 * the `quote_unverified` wire code.
 */

import {
  DISTILL_CLAIMS_MAX,
  distillSource,
  DistillValidationError,
  parseDistillClaims,
  type DistillSourceInput,
  type DistillSourceOptions,
  type DistillSourceResult,
} from "../../core/brain/distill/distill-source.ts";
import { QuoteCheckError } from "../../core/brain/distill/quote-verdict.ts";
import {
  CAPTURE_EXCERPT_MAX_BYTES,
  CaptureExcerptError,
} from "../../core/brain/provenance/capture-scope.ts";
import { ResponseShapeError } from "../../core/brain/response-shape.ts";
import { resolveAgentName } from "../../core/config.ts";
import { coerceBoolOptional, coerceStr } from "../coerce.ts";
import { INVALID_PARAMS, MCPError } from "../protocol.ts";
import type { ServerContext, ToolDefinition } from "../tool-contract.ts";
import { readableAtContextReach } from "./reach-readable.ts";
import { wrapToolErrors } from "./shared.ts";

const TOOL = "brain_distill_source";
const EXCERPT_ARG = "excerpt";

async function toolBrainDistillSource(
  ctx: ServerContext,
  args: Record<string, unknown>,
): Promise<Record<string, unknown>> {
  const sourcePath = coerceStr(args, "source_path", true)!;
  const agentArg = coerceStr(args, "agent", false);
  const agent =
    agentArg && agentArg.trim().length > 0
      ? agentArg
      : resolveAgentName(ctx.configPath ?? undefined);

  const excerpt = readExcerptArg(args);
  const strictQuotes = coerceBoolOptional(args, "strict_quotes") ?? false;

  return wrapToolErrors(
    TOOL,
    [DistillValidationError, ResponseShapeError, CaptureExcerptError],
    async () => {
      // Shape first: the payload is validated before a single claim is
      // normalized, so a malformed item aborts the whole batch unwritten.
      const claims = parseDistillClaims(args["claims"]);
      const res = distillWithQuoteCode(
        ctx.vault,
        { sourcePath, claims, ...(excerpt !== undefined ? { excerpt } : {}) },
        // The quote check reads the source's bytes on the caller's behalf, so
        // it answers only for a page the caller may read at its reach.
        { agent, now: new Date(), strictQuotes, readable: readableAtContextReach(ctx) },
      );
      return {
        distillation_path: res.distillationPath,
        created: res.created,
        claim_count: res.claimCount,
        // Omitted rather than reported as a sentinel when the source had no
        // bytes to hash: an absent key reads as "not recorded", where the
        // `missing` string this used to return read as a digest until you knew
        // better.
        ...(res.sourceHash !== undefined ? { source_hash: res.sourceHash } : {}),
        // The lane the page ACTUALLY landed in. Classifying the source a second
        // time here would be a second answer to one question, free to disagree
        // with the write that already happened.
        trust: res.trust,
        // How much of the source the page holds. Always present, like `trust`.
        capture_scope: res.captureScope,
        // Only when a claim held a quoted span: absence means nothing was
        // quoted, never "checked and clean" (that is `unquoted: 0`).
        ...(res.quotes !== undefined ? { quotes: res.quotes } : {}),
      };
    },
  );
}

/**
 * The `excerpt` argument, verbatim. `coerceStr` folds a blank string into
 * "absent", which would turn an empty excerpt into a silent no-op; the core
 * refuses an empty one by name, so the bytes are passed through untouched
 * and only a non-string is rejected here.
 */
function readExcerptArg(args: Record<string, unknown>): string | undefined {
  const raw = args[EXCERPT_ARG];
  if (raw === undefined || raw === null) return undefined;
  if (typeof raw !== "string") {
    throw new MCPError(INVALID_PARAMS, `${TOOL}: argument '${EXCERPT_ARG}' must be a string`);
  }
  return raw;
}

/**
 * Run the distillation, answering a strict quote refusal with its registered
 * wire code. `wrapToolErrors` folds a validation class into a bare
 * `INVALID_PARAMS` and drops any data, so this one class is mapped here,
 * where the code is still in hand; every other error keeps the shared path.
 */
function distillWithQuoteCode(
  vault: string,
  input: DistillSourceInput,
  opts: DistillSourceOptions,
): DistillSourceResult {
  try {
    return distillSource(vault, input, opts);
  } catch (err) {
    if (err instanceof QuoteCheckError) {
      throw new MCPError(INVALID_PARAMS, `${TOOL}: ${err.message}`, { code: err.code });
    }
    throw err;
  }
}

export const DISTILL_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([
  {
    name: TOOL,
    kind: "write",
    // The guarantee is stated here, in the idiom `brain_intake_entities` uses:
    // a caller choosing a tool reads this, and a write that quarantines what it
    // just wrote must say so where the choice is made.
    //
    // It is stated CONDITIONALLY, and the condition is named. This sentence
    // used to assert that the page was "excluded from ordinary reads", which
    // was false on a default install: the exclusion is `trustGateAdjuster`,
    // which `search/pipeline/post-rank.ts` mounts only when
    // `recall.retrievalTrustGateEnabled` is set, and that flag falls back to
    // `false`. The marker is written correctly and `classifyRetrievalTrust`
    // reads it correctly - nothing mounts the gate.
    //
    // Making it true by default was the other option and is not taken here.
    // Flipping the flag turns on three signals at once, changes the search
    // result shape (the trust receipts stop being null), the cache slot key and
    // the explain envelope - a release-wide decision that does not belong to a
    // tool description. Mounting a partial gate for this one signal would
    // exclude pages with no receipt to say so, which is the silent drop this
    // project forbids. So the limit is admitted instead, with the setting
    // named, and `tests/cli/distill-trust-lane.test.ts` proves both halves:
    // the default returns the page, the setting stops returning it.
    //
    // Note the asymmetry with `brain_intake_entities`, whose quarantine holds
    // by DEFAULT: it works through `status: quarantine` plus the entity page
    // status scope, which nothing gates. The same words mean less here.
    //
    // Session-mining-economy: the legacy boolean still mounts the gate in
    // the excluding mode, and an explicit `search_trust_gate_mode: enforce`
    // does the same; `shadow` measures without excluding. The description
    // states both keys.
    description:
      "Distill one source into atomic claims; runs no model, checks quotes. Writes an idempotent page citing each claim as `[[source#^block]]`. `untrusted_source` pages surface unless the gate enforces (`search_trust_gate_enabled: true` or `search_trust_gate_mode: enforce`). `trust` names the lane.",
    inputSchema: {
      type: "object",
      properties: {
        source_path: {
          type: "string",
          description: "Source identity: a vault-relative path or a URL.",
        },
        claims: {
          type: "array",
          description: `Atomic claims distilled from the source, each one line (1 to ${DISTILL_CLAIMS_MAX}).`,
          items: {
            type: "object",
            properties: {
              text: { type: "string", description: "The atomic claim text." },
              block: {
                type: "string",
                description: "Optional source block id the claim was drawn from (the `^abc` id).",
              },
            },
            required: ["text"],
            additionalProperties: false,
          },
        },
        strict_quotes: {
          type: "boolean",
          description:
            "Refuse the write (code quote_unverified) when a quoted span fails the check; by default the span is unquoted and reported.",
        },
        excerpt: {
          type: "string",
          // Characters, a necessary bound on the byte cap the core enforces.
          maxLength: CAPTURE_EXCERPT_MAX_BYTES,
          description: `Verbatim text read from a url-only source; stored on the page as bounded-local and used to check quotes. At most ${CAPTURE_EXCERPT_MAX_BYTES} bytes.`,
        },
        agent: {
          type: "string",
          description: "Optional agent identity override; defaults to the server-resolved name.",
        },
      },
      required: ["source_path", "claims"],
      additionalProperties: false,
    },
    handler: toolBrainDistillSource,
  },
]);