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
6.3 KB
Raw Blame
/**
 * The maintenance lane's reindex task, shared by both front doors
 * (`o2b brain maintenance run` and the `brain_maintenance` MCP tool).
 *
 * One builder owns the three things the two doors used to copy: whether
 * the pass may run its embedding phase, the spend preview announced
 * before the pass, and the receipt recorded after it (task row, metrics
 * line, run-level `spend` block).
 *
 * Spend is opt-in. The lane is unattended - a cron runs it - so the
 * embedding phase runs only when the operator set `maintenance_embeddings`
 * AND the resolved config can reach a provider. Off, the pass is
 * keyword-only: no preview, no provider call, no receipt. On, the
 * embedding cost gate applies exactly as it does for `o2b search index`.
 *
 * The preview is computed INSIDE the task, so a run the window, busy or
 * lease gate skips never reads the pending chunks and never reports a
 * banner for a pass that did not happen.
 */

import type { EmbeddingPriceSource } from "../../search/embeddings/pricing.ts";
import { resolveMaintenanceEmbeddings } from "../../config.ts";
import {
  resolveSemanticCapability,
  semanticCapabilityIsBlocked,
} from "../../search/capability-tier.ts";
import { indexVault } from "../../search/index.ts";
import {
  embeddingSpendOf,
  estimatePendingEmbeddingSpend,
  type EmbeddingSpendPreview,
} from "../../search/indexer.ts";
import type { ResolvedSearchConfig } from "../../search/types.ts";
import { appendMetric } from "../metrics.ts";
import type { ProgressSink } from "../progress.ts";
import type { Safeguard } from "../safeguard.ts";
import { isoSecond } from "../time.ts";
import { MAINTENANCE_SPEND_METRIC, type MaintenanceSpendReceipt } from "./journal.ts";
import { LANE_TASK, type MaintenanceTask, type MaintenanceTaskResult } from "./lane.ts";

export interface LaneReindexOptions {
  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;
  /** Built lazily, so the deadline starts when the task starts. */
  readonly safeguard: () => Safeguard;
  readonly signal?: AbortSignal;
  readonly onProgress?: ProgressSink;
  /** Called once with the preview, before the pass, when there is one. */
  readonly onBanner?: (preview: EmbeddingSpendPreview) => void;
}

/** The run-level `spend` block both doors report beside the task rows. */
export interface LaneSpendBlock {
  readonly banner?: {
    readonly model: string | null;
    readonly pendingChunks: number;
    /** Null when nobody stated the model's price. */
    readonly estimatedUsd: number | null;
    /** Who stated the price the estimate used. */
    readonly priceSource: EmbeddingPriceSource;
    readonly gateUsd: number;
  };
  readonly receipt?: MaintenanceSpendReceipt;
  /** Set when the receipt's metrics line could not be written, naming why. */
  readonly receipt_metric_error?: string;
}

export interface LaneReindex {
  /** True when this run may contact an embedding provider. */
  readonly embeddings: boolean;
  readonly task: MaintenanceTask;
  /** The `spend` block for the finished run, or undefined when there is nothing to say. */
  spendBlock(tasks: ReadonlyArray<MaintenanceTaskResult>): LaneSpendBlock | undefined;
}

/** Whether the lane may run the embedding phase under this config. */
export function laneEmbeddingsEnabled(
  searchConfig: ResolvedSearchConfig,
  configPath?: string,
): boolean {
  return (
    resolveMaintenanceEmbeddings(configPath) &&
    !semanticCapabilityIsBlocked(resolveSemanticCapability(searchConfig.semantic))
  );
}

export function createLaneReindex(opts: LaneReindexOptions): LaneReindex {
  const embeddings = laneEmbeddingsEnabled(opts.searchConfig, opts.configPath);
  let banner: EmbeddingSpendPreview | undefined;
  let metricError: string | undefined;

  const task: MaintenanceTask = {
    name: LANE_TASK.reindex,
    run: async () => {
      // An estimate by position: the walk may still add chunks, so the
      // receipt below is the phase's own census, not this number.
      if (embeddings) {
        const preview = await estimatePendingEmbeddingSpend(opts.searchConfig);
        if (preview !== null) {
          banner = preview;
          opts.onBanner?.(preview);
        }
      }
      const stats = await indexVault(opts.searchConfig, {
        embeddings,
        forceCost: opts.forceCost,
        safeguard: opts.safeguard(),
        ...(opts.signal !== undefined ? { signal: opts.signal } : {}),
        ...(opts.onProgress !== undefined ? { onProgress: opts.onProgress } : {}),
      });
      // Only a completed pass returns stats, so a pass killed mid-spend
      // receipts nothing and its row carries the named failure instead.
      const receipt = embeddingSpendOf(stats);
      if (receipt !== undefined) {
        try {
          appendMetric(opts.vault, {
            surface: MAINTENANCE_SPEND_METRIC,
            runAt: isoSecond(opts.now),
            payload: {
              task: LANE_TASK.reindex,
              model: receipt.model,
              tokens: receipt.tokens,
              estimated_usd: receipt.estimatedUsd,
              price_source: receipt.priceSource,
              forced: receipt.forced,
              lane: true,
            },
          });
        } catch (err) {
          // The receipt still rides the task row and the journal; the
          // missing metrics line is reported by name on the spend block.
          metricError = err instanceof Error ? err.message : String(err);
        }
      }
      return receipt;
    },
  };

  return {
    embeddings,
    task,
    spendBlock(tasks) {
      const receipt = tasks.find(
        (t) => t.name === LANE_TASK.reindex && t.receipt !== undefined,
      )?.receipt;
      if (banner === undefined && receipt === undefined) return undefined;
      return {
        ...(banner !== undefined
          ? {
              banner: {
                model: banner.model,
                pendingChunks: banner.pendingChunks,
                estimatedUsd: banner.estimatedUsd,
                priceSource: banner.priceSource,
                gateUsd: opts.searchConfig.semantic.costGateUsd,
              },
            }
          : {}),
        ...(receipt !== undefined ? { receipt } : {}),
        ...(metricError !== undefined ? { receipt_metric_error: metricError } : {}),
      };
    },
  };
}