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
7.9 KB
Raw Blame
/**
 * Names, classification and values of the shared brain settings: the
 * part of `./settings-write.ts` that touches no storage. A name is
 * `<block>.<field>` (or a scalar key such as `primary_agent`, with an
 * optional `brain.` prefix); it is classified by `./settings-keys.ts`, so
 * only a `shared` key resolves, a `device` key is refused with the
 * machine-config key that holds it, and `schema_version` is no setting.
 * A value is what the `_brain.yaml` parser reads: a scalar, or a list of
 * scalars.
 *
 * A few settings are native to the store and have no `_brain.yaml` home
 * ({@link STORE_NATIVE_SETTINGS}): they keep their own key (no `brain.`
 * prefix), are written as store records on every machine, and carry their
 * own validator.
 */

import { SETTING_RULES } from "../../store/fold-settings.ts";
import { SETTING_VIEW_LANGUAGE } from "../../store/constants.ts";
import {
  parsePermissionsDocumentText,
  PERMISSIONS_DOCUMENT_SETTING,
} from "../permissions/document.ts";
import { DEFAULT_VIEW_LANGUAGE, isViewLanguage, VIEW_LANGUAGES } from "../../view/i18n.ts";
import { DEFAULT_BRAIN_CONFIG } from "./defaults.ts";
import { brainConfigKey, brainKeyHome, brainSettingKey } from "./settings-keys.ts";
import type { YamlSettingValue } from "./settings-yaml-edit.ts";

/** Who writes a setting: the operator at the CLI, or an agent over MCP. */
export type SettingAuthority = "human" | "agent";

/** Why a settings operation was refused. */
export type BrainSettingErrorCode =
  | "unknown_setting"
  | "device_setting"
  | "not_a_setting"
  | "field_required"
  | "invalid_setting_value"
  | "human_value_in_force"
  | "operator_only_setting"
  | "private_setting_value"
  | "no_settings_file"
  | "settings_unreadable";

export class BrainSettingError extends Error {
  readonly code: BrainSettingErrorCode;
  /** For `device_setting`: the machine-config key that holds this value. */
  readonly configKey?: string;

  constructor(code: BrainSettingErrorCode, message: string, configKey?: string) {
    super(message);
    this.name = "BrainSettingError";
    this.code = code;
    if (configKey !== undefined) this.configKey = configKey;
  }
}

export interface SettingTarget {
  readonly block: string;
  readonly field: string | undefined;
  readonly name: string;
  readonly key: string;
  /** Set for a store-native setting: its validator and default. */
  readonly native?: StoreNativeSetting;
}

/** A setting that lives in the store only, under its own key. */
export interface StoreNativeSetting {
  /** `null` when `value` is valid, else why it is not. */
  readonly invalid: (value: unknown) => string | null;
  /** What applies when the setting is not set. */
  readonly default: unknown;
  /** Only the operator (human authority) sets it: it holds a safety boundary. */
  readonly operatorOnly?: true;
}

/** The store-native settings, by name (which is also the store key). */
export const STORE_NATIVE_SETTINGS: Readonly<Record<string, StoreNativeSetting>> = Object.freeze({
  [SETTING_VIEW_LANGUAGE]: {
    invalid: (value: unknown) =>
      SETTING_RULES[SETTING_VIEW_LANGUAGE].valid(value) && isViewLanguage(value as string)
        ? null
        : `${SETTING_VIEW_LANGUAGE} must be a language the human view has strings for: ` +
          `${VIEW_LANGUAGES.join(", ")} (a regional tag such as ru-RU is accepted)`,
    default: DEFAULT_VIEW_LANGUAGE,
  },
  // The permissions document of a store-only machine (`_permissions.yaml`
  // once switched): its whole text, validated by the document's own
  // parser. Operator-only: it is the write gate an agent passes through.
  [PERMISSIONS_DOCUMENT_SETTING]: {
    invalid: (value: unknown) => {
      if (typeof value !== "string")
        return `${PERMISSIONS_DOCUMENT_SETTING} must be the YAML text of a permissions document`;
      try {
        parsePermissionsDocumentText(value, PERMISSIONS_DOCUMENT_SETTING);
        return null;
      } catch (err) {
        return err instanceof Error ? err.message : String(err);
      }
    },
    default: null,
    operatorOnly: true,
  },
});

function nativeTarget(name: string): SettingTarget | undefined {
  if (!Object.hasOwn(STORE_NATIVE_SETTINGS, name)) return undefined;
  const dot = name.indexOf(".");
  return {
    block: name.slice(0, dot),
    field: name.slice(dot + 1),
    name,
    key: name,
    native: STORE_NATIVE_SETTINGS[name]!,
  };
}

export const KEY_PREFIX = "brain.";
const NAME_RE = /^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)?$/;

/** The shipped default of `block` or `block.field`, `undefined` when none. */
export function defaultOf(block: string, field: string | undefined): unknown {
  const top = (DEFAULT_BRAIN_CONFIG as unknown as Record<string, unknown>)[block];
  if (field === undefined) return top;
  return top !== null && typeof top === "object"
    ? (top as Record<string, unknown>)[field]
    : undefined;
}

/**
 * Whether `block` holds fields: an object default, or no default at all
 * (every top-level key without a shipped default is a block; a scalar key
 * such as `primary_agent` ships a `null` default).
 */
function isBlockWithFields(block: string): boolean {
  const top = defaultOf(block, undefined);
  if (top !== null && typeof top === "object" && !Array.isArray(top)) return true;
  return top === undefined;
}

/** Resolve and classify a setting name; throws {@link BrainSettingError}. */
export function resolveSettingName(raw: string): SettingTarget {
  const trimmed = raw.trim();
  const name = trimmed.startsWith(KEY_PREFIX) ? trimmed.slice(KEY_PREFIX.length) : trimmed;
  // The `brain.` prefix is accepted for a native setting too, as for every other one.
  const native = nativeTarget(trimmed) ?? nativeTarget(name);
  if (native !== undefined) return native;
  if (!NAME_RE.test(name)) {
    throw new BrainSettingError(
      "unknown_setting",
      `"${raw}" is not a brain setting name; use <block>.<field>, for example dream.candidate_threshold`,
    );
  }
  const dot = name.indexOf(".");
  const block = dot === -1 ? name : name.slice(0, dot);
  const field = dot === -1 ? undefined : name.slice(dot + 1);
  const home = brainKeyHome(block, field);
  if (home === undefined) {
    throw new BrainSettingError("unknown_setting", `"${name}" is not a brain setting`);
  }
  if (home === "drop") {
    throw new BrainSettingError("not_a_setting", `"${name}" is the format version, not a setting`);
  }
  if (home === "device") {
    const configKey = brainConfigKey(block, field);
    throw new BrainSettingError(
      "device_setting",
      `"${name}" is a setting of this machine, not a shared one: add ` +
        `\`${configKey}: <JSON value>\` to the machine config instead`,
      configKey,
    );
  }
  if (field === undefined && isBlockWithFields(block)) {
    throw new BrainSettingError(
      "field_required",
      `"${name}" is a block; name one of its fields, for example ${block}.<field>`,
    );
  }
  if (field !== undefined && !isBlockWithFields(block)) {
    throw new BrainSettingError("unknown_setting", `"${block}" takes a single value, not fields`);
  }
  return { block, field, name, key: brainSettingKey(block, field) };
}

/** The device-key refusal, with the value filled in when one is known. */
export function withDeviceValue(err: unknown, value: unknown): unknown {
  if (!(err instanceof BrainSettingError) || err.code !== "device_setting") return err;
  return new BrainSettingError(
    "device_setting",
    err.message.replace("<JSON value>", JSON.stringify(value)),
    err.configKey,
  );
}

/** A CLI value: JSON when it parses, else the bare string. */
export function parseSettingValue(raw: string): unknown {
  try {
    return JSON.parse(raw) as unknown;
  } catch {
    return raw;
  }
}

function isYamlScalar(value: unknown): boolean {
  return value === null || ["string", "number", "boolean"].includes(typeof value);
}

export function isYamlValue(value: unknown): value is YamlSettingValue {
  return isYamlScalar(value) || (Array.isArray(value) && value.every(isYamlScalar));
}