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 query-embed gateway (honest-query-embed-and-safe-upgrades).
 *
 * Every paid query embed answers the same question before it spends: what
 * text goes on the wire. This module answers it once, so the search lane
 * and the semantic belief order cannot disagree about it.
 *
 * The fit cuts the query to the effective input window
 * (`effectiveInputWindowTokens` in `presets.ts`), charging the prefix the
 * backend actually sends against it. The cut uses the CEILING estimate,
 * the bound that cannot under-count, so it never sends more than the
 * window. Spend disclosure keeps the shared floor-side `estimateTokens`,
 * so a query receipt stays comparable with every other spend surface.
 * The ceiling over-cuts non-ASCII text; that is the safe direction, and
 * there is no real tokenizer here on purpose (no dependency).
 *
 * An unknown window cuts nothing, which is byte-identical to the
 * behaviour before the window was known to anyone.
 *
 * The gate decides whether the embed is sent at all. A caller that is not
 * local spends the operator's money on every request, so under a positive
 * `embedding_cost_gate_usd` a model nobody priced is refused before any
 * provider exists. That is v1.72.0's rule exactly (the unpriced arm only,
 * never an over-cap comparison for one query), and this is the one place
 * it lives. The gateway returns data rather than throwing, because its
 * callers report a refusal differently: the search lane has an explicit
 * and an implicit arm, the semantic belief order always refuses.
 */

import { resolvedTransportReach, TRANSPORT_REACH } from "../../graph/transport-reach.ts";
import type { TransportReach } from "../../graph/transport-reach.ts";
import { activeSpendQuote, COST_GATE_KEY } from "../embedding-spend.ts";
import type { ResolvedSearchConfig } from "../types.ts";
import {
  effectiveInputWindowTokens,
  INPUT_WINDOW_TOKENS_KEY,
  queryPrefixSentByProvider,
} from "./presets.ts";
import {
  EMBEDDING_PRICE_MODEL_KEY,
  EMBEDDING_PRICE_RATE_KEY,
  EMBEDDING_PRICE_SOURCE,
  type PriceQuote,
} from "./pricing.ts";
import { estimateTokens, textExtent, tokenEstimateCeiling } from "./signature.ts";

/** What a query fit decided: the text to send and what it costs. */
export interface QueryFit {
  /**
   * The query as it will be sent, without the prefix (the provider adds
   * the prefix itself). Empty when the prefix alone fills the window: the
   * caller must treat that as a degradation, never embed it.
   */
  readonly text: string;
  /** True when {@link text} is shorter than the query the caller sent. */
  readonly truncated: boolean;
  /**
   * The spend estimate (`estimateTokens`) of what goes on the wire, prefix
   * included. Zero when nothing is sent.
   */
  readonly sentTokens: number;
}

/** UTF-8 byte length of one code point. */
function utf8Length(codePoint: number): number {
  if (codePoint < 0x80) return 1;
  if (codePoint < 0x800) return 2;
  if (codePoint < 0x10000) return 3;
  return 4;
}

/**
 * The longest code-point prefix of `query` whose ceiling estimate, with
 * `prefix` in front, fits `windowTokens`. A `null` window means unknown,
 * and an unknown window cuts nothing.
 *
 * The cut is at a code-point boundary, so it never splits a surrogate
 * pair, and it is language-agnostic: no word or grapheme rule. The
 * ceiling never decreases as code points are appended (each one adds at
 * most one non-ASCII slot and at most one remainder code point), so the
 * first code point that overflows marks the cut.
 */
export function fitQueryToWindow(
  query: string,
  prefix: string,
  windowTokens: number | null,
): QueryFit {
  const whole = (): QueryFit =>
    Object.freeze({
      text: query,
      truncated: false,
      sentTokens: estimateTokens([prefix + query]),
    });
  if (windowTokens === null) return whole();

  const base = textExtent(prefix);
  const fits = (codePoints: number, utf8Bytes: number): boolean =>
    tokenEstimateCeiling({
      codePoints: base.codePoints + codePoints,
      utf8Bytes: base.utf8Bytes + utf8Bytes,
    }) <= windowTokens;

  const codePoints = [...query];
  let kept = 0;
  let bytes = 0;
  for (const ch of codePoints) {
    const next = bytes + utf8Length(ch.codePointAt(0)!);
    if (!fits(kept + 1, next)) break;
    kept++;
    bytes = next;
  }
  if (kept === codePoints.length) return whole();

  const text = codePoints.slice(0, kept).join("");
  return Object.freeze({
    text,
    truncated: true,
    sentTokens: text === "" ? 0 : estimateTokens([prefix + text]),
  });
}

/** The gateway refused: the embed must not be sent. */
export interface QueryEmbedRefused {
  readonly kind: "refused";
  readonly code: "EMBEDDING_COST_UNPRICED";
  /** The model the embed would have named, null when none is configured. */
  readonly model: string | null;
}

/** The gateway cleared the embed: send {@link text}, disclose the rest. */
interface QueryEmbedReadyBase extends QueryFit {
  readonly kind: "ready";
  /** The price quote every spend surface shares for {@link model}. */
  readonly quote: PriceQuote;
  /** The model the embed names, null when none is configured. */
  readonly model: string | null;
}

/** The query fits its window (or the window is unknown): it is sent whole. */
export interface QueryEmbedWhole extends QueryEmbedReadyBase {
  readonly truncated: false;
  readonly emptyFit: false;
  /** The effective input window the text was fitted to; null when unknown. */
  readonly windowTokens: number | null;
}

/** The query was cut to its window; only a known window cuts. */
export interface QueryEmbedCut extends QueryEmbedReadyBase {
  readonly truncated: true;
  /**
   * True when the instruction prefix alone fills the window, so nothing of
   * the query survived the cut. Every caller must treat it as a
   * degradation and never embed the prefix by itself.
   */
  readonly emptyFit: boolean;
  /** The effective input window the text was cut to. */
  readonly windowTokens: number;
}

/** A cleared embed: whole, or cut to a known window. */
export type QueryEmbedReady = QueryEmbedWhole | QueryEmbedCut;

/** What {@link prepareQueryEmbed} decided. */
export type QueryEmbedPreparation = QueryEmbedRefused | QueryEmbedReady;

/**
 * Decide whether, and with what text, a query is embedded.
 *
 * Pure over the config: no provider is constructed and nothing is sent.
 * An omitted reach resolves through `resolvedTransportReach` (remote), as
 * everywhere else in the tree. The local hashing embedder is priced at 0
 * by the builtin table, so it is never refused; a self-hosted model is
 * unpriced until the operator declares its price (0 for free).
 */
export function prepareQueryEmbed(
  config: ResolvedSearchConfig,
  query: string,
  reach: TransportReach | undefined,
): QueryEmbedPreparation {
  const { model, quote } = activeSpendQuote(config);
  if (
    resolvedTransportReach(reach) !== TRANSPORT_REACH.local &&
    config.semantic.costGateUsd > 0 &&
    quote.source === EMBEDDING_PRICE_SOURCE.unknown
  ) {
    return Object.freeze({ kind: "refused", code: "EMBEDDING_COST_UNPRICED", model });
  }
  const windowTokens = effectiveInputWindowTokens(config.semantic);
  const fit = fitQueryToWindow(
    query,
    queryPrefixSentByProvider(config.semantic.provider, config.semantic.queryPrefix),
    windowTokens,
  );
  if (fit.truncated && windowTokens !== null) {
    return Object.freeze({
      kind: "ready",
      ...fit,
      truncated: true,
      emptyFit: fit.text === "",
      windowTokens,
      quote,
      model,
    });
  }
  return Object.freeze({
    kind: "ready",
    ...fit,
    truncated: false,
    emptyFit: false,
    windowTokens,
    quote,
    model,
  });
}

/**
 * The operator-facing sentence for a refused query embed: the model, the
 * gate key, and the price pair that clears it. Shared so every caller
 * that surfaces the refusal names the same lever.
 *
 * The gate amount is the operator's budget and the gateway refuses only
 * callers that are not local, so the sentence says the gate is positive
 * and never states the amount.
 */
export function queryEmbedRefusalMessage(refused: QueryEmbedRefused): string {
  return (
    `embedding model ${refused.model ?? "(unset)"} has no known price and ` +
    `${COST_GATE_KEY} is positive, so a query embed for a caller ` +
    `that is not local is refused. Declare its price with ${EMBEDDING_PRICE_MODEL_KEY} ` +
    `and ${EMBEDDING_PRICE_RATE_KEY} (0 for a free self-hosted model).`
  );
}

/**
 * The operator-facing sentence for an empty fit: the window, and the key
 * that raises it when the model accepts more. Shared so the search lane
 * and the semantic belief order name the same lever.
 */
export function queryEmbedEmptyFitMessage(cut: QueryEmbedCut): string {
  return (
    `the ${cut.windowTokens}-token embedding input window leaves no room for the query ` +
    `after the instruction prefix; raise ${INPUT_WINDOW_TOKENS_KEY} if the model accepts ` +
    `more, or shorten the query prefix`
  );
}

/**
 * The operator-facing sentence for a query cut to its window: the window,
 * how much of `query` was embedded, and the key that raises the window.
 */
export function queryEmbedCutMessage(cut: QueryEmbedCut, query: string): string {
  return (
    `query cut to the ${cut.windowTokens}-token embedding input window: ` +
    `${[...cut.text].length} of ${[...query].length} code point(s) embedded; ` +
    `raise ${INPUT_WINDOW_TOKENS_KEY} if the model accepts more`
  );
}