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
14.1 KB
Raw Blame
/**
 * Shared coercion helpers for MCP tool handlers.
 *
 * Used by tools.ts, brain-tools.ts, and search-tools.ts to validate
 * and cast incoming JSON-RPC arguments. All helpers throw `MCPError`
 * with `INVALID_PARAMS` on bad input.
 */

import { refuseOwnerScopeRequest } from "./owner-scope-refusal.ts";
import { INVALID_PARAMS, MCPError } from "./protocol.ts";
import { TOOL_ERROR_CODE } from "./tool-error-codes.ts";

export function coerceStr(
  args: Record<string, unknown>,
  key: string,
  required = true,
  defaultValue: string | null = null,
): string | null {
  const value = args[key];
  if (value === undefined || value === null || (typeof value === "string" && value.trim() === "")) {
    if (required) throw new MCPError(INVALID_PARAMS, `missing required argument: ${key}`);
    return defaultValue;
  }
  if (typeof value !== "string")
    throw new MCPError(INVALID_PARAMS, `argument '${key}' must be a string`);
  return value;
}

export function coerceStrList(args: Record<string, unknown>, key: string): string[] {
  const value = args[key];
  if (value === undefined || value === null) return [];
  if (!Array.isArray(value) || !value.every((v) => typeof v === "string")) {
    throw new MCPError(INVALID_PARAMS, `argument '${key}' must be a list of strings`);
  }
  return [...value] as string[];
}

export function coerceInt(
  args: Record<string, unknown>,
  key: string,
  defaultValue: number,
  min: number,
  max: number,
): number {
  const value = args[key] ?? defaultValue;
  if (typeof value === "boolean" || typeof value !== "number" || !Number.isInteger(value)) {
    throw new MCPError(INVALID_PARAMS, `argument '${key}' must be an integer`);
  }
  if (value < min || value > max) {
    throw new MCPError(INVALID_PARAMS, `argument '${key}' must be between ${min} and ${max}`);
  }
  return value;
}

export function coerceBool(args: Record<string, unknown>, key: string): boolean {
  const value = args[key];
  if (value === undefined || value === null) return false;
  if (typeof value !== "boolean")
    throw new MCPError(INVALID_PARAMS, `argument '${key}' must be a boolean`);
  return value;
}

export function coerceBoolOptional(
  args: Record<string, unknown>,
  key: string,
): boolean | undefined {
  if (!(key in args)) return undefined;
  const v = args[key];
  if (v === undefined || v === null) return undefined;
  if (typeof v !== "boolean")
    throw new MCPError(INVALID_PARAMS, `argument '${key}' must be a boolean`);
  return v;
}

export function coerceStringOptional(
  args: Record<string, unknown>,
  key: string,
  maxLen: number,
): string | undefined {
  if (!(key in args)) return undefined;
  const v = args[key];
  if (v === undefined || v === null) return undefined;
  if (typeof v !== "string")
    throw new MCPError(INVALID_PARAMS, `argument '${key}' must be a string`);
  if (v.length > maxLen)
    throw new MCPError(INVALID_PARAMS, `argument '${key}' exceeds ${maxLen} characters`);
  return v;
}

/**
 * Input-schema fragment for the owner-scope argument
 * (context-integrity-gates, Unit A). Declared once so eleven tools
 * cannot grow eleven descriptions of the same argument.
 */
export const AGENT_SCOPE_ARG_NAME = "agent_scope";

/** Longest accepted owner token; an agent name, not a document. */
const AGENT_SCOPE_MAX_LEN = 128;

export const AGENT_SCOPE_SCHEMA = Object.freeze({
  type: "string",
  description:
    "Optional agent-ownership scope; shared (ownerless) memories always match, owner-tagged memories only their owner. Absent = no ownership filtering.",
});

/**
 * Read the owner scope a content-returning tool was called with - the
 * ONE reader of {@link AGENT_SCOPE_ARG_NAME} in this tree, asserted by
 * `tests/mcp/owner-scope-refusal.test.ts`. A tool that spells the
 * argument itself would opt out of the identity check below, which is
 * the class of defect this seam exists to make impossible.
 *
 * `fallbackToServerIdentity` is for the GATED preference-backed
 * surfaces: with no explicit argument they scope to the process's own
 * agent identity, which is what makes `owner_scope_delivery: fail`
 * effective for clients that never pass the argument. It is safe there
 * and only there, because those surfaces filter nothing until the
 * operator sets the gate. The ungated search-backed surfaces pass
 * `false`, so an omitted argument keeps them byte-identical.
 *
 * An EXPLICIT argument is checked against the server-resolved identity
 * under `owner_scope_delivery: fail` and refused when it names another
 * owner - see {@link refuseOwnerScopeRequest} for why refusing beats
 * narrowing. `ctx.agentName` is read only on that path and only when a
 * scope was supplied, so a call that asks for nothing costs nothing and
 * a vault that never opted in is untouched.
 */
export function coerceAgentScope(
  ctx: { readonly vault: string; readonly agentName?: string },
  args: Record<string, unknown>,
  fallbackToServerIdentity: boolean,
): string | undefined {
  const explicit = coerceStringOptional(args, AGENT_SCOPE_ARG_NAME, AGENT_SCOPE_MAX_LEN);
  if (explicit === undefined) return fallbackToServerIdentity ? ctx.agentName : undefined;
  const refused = refuseOwnerScopeRequest(ctx.vault, {
    argument: AGENT_SCOPE_ARG_NAME,
    requested: explicit,
    identity: ctx.agentName,
  });
  // The refusal token is the boundary code: already a registered member,
  // already named in the message, so the wire carries one spelling.
  if (refused !== null) {
    throw new MCPError(INVALID_PARAMS, refused.message, { code: refused.refusal });
  }
  return explicit;
}

/** Longest accepted recall-score array; a top-k list, not a corpus. */
const RECALL_SCORES_MAX_ITEMS = 200;

export const MATCH_QUALITY_ARG_NAME = "match_quality";

/**
 * Input-schema fragments for the two arguments an adequacy verdict needs.
 * Declared once, beside {@link AGENT_SCOPE_SCHEMA}, because the two tools
 * that accept them spelled the score parser out twice already and the
 * second argument would have made it three descriptions of one contract.
 */
export const RECALL_SCORES_SCHEMA = Object.freeze({
  type: "array",
  maxItems: RECALL_SCORES_MAX_ITEMS,
  items: { type: "number" },
  description:
    "Optional top-k recall scores; requires `match_quality`. Together they add an adequacy verdict: sufficient/proceed, weak/re_recall, insufficient/abstain.",
});

/**
 * The companion argument's fragment, parameterised for the same reason
 * {@link recallAdequacyPairing} is.
 *
 * This description used to be a frozen constant naming "scores", which is
 * the gate's spelling and not the context pack's. Prose is what a
 * schema-driven client reads when it wants to know WHICH argument to send
 * alongside, and `additionalProperties: false` refuses the wrong one - so a
 * shared sentence naming one tool's key is the same defect as a pairing
 * hard-keyed on it, one layer softer. Both now say the key of the tool they
 * are attached to.
 *
 * The sentence is budgeted for the LONGEST key it will be handed: the
 * cap is `PROPERTY_DESCRIPTION_MAX` (registry-guard, which grants no
 * exemptions), so prose that fits under `scores` can still overflow under
 * `recall_scores`. Six characters of key are six characters of budget.
 */
export function matchQualitySchema(scoresKey: string): Readonly<Record<string, unknown>> {
  return Object.freeze({
    type: "number",
    minimum: 0,
    maximum: 1,
    description:
      `Absolute match quality in [0,1]: a search outcome's \`idf_weighted_coverage\`. ` +
      `Required with \`${scoresKey}\`; the adequacy level reads this, never a score.`,
  });
}

/**
 * "Both or neither", said in the schema rather than only in the refusal.
 *
 * {@link coerceRecallAdequacyInput} answers an incomplete pair with
 * INVALID_PARAMS, and until this keyword landed the pairing appeared in no
 * `required` array anywhere, so the only way a client could discover it was
 * to make the call the server refuses.
 *
 * Parameterised by the scores key, and living beside the enforcement rather
 * than inside one tool, because the two tools that enforce this spell the
 * key differently - `scores` on `brain_recall_gate`, `recall_scores` on
 * `brain_context_pack`. A pairing hard-keyed on one of those names is a
 * declaration only the first tool can use, which is how the second shipped
 * enforcing a rule it never declared. The declaration and the refusal now
 * read the same key from the same place.
 *
 * `dependentRequired` is the one keyword that states "both or neither"
 * declaratively; neither argument can sit in `required`, since both are
 * optional on their own. A client on a draft that predates the keyword
 * ignores it, which is why {@link RECALL_SCORES_SCHEMA} says it in prose too.
 */
export function recallAdequacyPairing(
  scoresKey: string,
): Readonly<Record<string, ReadonlyArray<string>>> {
  return Object.freeze({
    [scoresKey]: Object.freeze([MATCH_QUALITY_ARG_NAME]),
    [MATCH_QUALITY_ARG_NAME]: Object.freeze([scoresKey]),
  });
}

/**
 * One recall attempt as {@link assessRecallAdequacy} reads it, or
 * `undefined` when the caller asked for no verdict.
 *
 * The two arguments stand or fall together. Scores without a quality
 * cannot be graded - the level is decided by the quality alone - and
 * inventing one from the scores is exactly the substitution this release
 * removes, so an incomplete pair is refused rather than half-honoured.
 */
export function coerceRecallAdequacyInput(
  tool: string,
  args: Record<string, unknown>,
  scoresKey: string,
): { readonly matchQuality: number; readonly scores: ReadonlyArray<number> } | undefined {
  const rawScores = args[scoresKey];
  const rawQuality = args[MATCH_QUALITY_ARG_NAME];
  const hasScores = rawScores !== undefined && rawScores !== null;
  const hasQuality = rawQuality !== undefined && rawQuality !== null;
  if (!hasScores && !hasQuality) return undefined;
  if (!hasScores || !hasQuality) {
    throw new MCPError(
      INVALID_PARAMS,
      `${tool}: '${scoresKey}' and '${MATCH_QUALITY_ARG_NAME}' must be given together; ` +
        `the adequacy level is decided by ${MATCH_QUALITY_ARG_NAME} and cannot be derived from scores`,
    );
  }
  if (!Array.isArray(rawScores)) {
    throw new MCPError(INVALID_PARAMS, `${tool}: '${scoresKey}' must be an array of numbers`);
  }
  if (rawScores.length > RECALL_SCORES_MAX_ITEMS) {
    throw new MCPError(
      INVALID_PARAMS,
      `${tool}: '${scoresKey}' must not exceed ${RECALL_SCORES_MAX_ITEMS} items`,
    );
  }
  for (const item of rawScores) {
    if (typeof item !== "number") {
      throw new MCPError(INVALID_PARAMS, `${tool}: '${scoresKey}' must contain only numbers`);
    }
  }
  if (typeof rawQuality !== "number" || !Number.isFinite(rawQuality)) {
    throw new MCPError(
      INVALID_PARAMS,
      `${tool}: '${MATCH_QUALITY_ARG_NAME}' must be a finite number`,
    );
  }
  if (rawQuality < 0 || rawQuality > 1) {
    throw new MCPError(
      INVALID_PARAMS,
      `${tool}: '${MATCH_QUALITY_ARG_NAME}' must be in [0,1]; got ${rawQuality}`,
    );
  }
  return { matchQuality: rawQuality, scores: rawScores as ReadonlyArray<number> };
}

/**
 * The optional advisory probability a decision-model search surfaced as
 * `decision_model.answerable.probability` (issue #213, Part 8).
 */
export const DECISION_ANSWERABLE_ARG_NAME = "decision_answerable";

export function decisionAnswerableSchema(scoresKey: string): Readonly<Record<string, unknown>> {
  return Object.freeze({
    type: "number",
    minimum: 0,
    maximum: 1,
    description:
      "Advisory [0,1] probability from a search's `decision_model.answerable`. " +
      `Needs \`${scoresKey}\` and \`${MATCH_QUALITY_ARG_NAME}\`; never changes the level.`,
  });
}

/**
 * `decision_answerable` needs the pair it annotates, stated in the same
 * `dependentRequired` style as {@link recallAdequacyPairing}; the pair
 * itself does not need it.
 */
export function decisionAnswerablePairing(
  scoresKey: string,
): Readonly<Record<string, ReadonlyArray<string>>> {
  return Object.freeze({
    [DECISION_ANSWERABLE_ARG_NAME]: Object.freeze([scoresKey, MATCH_QUALITY_ARG_NAME]),
  });
}

/**
 * The caller's `decision_answerable`, or `undefined` when absent. Refused
 * without the recall pair (there is no verdict to annotate) and outside
 * [0,1].
 */
export function coerceDecisionAnswerable(
  tool: string,
  args: Record<string, unknown>,
  scoresKey: string,
  hasAttempt: boolean,
): number | undefined {
  const raw = args[DECISION_ANSWERABLE_ARG_NAME];
  if (raw === undefined || raw === null) return undefined;
  if (!hasAttempt) {
    throw new MCPError(
      INVALID_PARAMS,
      `${tool}: '${DECISION_ANSWERABLE_ARG_NAME}' requires '${scoresKey}' and ` +
        `'${MATCH_QUALITY_ARG_NAME}'; it annotates their adequacy verdict`,
    );
  }
  if (typeof raw !== "number" || !Number.isFinite(raw)) {
    throw new MCPError(
      INVALID_PARAMS,
      `${tool}: '${DECISION_ANSWERABLE_ARG_NAME}' must be a finite number`,
    );
  }
  if (raw < 0 || raw > 1) {
    throw new MCPError(
      INVALID_PARAMS,
      `${tool}: '${DECISION_ANSWERABLE_ARG_NAME}' must be in [0,1]; got ${raw}`,
    );
  }
  return raw;
}

export function coerceIsoDate(args: Record<string, unknown>, key: string): Date | null {
  const raw = coerceStr(args, key, false);
  if (raw === null) return null;
  const d = new Date(raw);
  if (Number.isNaN(d.getTime()))
    throw new MCPError(INVALID_PARAMS, `argument '${key}' must be a valid ISO-8601 timestamp`);
  return d;
}

export function coerceFormat(args: Record<string, unknown>, key = "format"): "markdown" | "json" {
  const raw = coerceStr(args, key, false);
  if (raw === null) return "markdown";
  if (raw !== "markdown" && raw !== "json") {
    throw new MCPError(INVALID_PARAMS, `argument '${key}' must be 'markdown' or 'json'`);
  }
  return raw;
}

/**
 * The refusal every operation-dispatching tool answers when the argument
 * that selects its operation (`operation`, `op` or `action`) names none
 * of the tool's closed set. One builder, so the `unknown_operation` code
 * is a contract of every such tool rather than of the few that set it;
 * the message stays the tool's own.
 */
export function unknownOperationError(message: string): MCPError {
  return new MCPError(INVALID_PARAMS, message, { code: TOOL_ERROR_CODE.unknownOperation });
}