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
10.2 KB
Raw Blame
/**
 * The shared embedding spend plan (Honest Embedding Spend).
 *
 * Four places price embedding spend: the phase gate, the maintenance
 * preview, the vector-backfill dry run and the `search status` refresh
 * estimate. They all read {@link planEmbeddingSpend}, so what a run
 * announces, refuses, spends and receipts is one computation: one pending
 * census (optionally path-scoped), one model resolution, one token
 * estimate, one price quote and one gate verdict.
 *
 * The gate fails closed only under an explicit cap: a positive
 * `embedding_cost_gate_usd` refuses an unpriced model with pending work,
 * because for an operator who asked for a ceiling an unknown price is not
 * a price below it. A zero gate (the default) never blocks.
 */

import {
  EMBEDDING_PRICE_MODEL_KEY,
  EMBEDDING_PRICE_RATE_KEY,
  resolveEmbeddingPrice,
  type PriceQuote,
} from "./embeddings/pricing.ts";
import { effectiveInputWindowTokens, passagePrefixSentByProvider } from "./embeddings/presets.ts";
import {
  embeddingSignature,
  estimateCostUsd,
  estimateTokens,
  LOCAL_EMBEDDING_MODEL,
} from "./embeddings/signature.ts";
import { sha256Hex } from "../integrity/digest.ts";
import type { Store } from "./store.ts";
import type { ChunkHoldExclusion, PendingVectorScope } from "./store/chunks.ts";
import type { ResolvedSearchConfig } from "./types.ts";

/** Why a gate refused. The value leaves TypeScript in previews and JSON. */
export const EMBEDDING_GATE_REASON = Object.freeze({
  /** The known estimate strictly exceeds the positive gate. */
  overCap: "over_cap",
  /** The gate is positive and nobody stated the model's price. */
  unpriced: "unpriced",
} as const);

/** Closed union over {@link EMBEDDING_GATE_REASON}. */
export type EmbeddingGateReason =
  (typeof EMBEDDING_GATE_REASON)[keyof typeof EMBEDDING_GATE_REASON];

/** Membership list of {@link EMBEDDING_GATE_REASON}. */
export const EMBEDDING_GATE_REASONS: ReadonlyArray<EmbeddingGateReason> = Object.freeze([
  EMBEDDING_GATE_REASON.overCap,
  EMBEDDING_GATE_REASON.unpriced,
]);

/** Narrow a string read back off disk or across a tool boundary. */
export function isEmbeddingGateReason(value: unknown): value is EmbeddingGateReason {
  return (
    typeof value === "string" && (EMBEDDING_GATE_REASONS as ReadonlyArray<string>).includes(value)
  );
}

/** A gate verdict: `reason` is null exactly when the run is not blocked. */
export type EmbeddingGateVerdict =
  | { readonly blocked: false; readonly reason: null }
  | { readonly blocked: true; readonly reason: EmbeddingGateReason };

/** Outcome of a cost-gate evaluation for an embedding run. */
export type CostGateResult = EmbeddingGateVerdict & {
  readonly tokens: number;
  /** Null when the price is unknown; never 0 for an unknown price. */
  readonly estimatedUsd: number | null;
};

const PASS: EmbeddingGateVerdict = Object.freeze({ blocked: false, reason: null });

/**
 * Evaluate whether an embedding run should be blocked on estimated spend.
 * Never blocks when the gate is 0, the run is forced or nothing is
 * pending. Otherwise an unknown price blocks as `unpriced` and a known
 * estimate strictly over the gate blocks as `over_cap`.
 */
export function evaluateCostGate(opts: {
  texts: ReadonlyArray<string>;
  quote: PriceQuote;
  gateUsd: number;
  forced?: boolean;
}): CostGateResult {
  const tokens = estimateTokens(opts.texts);
  const estimatedUsd = estimateCostUsd(tokens, opts.quote);
  return { tokens, estimatedUsd, ...gateVerdict(opts, estimatedUsd) };
}

function gateVerdict(
  opts: { texts: ReadonlyArray<string>; gateUsd: number; forced?: boolean },
  estimatedUsd: number | null,
): EmbeddingGateVerdict {
  if (opts.gateUsd <= 0 || opts.forced === true || opts.texts.length === 0) return PASS;
  if (estimatedUsd === null) return { blocked: true, reason: EMBEDDING_GATE_REASON.unpriced };
  if (estimatedUsd > opts.gateUsd) return { blocked: true, reason: EMBEDDING_GATE_REASON.overCap };
  return PASS;
}

/**
 * The model an embedding request would name right now. The local
 * provider always embeds with its implicit model, whatever
 * `embedding_model` says; every other provider takes the configured
 * one, falling back to what the index recorded when the config leaves
 * it unset.
 */
export function activeEmbeddingModel(
  config: ResolvedSearchConfig,
  storedModel: string | null = null,
): string | null {
  if (config.semantic.provider === "local") return LOCAL_EMBEDDING_MODEL;
  return config.semantic.model ?? storedModel;
}

/**
 * The model a pass would name and its price quote, through the operator
 * pair. The one model resolution every spend surface shares.
 */
export function activeSpendQuote(config: ResolvedSearchConfig): {
  readonly model: string | null;
  readonly quote: PriceQuote;
} {
  const model = activeEmbeddingModel(config);
  return { model, quote: resolveEmbeddingPrice(model, config.semantic.priceOverride) };
}

/** One computation of what an embedding pass would spend. */
export interface EmbeddingSpendPlan {
  /** The scoped pending census: chunks with no vector yet. */
  readonly pending: ReadonlyArray<{ readonly chunkId: number; readonly content: string }>;
  readonly model: string | null;
  readonly tokens: number;
  readonly quote: PriceQuote;
  /** Null when the price is unknown. */
  readonly estimatedUsd: number | null;
  readonly gate: EmbeddingGateVerdict;
}

/** Options of {@link planEmbeddingSpend}. */
export interface EmbeddingSpendPlanOptions {
  /** Path scope of the pending census; vault-wide when absent. */
  readonly scope?: PendingVectorScope;
  /** A forced plan never blocks. */
  readonly forced?: boolean;
}

/**
 * The pending-census exclusion key for this config's chunk holds
 * (chunk skip-and-hold, F2): the (model, window, signature) triple under
 * which the embedding phase records a hold, and under which the pending
 * anti-join hides held chunks from every spend surface.
 *
 * Null when no chunk can be proved over anything - no model, or no
 * declared window - and a null key excludes nothing: an old hold row
 * whose key no longer matches the config is inert, which is exactly the
 * release path. The phase persists under the same rendering so the writer
 * and the readers cannot drift on what "the same hold" means.
 */
export function chunkHoldExclusion(config: ResolvedSearchConfig): ChunkHoldExclusion | null {
  const model = activeEmbeddingModel(config);
  if (model === null) return null;
  const windowTokens = effectiveInputWindowTokens(config.semantic, model);
  if (windowTokens === null) return null;
  return Object.freeze({
    model,
    windowTokens,
    embeddingSignature: holdKeySignature(config, model),
  });
}

/**
 * The hold table's signature: the embedding identity PLUS the passage
 * prefix the backend would actually send. The hold's proof is measured
 * over `prefix + content` against the window, so the key the proof is
 * recorded under has to answer for the prefix too - a shortened or
 * removed prefix changes what fits, and a key blind to it would keep
 * excluding a chunk that now fits, with nothing to release it. The prefix
 * rides as a LEADING field, so the trailing provider:model:dimension
 * triple every signature reader parses from the end stays intact; an
 * empty sent prefix (every backend but `openai-compat`, or the prefix
 * disabled) contributes no field and renders the identity alone.
 */
function holdKeySignature(config: ResolvedSearchConfig, model: string): string {
  const identity = embeddingSignature({
    provider: config.semantic.provider,
    model,
    dimension: config.semantic.dimension,
  });
  const sent = passagePrefixSentByProvider(config.semantic.provider, config.semantic.passagePrefix);
  if (sent === "") return identity;
  const digest = sha256Hex(sent);
  return `pp-${digest.slice(0, 16)}:${identity}`;
}

/**
 * Plan the spend of embedding every pending chunk in scope. Reads only:
 * the phase in `indexer.ts` remains the only spender and throws on a
 * blocked verdict. Chunks held under the config's own key are not
 * pending: they leave the census before they can be priced.
 */
export function planEmbeddingSpend(
  store: Store,
  config: ResolvedSearchConfig,
  opts: EmbeddingSpendPlanOptions = {},
): EmbeddingSpendPlan {
  const hold = chunkHoldExclusion(config);
  return priceSpendPlan(
    store.findChunksWithoutEmbeddings(opts.scope, hold ?? undefined),
    config,
    opts.forced,
  );
}

/**
 * Price `pending` under the current config: the model, the quote, the
 * estimate and the gate verdict, with no census read. The embedding
 * phase re-prices a plan a caller handed in this way, so the verdict it
 * gates on is never one the caller computed forced or under another
 * config.
 */
export function priceSpendPlan(
  pending: EmbeddingSpendPlan["pending"],
  config: ResolvedSearchConfig,
  forced?: boolean,
): EmbeddingSpendPlan {
  const { model, quote } = activeSpendQuote(config);
  const { tokens, estimatedUsd, ...gate } = evaluateCostGate({
    texts: pending.map((p) => p.content),
    quote,
    gateUsd: config.semantic.costGateUsd,
    ...(forced === undefined ? {} : { forced }),
  });
  return { pending, model, tokens, quote, estimatedUsd, gate };
}

/** What every spend surface prints in place of a dollar figure nobody can state. */
export const PRICE_UNKNOWN_LABEL = "price unknown";

/** Decimal places of every rendered USD amount, the gate's own spelling. */
export const USD_DECIMALS = 4;

/** A USD estimate as `$0.0123`, or {@link PRICE_UNKNOWN_LABEL} when null. */
export function formatEstimatedUsd(usd: number | null): string {
  return usd === null ? PRICE_UNKNOWN_LABEL : `$${usd.toFixed(USD_DECIMALS)}`;
}

/** The config key whose positive value turns an estimate into a refusal. */
export const COST_GATE_KEY = "embedding_cost_gate_usd";
/** The flag that passes a cost-gate refusal for one run. */
export const FORCE_COST_FLAG = "--force-cost";

/** The refusal text for an unpriced model under a positive gate. */
export function unpricedRefusalMessage(plan: EmbeddingSpendPlan, gateUsd: number): string {
  return (
    `embedding model ${plan.model ?? "(unset)"} has no known price, so ${plan.pending.length} ` +
    `chunk(s) cannot be checked against ${COST_GATE_KEY} ${formatEstimatedUsd(gateUsd)}. ` +
    `Declare its price with ${EMBEDDING_PRICE_MODEL_KEY} and ${EMBEDDING_PRICE_RATE_KEY}, ` +
    `or re-run with ${FORCE_COST_FLAG} to proceed.`
  );
}