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
6.8 KB
Raw Blame
/**
 * The host-dependent dimensions of the generated MCP payload.
 *
 * {@link buildPayload} is pure and stays that way: same config in, same
 * two entries out. What it cannot know is WHICH runtime the entries are
 * about, and two things in the registration depend on exactly that:
 *
 *   - the tool-surface profile a capped host needs. Cursor sends at
 *     most the first forty tools of every enabled MCP server to the
 *     model; the full surface advertises a hundred and ten, so without
 *     a profile the host drops seventy of them and says nothing.
 *   - the runtime's own id, so the server the payload launches can name
 *     its host in `second_brain_capabilities` instead of reporting a
 *     ceiling it has no way to look up.
 *
 * Both are applied HERE rather than inside `buildPayload` because they
 * are impure - the profile walks the environment, the committed
 * `<vault>/Brain/_brain.yaml` and the machine-local config before
 * falling back to the host row - and because the adapters are the only
 * callers that know a target at all. `install --target generic` prints
 * a payload for a host it was never told the name of and therefore
 * never comes through here.
 *
 * The rule that constrains the shape: `verify()` reconstructs the
 * expected payload from {@link InstallEnv} ALONE, never from a stored
 * hash. Every argument added here is therefore a pure function of the
 * `InstallEnv` plus the target id the adapter carries in its spec, so
 * apply and verify compute byte-identical args and a fresh install
 * reports no drift.
 */

import { installSettingsSource, resolveInstallToolProfile } from "./settings.ts";
import type { InstallEnv, McpPayload, McpServerEntry } from "./types.ts";
import { INSTALL_TARGET_ID, type InstallTargetId } from "../runtime/host-facts.ts";
import type { ResolvedInstallSetting } from "./settings.ts";

/** Names the runtime the generated entry was written for. */
export const HOST_TARGET_FLAG = "--host-target";
/** Names the tool-surface profile the generated entry selects. */
export const TOOL_PROFILE_FLAG = "--tool-profile";

/**
 * The targets whose generated registration passes through
 * {@link payloadForHost}, and therefore carries the host dimensions.
 *
 * Three of the ten do not, and it is not an oversight: `generic` prints a
 * payload for a host it was never told the name of, `aider` is wired
 * through a managed YAML block and a sidecar context file rather than an
 * MCP server, and `pi` is a skill symlink. None of the three writes an MCP
 * command line at all, so there is nothing for `--tool-profile` or
 * `--host-target` to land on.
 *
 * Declared here because this is the module the dimensions live in, and
 * read by everything that must not claim a dimension a target never
 * carries: `o2b update`'s payload hash, and `--friction`'s profile cell -
 * which printed `generic tool-profile minimal` for a registration that
 * carries no profile flag at all.
 * `tests/core/install/payload-host.test.ts` holds the declaration against
 * the artifacts the ten adapters actually write.
 */
export const HOST_PAYLOAD_TARGETS: ReadonlySet<InstallTargetId> = Object.freeze(
  new Set<InstallTargetId>([
    INSTALL_TARGET_ID.codex,
    INSTALL_TARGET_ID.copilotCli,
    INSTALL_TARGET_ID.cursor,
    INSTALL_TARGET_ID.geminiCli,
    INSTALL_TARGET_ID.grok,
    INSTALL_TARGET_ID.kiro,
    INSTALL_TARGET_ID.opencode,
  ]),
);

/** Whether `target`'s generated registration carries the host dimensions. */
export function carriesHostDimensions(target: InstallTargetId): boolean {
  return HOST_PAYLOAD_TARGETS.has(target);
}

/**
 * The profile `target`'s registration will actually carry, or `null` when
 * the registration carries no profile at all.
 *
 * The two `null`s are different answers and both are honest: a member of
 * {@link HOST_PAYLOAD_TARGETS} whose ladder resolves to `null` writes a
 * flag-free MCP command line, while a non-member writes no MCP command
 * line for a flag to be absent from. Callers that print the answer say
 * which one they mean.
 */
export function writtenToolProfile(
  target: InstallTargetId,
  env: InstallEnv,
): ResolvedInstallSetting<string | null> | null {
  if (!carriesHostDimensions(target)) return null;
  return resolveInstallToolProfile(installSettingsSource(env), target);
}

/**
 * The canonical payload with this host's dimensions baked in.
 *
 * The profile lands on the FULL entry only. The writer entry advertises
 * five tools on every host in the table, so no ceiling can bind it and
 * naming a profile there would only be a second place for the two to
 * disagree. `--host-target` lands on both, because the ceiling question
 * is about the host and both servers run on it.
 */
export function payloadForHost(
  target: InstallTargetId,
  payload: McpPayload,
  env: InstallEnv,
): McpPayload {
  const resolved = writtenToolProfile(target, env);
  if (resolved === null) {
    // A caller outside {@link HOST_PAYLOAD_TARGETS} is a programming
    // error, not an operator one: the declaration and the routing would
    // have silently disagreed, and every surface that reads the
    // declaration to describe the registration would have described the
    // wrong one.
    throw new Error(
      `payloadForHost: ${target} is not declared in HOST_PAYLOAD_TARGETS; ` +
        "add it there, or stop routing this target's payload through here",
    );
  }
  const profile = resolved.value;
  return {
    full: withArgs(payload.full, [
      ...(profile === null ? [] : [TOOL_PROFILE_FLAG, profile]),
      HOST_TARGET_FLAG,
      target,
    ]),
    writer: withArgs(payload.writer, [HOST_TARGET_FLAG, target]),
  };
}

/**
 * The payload `target` will actually be registered with, whether or not
 * that target carries host dimensions.
 *
 * The total function {@link payloadForHost} deliberately is not. It exists
 * for `o2b update`, which decides whether an installed target needs
 * re-applying by hashing the payload and comparing it against the stored
 * `payload_hash`: a hash taken over the CANONICAL payload cannot see the
 * host dimensions, so an operator whose vault, agent name and timezone
 * were unchanged got "up-to-date, payload unchanged" while `--check`
 * reported drift on the same target, and a 110-tool registration stayed
 * under Cursor's 40-tool ceiling. Hashing what is written closes that,
 * and hashing the canonical payload for the three targets that write no
 * MCP command line keeps the hash from claiming dimensions they do not
 * carry.
 */
export function payloadAsWritten(
  target: InstallTargetId,
  payload: McpPayload,
  env: InstallEnv,
): McpPayload {
  return carriesHostDimensions(target) ? payloadForHost(target, payload, env) : payload;
}

/** One entry with `extra` appended; argument order is the byte identity. */
function withArgs(entry: McpServerEntry, extra: ReadonlyArray<string>): McpServerEntry {
  return { ...entry, args: [...entry.args, ...extra] };
}