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
17.1 KB
Raw Blame
/**
 * Shared, dependency-free helpers for HTTP embedding providers
 * (openai-compat, zeroentropy). Pure utilities only - no network, no
 * config knowledge - so each provider owns its own request/response
 * mapping while reusing identical batching, concurrency, backoff, and
 * unit-normalisation semantics.
 *
 * {@link Semaphore} is the one exception to "embedding providers": it is
 * the search layer's only concurrency limiter, and the recall benchmark
 * bounds its query fan-out with it too rather than growing a second one.
 */

import { SearchError } from "../types.ts";
import { assertValidVector } from "../vector-guard.ts";
import { estimateTokens } from "./signature.ts";

/** Statuses that warrant a transient retry with backoff. */
export const RETRYABLE_STATUSES: ReadonlySet<number> = new Set([429, 500, 502, 503, 504]);

/** Auth statuses that trigger failover to the next probe key. */
export const AUTH_STATUSES: ReadonlySet<number> = new Set([401, 403]);

/** HTTP 402 Payment Required: an unconditional billing/quota exhaustion signal. */
export const PAYMENT_REQUIRED_STATUS = 402;

/** HTTP 429 Too Many Requests: a rate-limit unless the body proves quota exhaustion. */
export const RATE_LIMIT_STATUS = 429;

/** Milliseconds per second, used to convert `Retry-After` delta-seconds. */
const MS_PER_SECOND = 1000;

/** Hosts a plain-`http://` provider endpoint is still accepted on. */
function isLoopbackHost(hostname: string): boolean {
  const h = hostname.toLowerCase().replace(/^\[|\]$/g, "");
  return h === "localhost" || h === "127.0.0.1" || h === "::1";
}

/**
 * The endpoint a provider transport may POST vault bytes and bearer keys
 * to, validated.
 *
 * `https` is required everywhere except a loopback host, where plain
 * `http` is the local-server case (a self-hosted embedding endpoint on
 * 127.0.0.1) and the plaintext hop never leaves the machine. Everywhere
 * else the requirement is not ceremony: every indexed chunk body and the
 * `authorization: Bearer` header travel to this host, and a `http://`
 * endpoint hands both to anyone on the path. The registry file that
 * carries `baseUrl` lives inside the vault, so this is also the wall
 * between a config-writing boundary and vault exfiltration by config.
 *
 * The one exception is an explicit operator opt-out for a single endpoint
 * ({@link HttpEgressOptOut}): a local embedding server on a LAN or tailnet
 * address (LM Studio on the Windows host, Ollama on another box) has no
 * certificate to offer. It is off by default, it is read only from the
 * operator's own config or environment - never from the in-vault provider
 * registry - and every process that uses it says so once on stderr.
 *
 * Returns the URL unchanged; throws `INVALID_INPUT` naming the config
 * key when the shape or scheme is refused.
 */
export function assertHttpEgressEndpoint(
  rawUrl: string,
  configKey: string,
  optOut?: HttpEgressOptOut,
): string {
  let url: URL;
  try {
    url = new URL(rawUrl);
  } catch {
    throw new SearchError("INVALID_INPUT", `${configKey} is not a URL: ${rawUrl}`);
  }
  const httpsOk = url.protocol === "https:";
  const loopbackHttpOk = url.protocol === "http:" && isLoopbackHost(url.hostname);
  if (httpsOk || loopbackHttpOk) return rawUrl;
  if (url.protocol === "http:" && optOut?.allowInsecureHttp === true) {
    warnInsecureHttpOnce(rawUrl, configKey, optOut.key);
    return rawUrl;
  }
  throw new SearchError(
    "INVALID_INPUT",
    `${configKey} must be an https endpoint (plain http is accepted only for ` +
      `localhost/127.0.0.1/::1` +
      (optOut !== undefined
        ? `, or for this endpoint when the operator config sets ${optOut.key}: true`
        : "") +
      `): ${rawUrl}`,
  );
}

/**
 * The per-endpoint plain-http opt-out, as resolved from the operator's
 * config. `key` is the config key that grants it, named in the refusal
 * and in the warning so an operator can find the switch.
 */
export interface HttpEgressOptOut {
  readonly allowInsecureHttp: boolean;
  readonly key: string;
}

/** Endpoints this process already warned about. */
const insecureHttpWarned = new Set<string>();

function warnInsecureHttpOnce(rawUrl: string, configKey: string, optOutKey: string): void {
  if (insecureHttpWarned.has(rawUrl)) return;
  insecureHttpWarned.add(rawUrl);
  process.stderr.write(
    `warning: ${configKey} is plain http (${rawUrl}) because ${optOutKey} is true: ` +
      `vault text and the API key travel unencrypted to that host. Use it only on a ` +
      `network you trust (a LAN or tailnet).\n`,
  );
}

/**
 * Parse an HTTP `Retry-After` header value into milliseconds. The header is
 * either a non-negative integer count of seconds (RFC 7231 delta-seconds) or
 * an HTTP-date. Returns null when absent or unparseable. `nowMs` is
 * injectable so date-form parsing stays deterministic in tests.
 */
export function parseRetryAfterMs(
  headerValue: string | null,
  nowMs: number = Date.now(),
): number | null {
  if (headerValue === null) return null;
  const trimmed = headerValue.trim();
  if (trimmed === "") return null;
  // delta-seconds form: a bare non-negative integer.
  if (/^\d+$/.test(trimmed)) {
    return Number(trimmed) * MS_PER_SECOND;
  }
  // HTTP-date form: convert to a delay relative to now, floored at zero.
  const dateMs = Date.parse(trimmed);
  if (Number.isNaN(dateMs)) return null;
  const delta = dateMs - nowMs;
  return delta > 0 ? delta : 0;
}

/** The `name` every cancelled fetch and `AbortController.abort()` reason carries. */
export const ABORT_ERROR_NAME = "AbortError";

/** True when `error` is an abort, recognised by its standard name. */
export function isAbortError(error: unknown): boolean {
  return (
    typeof error === "object" &&
    error !== null &&
    (error as { readonly name?: unknown }).name === ABORT_ERROR_NAME
  );
}

/**
 * Forward a caller's abort into a controller the callee owns, so one
 * cancellation reaches every request it started. Returns the unlink
 * function; an absent signal links nothing.
 */
export function linkAbortSignal(
  source: AbortSignal | undefined,
  target: AbortController,
): () => void {
  if (source === undefined) return () => {};
  if (source.aborted) {
    target.abort();
    return () => {};
  }
  const onAbort = (): void => target.abort();
  source.addEventListener("abort", onAbort, { once: true });
  return () => source.removeEventListener("abort", onAbort);
}

/**
 * Delay for `ms`, resolving early (never rejecting) if `signal` aborts. An
 * abort-aware sleep lets a retry backoff react to cancellation immediately
 * instead of blocking a sibling batch for up to the retry-after cap after
 * the shared abort signal fires. The caller re-checks the signal on the next
 * loop iteration to surface the cancellation.
 */
export function sleep(ms: number, signal?: AbortSignal): Promise<void> {
  if (signal?.aborted) return Promise.resolve();
  return new Promise((res) => {
    const onAbort = (): void => {
      clearTimeout(timer);
      res();
    };
    const timer = setTimeout(() => {
      signal?.removeEventListener("abort", onAbort);
      res();
    }, ms);
    signal?.addEventListener("abort", onAbort, { once: true });
  });
}

/** Apply ±25% jitter to a backoff base (never negative). */
export function jittered(base: number): number {
  const jitter = base * 0.25 * (Math.random() * 2 - 1);
  return Math.max(0, base + jitter);
}

/**
 * The three caps this module enforces, named for the operator-facing
 * config key each one carries, so a refusal says which key to change.
 */
const CAP_FIELD = Object.freeze({
  /** `embedding_batch_size`: how many items one request may carry. */
  size: "batch size",
  /** `embedding_batch_tokens`: how many estimated tokens one request may carry. */
  tokens: "token budget",
  /** `embedding_concurrency`: how many requests may be in flight at once. */
  concurrency: "concurrency ceiling",
});

/**
 * Take a cap EXACTLY as the caller gave it, or refuse it.
 *
 * `Math.max(1, cap | 0)` used to stand at every call site. `| 0` truncates
 * to a signed 32-bit int, so a cap above 2^31-1 wrapped NEGATIVE and the
 * clamp then lifted it to 1: the largest batch - or the widest concurrency
 * ceiling - an operator can ask for silently became the smallest one
 * possible. Nothing is truncated now, and nothing is clamped: a cap this
 * module cannot honour is named rather than quietly reinterpreted into a
 * different request plan than the one configured.
 *
 * All three keys are already refused below 1, at a fraction, and at a
 * non-finite value by config validation (`search/index.ts`), so a resolved
 * config never reaches this guard; it holds the line for programmatic
 * callers that construct a `ResolvedEmbeddingConfig` directly.
 */
function requireCap(cap: number, field: string): number {
  if (!Number.isInteger(cap) || cap < 1) {
    throw new SearchError("INVALID_INPUT", `${field} must be an integer >= 1, got ${cap}`);
  }
  return cap;
}

/**
 * One permit, handed to the acquirer that holds it. Calling it gives the
 * permit back; calling it a second time raises, because the second call
 * is a release of something the caller no longer holds.
 */
export type SemaphorePermit = () => void;

/**
 * A minimal counting semaphore for bounded concurrency.
 *
 * Giving a permit back hands it DIRECTLY to the head of the waiter queue
 * instead of returning it to the pool for the woken waiter to claim
 * later. The pool form over-subscribes by one for every wakeup: between
 * the `permits++` and the waiter's continuation there is a microtask in
 * which a fresh `acquire()` sees a free permit and takes it, and the
 * waiter then decrements past zero. Both run, and the ceiling reads one
 * higher than configured. With a hand-off the permit is never observable
 * as free, so the invariant holds for any interleaving.
 *
 * ## Why a permit rather than a `release()` method
 *
 * An over-release is a CALLER DEFECT, not an input: nothing an operator
 * configures can produce one, only code that gives back a permit it never
 * took or gives one back twice. So it is refused loudly rather than
 * clamped - a clamp would leave the defective call site running, and the
 * whole point of this object is that the number of requests on the wire
 * is the configured number and not a number that drifted.
 *
 * Refusing needs the holder's own record, which is what makes the permit
 * a value instead of a method:
 *
 *   - `if (permits >= limit) throw` cannot see the case that matters.
 *     With a waiter queued the pool count is 0, so a stray release passes
 *     that test and is handed straight to the waiter: one more holder
 *     than the ceiling, and no counter moved.
 *   - `if (held === 0) throw` misses the same case for the same reason.
 *   - A one-shot permit closure decides it locally: the second call knows
 *     it is the second call, whatever the pool and queue happen to hold,
 *     and code that never acquired has nothing to call.
 *
 * That also repairs the instrument. {@link peakInFlight} counts entries
 * and matched exits ONLY, so it can no longer be driven below the truth
 * by the very releases that break the bound - the failure mode where a
 * ceiling of 2 ran 4 real holders and the counter still reported 2
 * (nothing-runs-unwatched review, C4). A bound nothing can observe is a
 * bound nothing can verify, and a counter the breach silences is worse
 * than none.
 *
 * The ceiling is process-wide and shared between callers
 * (`provider-semaphore.ts`), so one caller's stray release would widen
 * the ceiling for every other caller against the same provider. That is
 * why the guard lives here rather than at any one call site.
 */
export class Semaphore {
  /** The ceiling enforced here: the permit count when nothing is held. */
  readonly limit: number;
  private permits: number;
  private held = 0;
  private peak = 0;
  private readonly waiters: Array<() => void> = [];
  constructor(limit: number) {
    this.limit = requireCap(limit, CAP_FIELD.concurrency);
    this.permits = this.limit;
  }
  /**
   * Most permits held at once since construction. Every increment is an
   * acquirer that entered and every decrement is that acquirer's own
   * permit coming back, so this is the true high-water mark of holders -
   * and never above `limit`, as a consequence rather than a coincidence.
   */
  get peakInFlight(): number {
    return this.peak;
  }
  private enter(): SemaphorePermit {
    this.held++;
    if (this.held > this.peak) this.peak = this.held;
    let spent = false;
    return (): void => {
      if (spent) {
        throw new SearchError(
          "INVALID_INPUT",
          `semaphore permit released twice (ceiling ${this.limit}): a second release ` +
            `returns a permit this caller no longer holds and widens the ceiling for ` +
            `every caller sharing it`,
        );
      }
      spent = true;
      this.leave();
    };
  }
  private leave(): void {
    this.held--;
    const next = this.waiters.shift();
    if (next) {
      next();
      return;
    }
    this.permits++;
  }
  /** Take a permit, waiting for one; call the result once to give it back. */
  async acquire(): Promise<SemaphorePermit> {
    if (this.permits > 0) {
      this.permits--;
      return this.enter();
    }
    // The releaser transfers its permit to this waiter, so the resumed
    // acquirer must NOT decrement `permits` again.
    await new Promise<void>((res) => this.waiters.push(res));
    return this.enter();
  }
  /**
   * Take a free permit WITHOUT ever yielding, or see there is none.
   *
   * `acquire()` is an `async` method, so `await acquire()` parks the
   * caller on a microtask even when a permit is free - and a microtask
   * cannot run until the caller's synchronous execution finishes. The
   * overlapped hybrid search (recall-lane-latency) starts the embed lane
   * in the caller's tick precisely so the HTTP request leaves before the
   * synchronous keyword lanes run; an await in the free-permit path
   * shipped the dispatch after them and the overlap never happened. The
   * fast path is `enter()` itself, which is synchronous: a free permit
   * reaches the caller in its own tick, `null` sends it to
   * {@link acquire} unchanged, and the permit contract (one release,
   * loud on a second) is identical either way.
   */
  tryAcquire(): SemaphorePermit | null {
    if (this.permits <= 0) return null;
    this.permits--;
    return this.enter();
  }
}

/**
 * Unit-normalise a vector in place so cosine similarity equals 1 - L2²/2.
 * A zero-norm or non-finite input has no meaningful unit direction, so it
 * surfaces a typed {@link SearchError} (`EMBEDDING_INVALID_VECTOR`) rather
 * than the former silent no-op that returned unnormalised zeros
 * (memory-write-path-integrity B1).
 */
export function unitNormaliseInPlace(v: number[]): number[] {
  assertValidVector(v, "unitNormalise");
  let s = 0;
  for (const x of v) s += x * x;
  const norm = Math.sqrt(s);
  for (let i = 0; i < v.length; i++) v[i] = (v[i] ?? 0) / norm;
  return v;
}

/** Split an array into fixed-size chunks. Refuses a step below 1 or fractional. */
export function chunkArray<T>(arr: ReadonlyArray<T>, size: number): T[][] {
  const step = requireCap(size, CAP_FIELD.size);
  const out: T[][] = [];
  for (let i = 0; i < arr.length; i += step) out.push(arr.slice(i, i + step) as T[]);
  return out;
}

/**
 * Split an array into batches that close on whichever of two caps fills
 * first: the item count (`size`, i.e. `embedding_batch_size`) or the
 * accumulated token estimate (`tokenBudget`, i.e. `embedding_batch_tokens`).
 *
 * `tokenBudget` of `undefined` - the state of an unset config key - delegates
 * straight to {@link chunkArray}, so batching is byte-identical to the fixed
 * stride that preceded the budget.
 *
 * The estimate is {@link estimateTokens}, the estimator already resident in
 * this layer and already governing the indexer's cost gate, so the gate and
 * the batch budget describe the same texts identically. It deliberately
 * differs from the chunker's word-count estimator: that one sizes chunks of
 * a document, this one sizes a request. `textOf` must return the text
 * exactly as it will be sent, instruction prefix included, because the
 * provider prepends the prefix before batching and the provider's token
 * ceiling counts it.
 *
 * An item whose own estimate already exceeds the budget cannot be made to fit
 * by closing the batch around it, so it travels alone. Splitting the text
 * itself is the chunker's job, not the request packer's; dropping it would be
 * silent data loss.
 */
export function chunkArrayByTokenBudget<T>(
  arr: ReadonlyArray<T>,
  size: number,
  tokenBudget: number | undefined,
  textOf: (item: T) => string,
): T[][] {
  if (tokenBudget === undefined) return chunkArray(arr, size);
  const step = requireCap(size, CAP_FIELD.size);
  const budget = requireCap(tokenBudget, CAP_FIELD.tokens);
  const out: T[][] = [];
  let current: T[] = [];
  let currentTokens = 0;
  for (const item of arr) {
    const tokens = estimateTokens([textOf(item)]);
    if (current.length > 0 && (current.length >= step || currentTokens + tokens > budget)) {
      out.push(current);
      current = [];
      currentTokens = 0;
    }
    current.push(item);
    currentTokens += tokens;
  }
  if (current.length > 0) out.push(current);
  return out;
}