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
/**
 * The maintenance lane's task list, built once for both front doors
 * (`o2b brain maintenance run` and the `brain_maintenance` MCP tool).
 *
 * The two surfaces carried the same four task bodies inline, and the
 * copies drifted. This builder owns them now: the four built-ins in their
 * registration order ({@link LANE_TASKS}), then the install-owned custom
 * tasks the machine config declares, when the master switch is on. What
 * differs per surface arrives by injection: the per-task safeguard (built
 * lazily, so each deadline starts when its task starts), the abort
 * signal, the progress sink and the spend banner.
 *
 * `taskNames` is the registered vocabulary both surfaces validate
 * `--retry`/`retry_tasks` against, and `custom.errors` carries every
 * refused declaration by name for the surface to report.
 */

import { dream } from "../dream.ts";
import { decideBudgetWithin, prepareTopicVerdicts } from "../../topics/decide-auto.ts";
import {
  discoverBridges,
  readDismissedBridges,
  writeBridgeProposals,
} from "../link-graph/bridge-discovery.ts";
import { detectCommunities, materializeClusterNotes } from "../link-graph/communities.ts";
import { appendMetric } from "../metrics.ts";
import type { ProgressSink } from "../progress.ts";
import type { Safeguard } from "../safeguard.ts";
import { isoSecond } from "../time.ts";
import type { EmbeddingSpendPreview } from "../../search/indexer.ts";
import { Store } from "../../search/store.ts";
import type { ResolvedSearchConfig } from "../../search/types.ts";
import {
  createCustomLaneTask,
  resolveCustomTasks,
  type CustomTaskResolution,
} from "./custom-tasks.ts";
import { LANE_TASK, type LaneTask, type LaneTaskId, type MaintenanceTask } from "./lane.ts";
import { createLaneReindex, type LaneReindex } from "./reindex-task.ts";
import { runRelinkAnchors, type RelinkAnchorsReport } from "./relink-anchors-task.ts";

export interface LaneTaskBuildOptions {
  readonly vault: string;
  readonly configPath?: string;
  readonly searchConfig: ResolvedSearchConfig;
  readonly now: Date;
  /** Bypass a positive embedding cost gate for this run (`--force-cost`). */
  readonly forceCost: boolean;
  /**
   * Apply the relink pass: rewrite the changed signal pages' anchor
   * lines. Absent or false, the lane's relink task is the dry run - it
   * reports what it would add and writes nothing - because every other
   * pass an unattended lane runs through a cron produces no new writes
   * without an explicit ask. The apply arm carries the run's own
   * vault-identity write guard.
   */
  readonly relinkApply?: boolean;
  /** One fresh deadline per built-in task, called when that task starts. */
  readonly safeguardFor: (operation: LaneTask) => Safeguard;
  readonly signal?: AbortSignal;
  readonly onProgress?: ProgressSink;
  /** Called once with the reindex spend preview, before the pass, when there is one. */
  readonly onBanner?: (preview: EmbeddingSpendPreview) => void;
}

export interface LaneTaskSet {
  readonly tasks: ReadonlyArray<MaintenanceTask>;
  readonly reindex: LaneReindex;
  /** Every registered identity, in registration order. */
  readonly taskNames: ReadonlyArray<LaneTaskId>;
  readonly custom: CustomTaskResolution;
  /**
   * The relink pass's report for the run dispatched through this set, or
   * `undefined` while the task has not completed: the preview on the
   * default arm, the changes on the apply arm. Read after
   * `runMaintenance` resolves, beside the task rows - the same shape the
   * reindex spend block rides, because a task's report belongs to the
   * run, not to a task row's receipt field.
   */
  relinkReport(): RelinkAnchorsReport | undefined;
}

export function buildLaneTasks(opts: LaneTaskBuildOptions): LaneTaskSet {
  const { vault, now, searchConfig, safeguardFor } = opts;
  const laneProgress = opts.onProgress !== undefined ? { onProgress: opts.onProgress } : {};
  // The relink report is captured by the task body and read by the
  // caller after the run: `undefined` until the task completes, and
  // undefined again never - a set builds one run's tasks.
  let relinkReport: RelinkAnchorsReport | undefined;
  // Spend is opt-in (`maintenance_embeddings`): the reindex builder decides
  // whether the pass may embed, announces the predicted spend inside the
  // task and receipts what the phase priced.
  const reindex = createLaneReindex({
    vault,
    ...(opts.configPath !== undefined ? { configPath: opts.configPath } : {}),
    searchConfig,
    now,
    forceCost: opts.forceCost,
    safeguard: () => safeguardFor(LANE_TASK.reindex),
    ...(opts.signal !== undefined ? { signal: opts.signal } : {}),
    ...laneProgress,
    ...(opts.onBanner !== undefined ? { onBanner: opts.onBanner } : {}),
  });
  const builtIns: MaintenanceTask[] = [
    {
      name: LANE_TASK.dream,
      run: async () => {
        // The task's one deadline starts with the task: the decide pass
        // spends it first, never more than its own budget, and the dream
        // pass gets the same guard (as the MCP dream tool shares its call's).
        const safeguard = safeguardFor(LANE_TASK.dream);
        const deadlineMs = decideBudgetWithin(safeguard.timeoutMs, 0);
        // The model verdicts are decided before the pass (design D10,
        // D20); the lane runs live passes only.
        // The lane's config and run date, as the pass below plans with them.
        const topicVerdicts =
          deadlineMs === 0
            ? undefined
            : await prepareTopicVerdicts({
                ...(opts.configPath !== undefined ? { configPath: opts.configPath } : {}),
                runAt: now,
                ...(deadlineMs !== undefined ? { deadlineMs } : {}),
              });
        dream(vault, {
          now,
          ...(opts.configPath !== undefined ? { configPath: opts.configPath } : {}),
          ...(topicVerdicts !== undefined ? { topicVerdicts } : {}),
          safeguard,
          ...laneProgress,
        });
      },
    },
    reindex.task,
    // Link-recall-intelligence passes ride the same lease, after reindex
    // so they see fresh edges. Both are fail-soft inside: a vault without
    // embeddings simply proposes nothing, and a metrics write failure
    // never fails the task.
    {
      name: LANE_TASK.bridges,
      run: async () => {
        const store = await Store.open(searchConfig, { mode: "read" });
        try {
          const report = discoverBridges(store, {
            dismissed: readDismissedBridges(vault),
            safeguard: safeguardFor(LANE_TASK.bridges),
            ...laneProgress,
          });
          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,
                lane: true,
              },
            });
          } catch {
            // Metrics are observability, not correctness.
          }
        } finally {
          await store.close();
        }
      },
    },
    {
      name: LANE_TASK.clusters,
      run: async () => {
        const store = await Store.open(searchConfig, { mode: "read" });
        try {
          const communities = detectCommunities(store, {
            safeguard: safeguardFor(LANE_TASK.clusters),
            ...laneProgress,
          });
          const materialized = materializeClusterNotes(vault, communities, { store, now });
          try {
            appendMetric(vault, {
              surface: "communities",
              runAt: isoSecond(now),
              payload: {
                communities: communities.length,
                sizes: communities.map((c) => c.size),
                written: materialized.written.length,
                removed: materialized.removed.length,
                lane: true,
              },
            });
          } catch {
            // Metrics are observability, not correctness.
          }
        } finally {
          await store.close();
        }
      },
    },
    // The anchor-relink pass (note-change truth maintenance) closes the
    // lane: it reads the signal tree and the entity index only, so it
    // needs no store. It PREVIEWS by contract - `relinkApply` hands it
    // the apply arm, and absent that flag the report is what would change
    // and no signal page is rewritten. Either way the pass's report is
    // captured below and surfaced through `relinkReport()`, so neither
    // front door runs the pass blind. The pass never calls a model and
    // returns no spend receipt.
    {
      name: LANE_TASK.relink,
      run: async () => {
        relinkReport = runRelinkAnchors(vault, {
          now,
          apply: opts.relinkApply === true,
          safeguard: safeguardFor(LANE_TASK.relink),
          ...laneProgress,
        });
      },
    },
  ];
  const custom = resolveCustomTasks(opts.configPath);
  const customTasks = custom.specs.map((spec) =>
    createCustomLaneTask(spec, {
      vault,
      ...(opts.signal !== undefined ? { signal: opts.signal } : {}),
    }),
  );
  const tasks = [...builtIns, ...customTasks];
  return {
    tasks,
    reindex,
    taskNames: tasks.map((task) => task.name),
    custom,
    relinkReport: () => relinkReport,
  };
}