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
/**
* Unknown-argument gate (evidence-at-the-boundary, task C3).
*
* All 108 advertised tools declare `additionalProperties: false` and the
* server enforced it on none. `tools/call` checked that the name was a
* string and the arguments were a non-array object, then handed the raw
* record to the handler, which read the keys it knew about and ignored
* the rest. So `{"quiery": "x"}` on `brain_search` came back as a normal
* success envelope computed entirely from defaults, and the single place
* the unknown key was observed was a telemetry field (`argKeys`) that the
* caller never sees. A silently ignored argument is the worst kind of
* fallback: it produces an answer to a question nobody asked.
*
* This module is the request-path half of the pair. Its test-time twin,
* `./registry-guard.ts`, is what makes the read below safe: the closure
* flag is READ from each schema rather than assumed, and the completeness
* audit is what guarantees the read never lands on an open one.
*
* The suggestion is pure string distance over the schema's own property
* names (`core/text/nearest-name.ts`) - never a curated synonym table,
* which would encode one language's habits and go stale on the first
* rename.
*
* RECORDED LIMIT: top-level closure only. Fifteen nested object nodes in
* the live table declare `additionalProperties: false` of their own -
* `usage` on `brain_generation_reports`, the `operations` entries, the
* `entities` and `relations` entries - and this gate does not enforce
* them. That is a stated boundary, not a fallback pretending to work: a
* nested unknown key still reaches the handler unremarked, exactly as it
* did before. Widening the gate means walking the argument tree against
* the schema tree, which is a validator, and this is not one.
*/
import { nearestName } from "../core/text/nearest-name.ts";
import { INVALID_PARAMS, MCPError } from "./protocol.ts";
import type { ToolDefinition } from "./tool-contract.ts";
import { TOOL_ERROR_CODE } from "./tool-error-codes.ts";
/** One argument the caller sent that the tool never declared. */
export interface UnknownArgument {
readonly name: string;
/** The declared name it is closest to, when one is close enough. */
readonly suggestion?: string;
}
/** The structured payload attached to the refusal, for machine callers. */
export interface UnknownArgumentData {
readonly tool: string;
readonly unknown_arguments: ReadonlyArray<UnknownArgument>;
/** Every argument the tool does declare, sorted, so the fix is in hand. */
readonly declared_arguments: ReadonlyArray<string>;
/** The boundary error code, last, after the members it summarises. */
readonly code: typeof TOOL_ERROR_CODE.unknownArgument;
}
/** What the caller is told when no declared name is near enough to name. */
const NO_CLOSE_MATCH = "no close match";
/**
* The names one schema declares, or undefined when the schema does not
* close itself over them.
*
* Own keys only: `name in properties` walks the prototype chain, so an
* argument called `constructor` or `toString` would be treated as
* declared by a schema that declares nothing of the sort.
*/
function declaredArgumentNames(schema: unknown): ReadonlyArray<string> | undefined {
if (schema === null || typeof schema !== "object" || Array.isArray(schema)) return undefined;
const node = schema as Record<string, unknown>;
// The closure is read, never assumed. An open schema accepts extra
// arguments by its own declaration, and refusing them would break a
// contract this server publishes.
if (node["additionalProperties"] !== false) return undefined;
const properties = node["properties"];
if (properties === null || typeof properties !== "object" || Array.isArray(properties)) {
return undefined;
}
return Object.keys(properties);
}
/**
* Every argument the caller sent that `schema` does not declare, in the
* caller's own key order, each with a suggestion where the distance
* supports one. Empty for a schema that is not closed at the top level.
*/
export function findUnknownArguments(
schema: unknown,
args: Record<string, unknown>,
): ReadonlyArray<UnknownArgument> {
const declared = declaredArgumentNames(schema);
if (declared === undefined) return Object.freeze([]);
const known = new Set(declared);
const unknown: UnknownArgument[] = [];
for (const name of Object.keys(args)) {
if (known.has(name)) continue;
const suggestion = nearestName(name, declared);
unknown.push(Object.freeze(suggestion === undefined ? { name } : { name, suggestion }));
}
return Object.freeze(unknown);
}
/** `'quiery' (did you mean 'query'?)` or the honest absence of one. */
function renderUnknown(entry: UnknownArgument): string {
return entry.suggestion === undefined
? `'${entry.name}' (${NO_CLOSE_MATCH})`
: `'${entry.name}' (did you mean '${entry.suggestion}'?)`;
}
/**
* Refuse a call carrying arguments the tool never declared.
*
* Every undeclared argument is named in one message - reporting only the
* first would send the caller round the loop once per typo - and the same
* list rides along as structured `data`, which `MCPError` carries and the
* JSON-RPC error response already forwards.
*/
export function assertKnownArguments(tool: ToolDefinition, args: Record<string, unknown>): void {
const unknown = findUnknownArguments(tool.inputSchema, args);
if (unknown.length === 0) return;
const declared = declaredArgumentNames(tool.inputSchema) ?? [];
const noun = unknown.length === 1 ? "unknown argument" : "unknown arguments";
const message =
`${tool.name}: ${noun} ${unknown.map(renderUnknown).join(", ")}. ` +
`This tool's inputSchema declares the ${declared.length} argument names it accepts.`;
const data: UnknownArgumentData = Object.freeze({
tool: tool.name,
unknown_arguments: unknown,
declared_arguments: Object.freeze(declared.toSorted()),
code: TOOL_ERROR_CODE.unknownArgument,
});
throw new MCPError(INVALID_PARAMS, message, data);
}