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.3 KB
Raw Blame
/**
 * `o2b brain bridges discover|list|accept|dismiss` (t_ab540afe):
 * bridge discovery over the vec index. `discover` regenerates the
 * reviewable `Brain/proposals/bridges.md` artifact and records one
 * `bridge_discovery` metric; `accept` writes a single `related:`
 * wikilink into the source note; `dismiss` silences a pair across
 * future runs. Fail-soft on a missing index or vec layer - the verb
 * reports why and exits 0 so cron wrappers stay quiet.
 *
 * Exit codes: 0 on success/fail-soft skip, 1 on an operational
 * failure, 2 on usage errors.
 */

import { join } from "node:path";

import {
  acceptBridge,
  bridgePairKey,
  discoverBridges,
  dismissBridge,
  readDismissedBridges,
  writeBridgeProposals,
  BRIDGE_DEFAULT_MAX_PROPOSALS,
  BRIDGE_DEFAULT_MIN_SIMILARITY,
} from "../../../core/brain/link-graph/bridge-discovery.ts";
import { appendMetric } from "../../../core/brain/metrics.ts";
import {
  createSafeguard,
  OPERATION,
  resolveSafeguardTimeoutMs,
  SafeguardTimeoutError,
} from "../../../core/brain/safeguard.ts";
import { loadSchemaPack } from "../../../core/brain/schema-pack.ts";
import { isoSecond } from "../../../core/brain/time.ts";
import { resolveSearchConfig } from "../../../core/search/index.ts";
import { Store } from "../../../core/search/store.ts";
import { SearchError } from "../../../core/search/types.ts";
import { emitNextStep, type AdvisoryStream } from "../../advisory-rail.ts";
import { attachProgress, reportProgressRefusal } from "../../progress-rail.ts";
import { nextCommandField } from "../../../core/brain/next-step.ts";
import { brainVerbContext, fail, ok, okJson, parse } from "../helpers.ts";
import { lanePageExists, parseLanePage } from "../../../core/store/lane-pages.ts";

const USAGE =
  "usage: o2b brain bridges discover [--max N] [--min-similarity X] [--progress] | list | " +
  "accept <source> <target> | dismiss <source> <target>  [--vault <path>] [--json]";

export async function cmdBrainBridges(argv: string[]): Promise<number> {
  const { flags, positional } = parse(argv, {
    vault: { type: "string" },
    max: { type: "string" },
    "min-similarity": { type: "string" },
    progress: { type: "boolean" },
    json: { type: "boolean" },
  });
  const asJson = flags["json"] === true;
  // no-dead-ends, task 5: both fail-soft exits below used to carry their
  // own `- run: <command>` tail inside the status line. They resolve
  // through the registry now, so the command is written down once.
  const stream: AdvisoryStream = { command: "brain", argv, jsonRequested: asJson };
  const action = positional[0];
  if (
    action === undefined ||
    !["discover", "list", "accept", "dismiss"].includes(action) ||
    ((action === "accept" || action === "dismiss") && positional.length !== 3) ||
    ((action === "discover" || action === "list") && positional.length !== 1)
  ) {
    process.stderr.write(`${USAGE}\n`);
    return 2;
  }

  const { config, vault } = brainVerbContext(flags);

  try {
    if (action === "accept") {
      const pack = loadSchemaPack(vault);
      const result = acceptBridge(vault, positional[1]!, positional[2]!, { pack });
      if (asJson) okJson({ ...result, source: positional[1], target: positional[2] });
      else if (result.changed) ok(`bridge accepted: related now ${result.related.join(", ")}`);
      else ok("bridge already accepted (related target present)");
      return 0;
    }

    if (action === "dismiss") {
      const added = dismissBridge(vault, positional[1]!, positional[2]!);
      if (asJson) {
        okJson({ dismissed: bridgePairKey(positional[1]!, positional[2]!), added });
      } else ok(added ? "bridge dismissed" : "bridge was already dismissed");
      return 0;
    }

    if (action === "list") {
      const path = join(vault, "Brain", "proposals", "bridges.md");
      if (!lanePageExists(vault, path)) {
        // no-dead-ends, phase 3: the rail suppresses its line here and
        // returns the step so this payload can carry it. Nothing did.
        if (asJson) {
          okJson({ exists: false, proposals: 0, ...nextCommandField("bridge-proposals-absent") });
        } else ok("no proposals artifact yet");
        // no-dead-ends, task 5: the exit is this verb's own producer.
        emitNextStep("bridge-proposals-absent", stream);
        return 0;
      }
      const [meta, body] = parseLanePage(vault, path);
      if (asJson) {
        okJson({
          exists: true,
          path: "Brain/proposals/bridges.md",
          generated_at: meta["generated_at"] ?? null,
          proposals: Number(meta["proposals"] ?? 0),
        });
      } else ok(body);
      return 0;
    }

    // discover
    const max = parsePositiveInt(flags["max"] as string | undefined);
    const minSimilarity = parseFraction(flags["min-similarity"] as string | undefined);
    if (max === false || minSimilarity === false) {
      process.stderr.write(
        "brain bridges discover: --max must be a positive integer, --min-similarity in (0, 1]\n",
      );
      return 2;
    }

    const searchConfig = resolveSearchConfig({ vault, configPath: config ?? undefined });
    let store: Store;
    try {
      store = await Store.open(searchConfig, { mode: "read" });
    } catch (exc) {
      if (
        exc instanceof SearchError &&
        (exc.code === "INDEX_MISSING" || exc.code === "SCHEMA_MISMATCH")
      ) {
        if (asJson) {
          okJson({
            vec_available: false,
            proposals: [],
            reason: "index not built",
            ...nextCommandField("search-index-missing"),
          });
        } else ok("bridges discover: search index not initialised");
        // no-dead-ends, task 5: fail-soft, but not silent about the fix.
        emitNextStep("search-index-missing", stream);
        return 0;
      }
      throw exc;
    }

    const now = new Date();
    // Progress is opt-in: attaching a sink by default would change the
    // stderr of every existing invocation, and this CLI's one streaming
    // precedent (`o2b search index --verbose`) is opt-in for the same
    // reason. The rail decides whether the stream can carry it at all.
    const observation =
      flags["progress"] === true
        ? attachProgress({ command: "brain", argv: ["bridges"], jsonRequested: asJson })
        : null;
    reportProgressRefusal(observation);
    // No interrupt handle: `discoverBridgesRun` is synchronous end to end,
    // so a signal handler cannot run while it does (see `interrupt.ts`).
    // Leaving SIGINT alone keeps the keystroke lethal, which is the only
    // way this scan can actually be stopped. Proposals are written in one
    // atomic write after the scan, so a killed run leaves no half file.
    try {
      const dismissed = readDismissedBridges(vault);
      const report = discoverBridges(store, {
        ...(max !== undefined ? { maxProposals: max } : {}),
        ...(minSimilarity !== undefined ? { minSimilarity } : {}),
        dismissed,
        safeguard: createSafeguard({
          operation: OPERATION.bridges,
          timeoutMs: resolveSafeguardTimeoutMs(OPERATION.bridges, config ?? undefined),
        }),
        ...(observation?.sink !== undefined ? { onProgress: observation.sink } : {}),
      });
      const path = writeBridgeProposals(vault, report, { now });
      try {
        appendMetric(vault, {
          surface: "bridge_discovery",
          runAt: isoSecond(now),
          payload: {
            proposals: report.proposals.length,
            scanned_candidates: report.scannedCandidates,
            vec_available: report.vecAvailable,
            dismissed_total: dismissed.size,
            min_similarity: minSimilarity ?? BRIDGE_DEFAULT_MIN_SIMILARITY,
            max_proposals: max ?? BRIDGE_DEFAULT_MAX_PROPOSALS,
          },
        });
      } catch {
        // Metrics are observability, not correctness.
      }
      if (asJson) {
        okJson({
          vec_available: report.vecAvailable,
          ...(report.reason !== undefined ? { reason: report.reason } : {}),
          scanned_candidates: report.scannedCandidates,
          proposals: report.proposals,
          artifact: "Brain/proposals/bridges.md",
        });
      } else if (!report.vecAvailable) {
        ok(`bridges discover: ${report.reason ?? "vec layer unavailable"}`);
      } else if (report.proposals.length === 0) {
        ok("bridges discover: no new bridge proposals");
      } else {
        ok(`bridges discover: ${report.proposals.length} proposal(s) -> ${path}`);
        for (const p of report.proposals) {
          ok(`  ${p.source} <-> ${p.target}  sim=${p.similarity.toFixed(3)}`);
        }
      }
      return 0;
    } finally {
      await store.close();
    }
  } catch (exc) {
    const timedOut = exc instanceof SafeguardTimeoutError;
    const message = `bridges ${action} failed: ${(exc as Error).message ?? exc}`;
    if (asJson) {
      okJson({ ok: false, message, ...(timedOut ? { timed_out: true } : {}) });
      return 1;
    }
    return fail(message);
  }
}

function parsePositiveInt(raw: string | undefined): number | undefined | false {
  if (raw === undefined) return undefined;
  const n = Number(raw);
  return Number.isInteger(n) && n > 0 ? n : false;
}

function parseFraction(raw: string | undefined): number | undefined | false {
  if (raw === undefined) return undefined;
  const n = Number(raw);
  return Number.isFinite(n) && n > 0 && n <= 1 ? n : false;
}