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
11.6 KB
Raw Blame
/**
 * The `vault_path` field an MCP tool response carries.
 *
 * By default this is the opaque, stable store reference
 * (`vault://<hex>`) rather than the absolute host path, since MCP
 * responses land in model context. The `expose_host_paths` config escape
 * hatch restores the raw path for operators whose tooling depends on it
 * (D2).
 *
 * Both branches read the device-local config - the escape hatch is a
 * config flag and the reference is keyed by a config-held secret - so an
 * unreadable config leaves this field, and ONLY this field, unresolvable.
 * It reports the reason rather than raising, because raising here took
 * down whole diagnostic payloads on their very last field. Degrading to
 * the raw host path instead would breach the redaction contract this
 * function exists to enforce, so there is no value to fall back to.
 *
 * The reason it reports is {@link CONFIG_UNREADABLE_REASON} rather than
 * the error's own message, which names the config file - a path under
 * the operator's home, in the one field written to keep host paths out
 * of model context.
 *
 * ## Why it is a module of its own
 *
 * It used to be a private function inside `./tools.ts`, where the ten
 * Brain domain modules that emit the same field could not reach it -
 * `tools.ts` imports them, so importing it back would close the cycle
 * `tests/core/architecture/import-cycles.test.ts` gates. So they emitted
 * `ctx.vault` instead, and the contract above was honoured at three
 * sites of forty-four. A contract with one implementation needs that
 * implementation to be reachable from every site it governs; this leaf
 * imports nothing from the tool surface, so it is.
 *
 * `tests/core/architecture/vault-path-census.test.ts` is what keeps the
 * next site from finding its own way to say `ctx.vault`.
 */

import { ConfigReadError, resolveExposeHostPaths, vaultStoreReference } from "../core/config.ts";
import {
  SecretStoreKeyfileMissingError,
  SecretStoreLockedError,
} from "../core/brain/secrets/envelope.ts";
import { SecretReferenceError } from "../core/secret-ref.ts";
import { escapeRegex } from "../core/strings.ts";
import type { UnresolvedField } from "../core/vault-presence.ts";
import type { OutputSchema } from "./output-contract.ts";

/**
 * A field whose value could not be resolved, carrying the reason. Same
 * shape `toolStatus` already degrades the `vault` block to when the vault
 * scope cannot be resolved, and `buildSearchStatusBlock` its own: the
 * failure is a value the consumer reads, never a key it has to notice is
 * missing.
 */
export function unresolvedField(err: Error): UnresolvedField {
  return { error: err.message };
}

/**
 * How a declared `outputSchema` describes the field.
 *
 * The value is `string | { error: string }` and the output-contract
 * descriptor language (`src/core/brain/response-shape.ts`) has no union
 * form - no `oneOf`, no `anyOf`. Two schemas used to say `type:
 * "string"`, which was true of what they emitted (the raw host path) and
 * false of what this function returns: on an unreadable config the
 * server's `assertOutputContract` would reject the degraded value and
 * destroy the whole payload, on precisely the condition the degraded
 * value exists to report.
 *
 * So the descriptor widens to the honest form the same schemas already
 * use for a field they cannot narrow (`generated_at: {}`), and it is
 * named ONCE here rather than spelled twice, so the two schemas cannot
 * drift from each other or from the producer above.
 */
export const VAULT_PATH_OUTPUT_SCHEMA: OutputSchema = Object.freeze({});

/**
 * The one field the path POLICY reads: which config decides it.
 *
 * Declared structurally rather than as {@link ServerContext} so the
 * OpenClaw plugin - a second runtime with its own context shape, and
 * three emissions of this same field - can reach it. A contract honoured
 * on one runtime and not the other is the defect this module exists to
 * close, one surface over.
 *
 * Split from {@link VaultPathSource} because the policy readers below
 * take a path (or a sentence) as their subject and never look at
 * `ctx.vault`: asking them for a vault they ignore reads as if the vault
 * were the thing being rendered.
 */
export interface HostPathPolicySource {
  readonly configPath?: string | null;
}

/** The policy source plus the vault {@link vaultPathField} renders. */
export interface VaultPathSource extends HostPathPolicySource {
  readonly vault: string;
  /** `null` on a server with no vault (design D14); `vault` is then never read. */
  readonly vaultOrNull?: string | null;
}

/**
 * The contract above, applied to any absolute host path.
 *
 * `vaultStoreReference` never required the path to be the vault - it
 * keys an HMAC over whatever it is handed - and the redaction contract
 * is about the response landing in model context, which is equally true
 * of a linked project's directory. `second_brain_wiring` renders both
 * sides of a project link through this, so there is one path policy on
 * this surface rather than a second one written for the second field.
 */
/**
 * What the degraded field says instead of {@link ConfigReadError}'s own
 * message.
 *
 * That message names the config file twice - once in the condition and
 * once in the `chmod` remedy - and it is right to, on the four channels
 * it was written for: a CLI refusal, an MCP error envelope, a hook's
 * stderr, and the two read-only diagnostics whose whole job is to name
 * the broken file. This is none of those. It is the field forty-five
 * tools emit into model context precisely so that an absolute host path
 * does not travel there, and the config file lives under the operator's
 * home. Reporting the condition by naming that path would reintroduce,
 * in the degraded branch, the leak the resolved branch exists to
 * prevent.
 *
 * Nothing is lost to the operator: `second_brain_status` and
 * `vault_health` still name the file, from their own fields, under the
 * contract that says those fields may.
 */
export const CONFIG_UNREADABLE_REASON =
  "the device-local config could not be read, so this reference cannot be " +
  "resolved; call second_brain_status for the file and the remedy";

/**
 * What the degraded field says when the installation secret resolves
 * through the vault's custody store and the store refuses: the keyfile is
 * passphrase-wrapped and this process holds no unlocked key.
 *
 * The named error's own message carries the keyfile path under the vault -
 * the same host path this field exists to keep out of model context - so
 * the remedy is restated here without it, exactly as
 * {@link CONFIG_UNREADABLE_REASON} restates its remedy without the config
 * path.
 */
export const SECRET_STORE_LOCKED_REASON =
  "the vault's credential store is locked, so the installation secret " +
  "reference cannot be resolved; set OPEN_SECOND_BRAIN_SECRETS_PASSPHRASE " +
  "for the server process, pass --passphrase-from-env or the passphrase on " +
  "stdin to any key-bearing verb, or run `o2b brain secret unwrap` to " +
  "return the store to its raw state";

/**
 * What the degraded field says when the vault's credential store still
 * holds entries but its keyfile is gone: the read-only resolve refuses
 * rather than minting a fresh key over the surviving ciphertext.
 *
 * The named error's message is already path-free, but this field degrades
 * every store refusal to its own short reason for the same reason the
 * locked state does: the field is a path field, and its error arm is a
 * named state, not a channel for the store's prose.
 */
export const SECRET_STORE_KEYFILE_MISSING_REASON =
  "the vault's credential store is missing its keyfile, so the installation " +
  "secret reference cannot be resolved; restore the keyfile and retry";

/**
 * What the degraded field says when the persisted installation secret is a
 * `$secret:` reference the vault's custody store cannot answer: the name
 * is absent from the store and the environment, or the reference is
 * malformed.
 *
 * The named error's message repeats the reference name or the raw value;
 * neither belongs in model context. The operator inspects the device
 * config and the store through the surfaces that may name them
 * (`second_brain_status`, `o2b secrets list`).
 */
export const SECRET_REFERENCE_UNRESOLVED_REASON =
  "the installation secret is a $secret: reference the vault's credential " +
  "store cannot resolve; inspect the device config and the store with " +
  "`o2b secrets list`";

export function hostPathReference(
  path: string,
  source: HostPathPolicySource,
): string | UnresolvedField {
  const configPath = source.configPath ?? undefined;
  try {
    return resolveExposeHostPaths(configPath) ? path : vaultStoreReference(path, configPath);
  } catch (err) {
    if (err instanceof ConfigReadError) return { error: CONFIG_UNREADABLE_REASON };
    if (err instanceof SecretStoreLockedError) return { error: SECRET_STORE_LOCKED_REASON };
    if (err instanceof SecretStoreKeyfileMissingError) {
      return { error: SECRET_STORE_KEYFILE_MISSING_REASON };
    }
    if (err instanceof SecretReferenceError) return { error: SECRET_REFERENCE_UNRESOLVED_REASON };
    throw err;
  }
}

/**
 * The contract above, as the one value every emitting site returns:
 * `null` on a server with no vault, which has no vault path to render.
 */
export function vaultPathField(ctx: VaultPathSource): string | UnresolvedField | null {
  if (ctx.vaultOrNull === null) return null;
  return hostPathReference(ctx.vault, ctx);
}

/** How a folded path names the host home. */
const HOME_REFERENCE = "~";

/**
 * The shortest home this function will fold.
 *
 * A home of `/` (or the empty string an unresolved lookup leaves) is a
 * prefix of every absolute path on the machine, so folding it would
 * rewrite unrelated paths into nonsense rather than redact anything.
 */
const SHORTEST_FOLDABLE_HOME = 2;

/**
 * What may NOT follow the home for the match to be the home.
 *
 * A plain prefix replacement run under a home named `dev` would clip a
 * sibling named `developer` in the same sentence into `~eloper`: a
 * mangled path is worse than either the raw one or the folded one,
 * because it names a file that does not exist. The home matches only
 * where the next character cannot continue a directory name - a
 * separator, punctuation, whitespace, or the end of the sentence.
 */
const NAME_CHARACTER = "[A-Za-z0-9._-]";

/**
 * Free-form adapter prose with the host home folded to `~`.
 *
 * `verify()` composes its `details` and `fix_hint` sentences from
 * `InstallEnv.home`, so a drifted install names an absolute path under
 * the operator's account - in the same MCP payload whose `vault_path`
 * was deliberately reduced to an opaque reference. {@link
 * hostPathReference} does not apply: a store reference keys the VAULT,
 * and hashing a third party's `~/.grok/hooks/...` would name nothing the
 * reader can act on.
 *
 * So the home PREFIX is folded instead. The file stays identifiable, the
 * account name does not travel, and the rewrite is one exact
 * substitution of a string this run resolved - never a search for
 * path-shaped text inside a sentence.
 *
 * Fails closed: an unreadable config folds, because printing raw host
 * paths is the branch an operator opts into.
 */
export function foldHostHome(text: string, home: string, source: HostPathPolicySource): string {
  if (home.length < SHORTEST_FOLDABLE_HOME) return text;
  try {
    if (resolveExposeHostPaths(source.configPath ?? undefined)) return text;
  } catch (err) {
    if (!(err instanceof ConfigReadError)) throw err;
    // Fall through and fold: an unreadable config is not consent to
    // print host paths, and the branch that prints them is opt-in.
  }
  return text.replace(new RegExp(`${escapeRegex(home)}(?!${NAME_CHARACTER})`, "g"), HOME_REFERENCE);
}