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
15.2 KB
Raw Blame
/**
 * The provider-consent resolver: what the operator's configuration says
 * about the embedding provider, and whether they DECLINED it
 * (write-honesty-egress-consent, Lane F).
 *
 * ## The defect this module exists for
 *
 * An operator who wrote `search_semantic_enabled: false` and an operator
 * who never configured semantic search at all reached the SAME capability
 * tier, so every surface reported the same sentence for two opposite
 * situations: one of them a decision, the other an absence. The
 * distinction is not cosmetic - "the provider is off" and "the operator
 * said no" have different repairs, and a surface that cannot tell them
 * apart cannot tell an operator which one they are looking at.
 *
 * ## What this module is NOT
 *
 * It is not a third "off" spelling beside the capability tier. The tier
 * (`./capability-tier.ts`) still answers what the configuration can do,
 * and this resolver CARRIES that tier rather than computing a second one:
 * {@link ProviderConsent.capability} is the shared resolver's answer, and
 * the consent adds exactly one fact beside it - whether a decline was
 * written down. A configuration sits on one rung of the shared ladder and
 * the consent is an annotation of that rung, never a rival ladder.
 *
 * The import-cycle ratchet is what limits the home: this module sits
 * BESIDE the capability tier rather than above it, and it reads the
 * operator's machine configuration directly (`../config.ts`) rather than
 * reaching for the vault configuration, whose loader sits above the search
 * layer and would close a loop. The cost of that choice is stated rather
 * than hidden: the resolver answers for the MACHINE's configuration, which
 * is where the two decline spellings live.
 *
 * ## The fail-closed arm
 *
 * A consent record that cannot be read, and a consent value that cannot
 * be parsed, both resolve to DECLINED. Reading either as "unset" would
 * turn a broken record back into a silent default - the same defect the
 * configuration reader itself refuses elsewhere ("an unreadable config is
 * not consent to print host paths", `src/mcp/vault-path-field.ts`). The
 * default `search_semantic_enabled` is `false`, so "unset" and "off" are
 * the same configuration; a record that cannot be read must not be allowed
 * to look like a record that says nothing, because only one of those two
 * is a decision the operator made. The fail-closed decline is for SPEND
 * surfaces - nothing may be sent on a record nobody read - while
 * {@link ProviderConsent.unreadableReason} lets a diagnostic report the
 * same arm as unmeasured rather than as the operator's decision, and the
 * refusal names the file to repair instead of keys to flip, because a
 * record nobody has read has named no key to clear.
 *
 * ## The two witnesses of a decline
 *
 *   1. `search_semantic_enabled=false` - the switch, in the config file
 *      or in `OPEN_SECOND_BRAIN_SEARCH_SEMANTIC`.
 *   2. `embedding_provider=disabled` - the provider name, in the config
 *      file or in `OPEN_SECOND_BRAIN_EMBEDDING_PROVIDER`.
 *
 * Both are READINGS OF THE RECORD, and nothing else is. The resolved
 * configuration is deliberately NOT a third witness even though it names
 * the sentinel provider whenever the record does: a resolved
 * `provider: "disabled"` is the record seen through the resolver, and
 * treating it as an independent witness would let a configuration that
 * was assembled rather than read - a fixture, an override - claim a
 * decision the operator never wrote down. The record is the only place a
 * decision lives.
 *
 * ## Why there is no membership list and no guard
 *
 * The verdict-vocabulary census enrols a vocabulary by its four pieces -
 * a frozen object, a derived union, a membership list and a guard that
 * takes `unknown`. The states here never cross a string boundary: they
 * are compared in-process and never persisted, never put on a wire and
 * never read back off disk, so a guard that policed a round trip through
 * a string would have nothing to police. The two pieces that earn their
 * place - the frozen object and the derived union - are what ship.
 */

import { discoverConfig, defaultConfigPath, ConfigReadError } from "../config.ts";
import { envOrConfig, parseBool } from "../validate.ts";
import { resolveSemanticCapability, type SemanticCapability } from "./capability-tier.ts";
import type { ResolvedEmbeddingConfig } from "./types.ts";

/**
 * The two consent states. Not a third member for "unknown": an unreadable
 * record resolves to {@link PROVIDER_CONSENT_STATE.declined}, because a
 * record that cannot be read is not a record of consent.
 */
export const PROVIDER_CONSENT_STATE = Object.freeze({
  /** The operator wrote no decision about the provider. */
  unset: "unset",
  /** The operator wrote a decline, or the record could not be read. */
  declined: "declined",
} as const);

export type ProviderConsentState =
  (typeof PROVIDER_CONSENT_STATE)[keyof typeof PROVIDER_CONSENT_STATE];

/**
 * The machine-configuration keys that record a decision about the
 * embedding provider. These are the two spellings the decline has always
 * had; this module names them rather than inventing a third.
 */
export const PROVIDER_CONSENT_KEY = Object.freeze({
  /** The switch that turns the semantic lane on. */
  semantic: "search_semantic_enabled",
  /** The provider name; the sentinel value is the decline. */
  provider: "embedding_provider",
} as const);

/**
 * The environment variables that mirror {@link PROVIDER_CONSENT_KEY}. The
 * environment wins over the config file, which is the rule the search
 * configuration resolver already applies to every key it reads.
 */
export const PROVIDER_CONSENT_ENV = Object.freeze({
  semantic: "OPEN_SECOND_BRAIN_SEARCH_SEMANTIC",
  provider: "OPEN_SECOND_BRAIN_EMBEDDING_PROVIDER",
} as const);

/**
 * The provider name that records a decline. The resolver's default
 * provider is `openai-compat`, so this value is never reached by
 * accident.
 */
export const PROVIDER_CONSENT_DECLINED_PROVIDER = "disabled";

/**
 * The keys that would re-enable a declined provider. Named in every
 * refusal, because a refusal that does not say how to undo it is a
 * sentence the operator has to look up the spelling of.
 */
export const PROVIDER_CONSENT_REENABLE_KEYS: ReadonlyArray<string> = Object.freeze([
  PROVIDER_CONSENT_KEY.semantic,
  PROVIDER_CONSENT_KEY.provider,
]);

/** What the resolver is asked to resolve. */
export interface ProviderConsentRequest {
  /**
   * The configuration file the record is read from. `undefined` reads the
   * process default path; `null` reads no file at all, which is what an
   * environment-only resolution means.
   */
  readonly configPath?: string | null;
  /** The environment, for the environment-over-config rule. */
  readonly env?: NodeJS.ProcessEnv;
  /**
   * The resolved semantic configuration. Optional: the consent state does
   * not depend on it, but the capability tier does, and a caller that
   * holds one should not have to resolve the tier twice.
   */
  readonly semantic?: ResolvedEmbeddingConfig;
}

/** What the resolver concluded. */
export interface ProviderConsent {
  /** Whether a decline was recorded. */
  readonly state: ProviderConsentState;
  /**
   * The shared capability tier, when the caller supplied a resolved
   * configuration. `null` when it did not - never a second ladder.
   */
  readonly capability: SemanticCapability | null;
  /**
   * The keys that record the decline, in the order they were found. Empty
   * when the state is unset, and non-empty for every declined state whose
   * record could be read - an unreadable record names no key, because it
   * named none.
   */
  readonly declineKeys: ReadonlyArray<string>;
  /** The keys that would re-enable a declined provider. */
  readonly reenableKeys: ReadonlyArray<string>;
  /**
   * Why the record could not be read, on the arm where it could not.
   * The resolver still fails closed to {@link PROVIDER_CONSENT_STATE.declined}
   * - an unreadable record is not consent - but a diagnostic that renders
   * that arm as a DECISION would pass a broken machine configuration as
   * one the operator chose. Null on every arm whose record was read.
   */
  readonly unreadableReason: string | null;
  /** The operator-facing sentence. Never empty. */
  readonly detail: string;
}

/**
 * The value that clears each decline key, keyed the way
 * {@link PROVIDER_CONSENT_KEY} is. The two keys decline INDEPENDENTLY -
 * clearing one leaves the other's decline in force - which is why the
 * re-enable sentence is built from the keys this record actually used
 * rather than naming both spellings and letting an operator clear only
 * one of them.
 */
const DECLINE_CLEARING_VALUE: Readonly<Record<string, string>> = Object.freeze({
  [PROVIDER_CONSENT_KEY.semantic]: "true",
  [PROVIDER_CONSENT_KEY.provider]: "<provider>",
});

/**
 * The sentence a refusal carries. Built from `declineKeys`, naming every
 * key that recorded THIS decline and the value that clears it, so the
 * advice is one the operator can follow to the end: following it must
 * never leave them refused by the other key. Named as a KEY, so an
 * operator reading it can search the configuration file for the spelling
 * rather than for a phrase.
 */
function reenableSentence(declineKeys: ReadonlyArray<string>): string {
  const clears = declineKeys.flatMap((key) => {
    const value = DECLINE_CLEARING_VALUE[key];
    return value === undefined ? [] : [`${key}=${value}`];
  });
  return `re-enable it with ${clears.join(" or ")}`;
}

/**
 * The advice an UNREADABLE record carries instead of a re-enable
 * sentence: an unreadable record named no key, so there is no key to
 * clear. The repair is the record itself, and the sentence names the
 * file it lives in.
 */
function repairRecordSentence(configPath: string): string {
  return `repair the configuration file at ${configPath}`;
}

/**
 * How a decline is WRITTEN. Both spellings are named, not only the one
 * this record used: an operator who wrote one of them and is looking at
 * a refusal that names the other needs to see that both spell the same
 * decision.
 */
function declineSpellingsSentence(): string {
  return (
    `a decline is written as ${PROVIDER_CONSENT_KEY.semantic}=false ` +
    `or ${PROVIDER_CONSENT_KEY.provider}=${PROVIDER_CONSENT_DECLINED_PROVIDER}`
  );
}

/** A declined consent whose record was read, with the keys that did it. */
function declined(
  capability: SemanticCapability | null,
  declineKeys: ReadonlyArray<string>,
  reason: string,
): ProviderConsent {
  const recorded =
    declineKeys.length > 0 ? `; this one is recorded by ${declineKeys.join(" and ")}` : "";
  return Object.freeze({
    state: PROVIDER_CONSENT_STATE.declined,
    capability,
    declineKeys: Object.freeze([...declineKeys]),
    reenableKeys: PROVIDER_CONSENT_REENABLE_KEYS,
    unreadableReason: null,
    detail:
      `provider consent declined: no embedding provider will be contacted. ` +
      `${reason}${declineSpellingsSentence()}${recorded}. ` +
      `${reenableSentence(declineKeys)}.`,
  });
}

/**
 * A declined consent whose record could not be READ. Same fail-closed
 * state as {@link declined}, but no key is named - the record named none
 * - and the advice is a repair of the file, not a key to flip: a
 * re-enable sentence would be advice about a record nobody has read.
 * `unreadableReason` is what lets a diagnostic report this arm as
 * unmeasured rather than as an operator's decision.
 */
function declinedUnreadable(
  capability: SemanticCapability | null,
  unreadableReason: string,
  configPath: string,
): ProviderConsent {
  return Object.freeze({
    state: PROVIDER_CONSENT_STATE.declined,
    capability,
    declineKeys: Object.freeze([]),
    reenableKeys: PROVIDER_CONSENT_REENABLE_KEYS,
    unreadableReason,
    detail:
      `provider consent declined: no embedding provider will be contacted. ` +
      `The provider-consent record could not be read (${unreadableReason}), and an ` +
      `unreadable record is not consent. ${declineSpellingsSentence()}. ` +
      `${repairRecordSentence(configPath)}.`,
  });
}

/**
 * Resolve what the operator's configuration says about the embedding
 * provider.
 *
 * Pure with respect to the filesystem in one direction only: it READS the
 * configuration file it is given and never writes one. A record that
 * cannot be read resolves to declined rather than to unset, and a value
 * that cannot be parsed resolves to declined for the same reason.
 */
export function resolveProviderConsent(request: ProviderConsentRequest): ProviderConsent {
  const capability =
    request.semantic === undefined ? null : resolveSemanticCapability(request.semantic);
  const env = request.env ?? process.env;

  // The record. An unreadable one is a decline, never an absence: the
  // operator's settings exist and are not the ones in force, which is
  // exactly what the configuration reader refuses to paper over. The
  // reason rides on the verdict, so a diagnostic can report this arm as
  // unmeasured rather than as a decision the operator made.
  let config: Readonly<Record<string, string>>;
  try {
    config = request.configPath === null ? {} : discoverConfig(request.configPath).data;
  } catch (e) {
    const reason =
      e instanceof ConfigReadError
        ? "the config file exists but could not be read"
        : e instanceof Error
          ? e.message
          : String(e);
    return declinedUnreadable(capability, reason, request.configPath ?? defaultConfigPath());
  }

  const declineKeys: string[] = [];

  // The switch. An unparseable value is a decline too: the operator wrote
  // something they meant to be a decision, and reading it as "unset"
  // would silently drop it.
  const semanticRaw = envOrConfig(
    env,
    config,
    PROVIDER_CONSENT_ENV.semantic,
    PROVIDER_CONSENT_KEY.semantic,
  );
  if (semanticRaw !== null) {
    let enabled: boolean;
    try {
      enabled = parseBool(semanticRaw, false, PROVIDER_CONSENT_KEY.semantic);
    } catch {
      return declined(
        capability,
        [PROVIDER_CONSENT_KEY.semantic],
        `The provider-consent record could not be parsed, and an unparseable record is not consent. `,
      );
    }
    if (!enabled) declineKeys.push(PROVIDER_CONSENT_KEY.semantic);
  }

  // The provider name. The sentinel value is the decline; every other
  // name is a provider the operator chose.
  const providerRaw = envOrConfig(
    env,
    config,
    PROVIDER_CONSENT_ENV.provider,
    PROVIDER_CONSENT_KEY.provider,
  );
  if (
    providerRaw !== null &&
    providerRaw.trim().toLowerCase() === PROVIDER_CONSENT_DECLINED_PROVIDER
  ) {
    declineKeys.push(PROVIDER_CONSENT_KEY.provider);
  }

  if (declineKeys.length > 0) {
    return declined(capability, declineKeys, "");
  }

  return Object.freeze({
    state: PROVIDER_CONSENT_STATE.unset,
    capability,
    declineKeys: Object.freeze([]),
    reenableKeys: PROVIDER_CONSENT_REENABLE_KEYS,
    unreadableReason: null,
    detail: "no provider-consent decision is recorded: the embedding provider was never declined.",
  });
}

/**
 * Whether the consent is a decline. A predicate rather than a comparison
 * at the call site, so the state is read the same way everywhere.
 */
export function providerConsentIsDeclined(consent: ProviderConsent): boolean {
  return consent.state === PROVIDER_CONSENT_STATE.declined;
}