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
5.1 KB
Raw Blame
/**
 * Adaptive tool-surface profiles (Agent Surface Suite, t_20dcb192).
 *
 * A profile names a curated MCP surface: a ToolScope plus an optional
 * RuntimeCapabilityWindow. Hosts pick one via the `mcp_tool_profile`
 * config key or `o2b mcp --tool-profile <name>` instead of hand-rolling
 * allow/deny flag lists per platform.
 *
 * Contract (mirrors upstream Hermes Tool Slimmer): selection FAILS
 * OPEN - an unknown profile name degrades to the full surface (with
 * the unknown name surfaced for logging), never locks an agent out.
 * Hard-window profiles (`recall`, `minimal`) always retain the
 * `second_brain_capabilities` diagnostic, which reports every withheld
 * tool with its reason; schema hydration via `tool_hydrate` stays on
 * the `catalog` and `full` surfaces, where every catalogued tool is
 * actually callable.
 */

import type { RuntimeCapabilityWindow } from "./capabilities.ts";
import type { ToolScope } from "./tool-contract.ts";

export interface ToolSurfaceProfile {
  readonly name: string;
  readonly description: string;
  readonly scope: ToolScope;
  readonly window?: RuntimeCapabilityWindow;
}

/** The always-loaded Brain writer/reader set (writer scope parity). */
const WRITER_SET = [
  "brain_apply_evidence",
  "brain_context",
  "brain_feedback",
  "brain_note",
  "brain_pinned_context",
] as const;

export const TOOL_SURFACE_PROFILES: Readonly<Record<string, ToolSurfaceProfile>> = Object.freeze({
  full: Object.freeze({
    name: "full",
    description: "Every tool advertised (default).",
    scope: "full",
  }),
  writer: Object.freeze({
    name: "writer",
    description: "Always-loaded Brain writers plus the context reader.",
    scope: "writer",
  }),
  catalog: Object.freeze({
    name: "catalog",
    description: "Two-pass surface: compact first pass, schemas via tool_hydrate.",
    scope: "catalog",
  }),
  recall: Object.freeze({
    name: "recall",
    description: "Memory read/write surface for recall-heavy hosts; no admin tools.",
    scope: "full",
    window: Object.freeze({
      allowedTools: Object.freeze([
        ...WRITER_SET,
        "brain_search",
        "brain_recall_gate",
        "brain_recall_feedback",
        "brain_context_pack",
        "brain_artifact_get",
      ]),
    }),
  }),
  minimal: Object.freeze({
    name: "minimal",
    description: "Floor surface for constrained hosts: writers, context, search.",
    scope: "full",
    window: Object.freeze({
      allowedTools: Object.freeze([...WRITER_SET, "brain_search"]),
    }),
  }),
});

export function toolSurfaceProfileNames(): string[] {
  return Object.keys(TOOL_SURFACE_PROFILES);
}

export interface ResolveToolSurfaceOptions {
  /** Profile name from --tool-profile or the mcp_tool_profile key. */
  readonly profileName?: string | null;
  /** Explicit --scope value; wins over the profile's scope. */
  readonly explicitScope?: ToolScope;
  /** Explicit window flags; fields win over the profile's window. */
  readonly explicitWindow?: RuntimeCapabilityWindow;
}

export interface ResolvedToolSurface {
  readonly scope: ToolScope;
  readonly window?: RuntimeCapabilityWindow;
  /** The profile that applied ("full" when none/unknown). */
  readonly profile: string;
  /**
   * Set when the requested profile did not exist. `o2b mcp` refuses to
   * start on it (fail closed); the scope/window fields beside it are the
   * no-profile defaults and must not be served.
   */
  readonly unknownProfile?: string;
}

function mergeWindows(
  profile: RuntimeCapabilityWindow | undefined,
  explicit: RuntimeCapabilityWindow | undefined,
): RuntimeCapabilityWindow | undefined {
  if (profile === undefined) return explicit;
  if (explicit === undefined) return profile;
  return {
    ...((explicit.allowedTools ?? profile.allowedTools)
      ? { allowedTools: explicit.allowedTools ?? profile.allowedTools! }
      : {}),
    ...((explicit.disabledTools ?? profile.disabledTools)
      ? { disabledTools: explicit.disabledTools ?? profile.disabledTools! }
      : {}),
    ...((explicit.maxTools ?? profile.maxTools) !== undefined
      ? { maxTools: (explicit.maxTools ?? profile.maxTools)! }
      : {}),
  };
}

/**
 * Resolve the effective surface. An unknown profile is reported through
 * `unknownProfile`, and the caller must refuse it rather than serve the
 * defaults returned beside it.
 */
export function resolveToolSurface(opts: ResolveToolSurfaceOptions): ResolvedToolSurface {
  const requested = opts.profileName?.trim() || null;
  if (requested === null) {
    return {
      scope: opts.explicitScope ?? "full",
      ...(opts.explicitWindow ? { window: opts.explicitWindow } : {}),
      profile: opts.explicitScope ?? "full",
    };
  }
  const profile = TOOL_SURFACE_PROFILES[requested];
  if (profile === undefined) {
    return {
      scope: opts.explicitScope ?? "full",
      ...(opts.explicitWindow ? { window: opts.explicitWindow } : {}),
      profile: "full",
      unknownProfile: requested,
    };
  }
  const window = mergeWindows(profile.window, opts.explicitWindow);
  return {
    scope: opts.explicitScope ?? profile.scope,
    ...(window ? { window } : {}),
    profile: profile.name,
  };
}