Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
16.8 KB
Raw Blame
/**
 * Param normalization + validation for MCP tool dispatch (WP3).
 *
 * Extracted from src/mcp/dispatch.ts so the branch-heavy validation logic has
 * a direct unit-test surface (amendment 12). Call order is load-bearing and
 * preserved from the dispatch layer: `normalizeOptionalParams` FIRST (absent
 * idioms become truly absent), THEN `validateParams` (types + enums), THEN
 * `findUnknownParams` (strict/warn unknown-key detection on the normalized
 * object — so a null/'' optional idiom is never mistaken for an unknown key).
 *
 * dispatch.ts re-exports `normalizeOptionalParams` and `validateParams` so
 * existing imports keep working.
 */

import type { Operation } from '../core/operations.ts';
import type { BrainEngine } from '../core/engine.ts';
import type { GBrainConfig } from '../core/config.ts';
import { suggestNearest } from '../core/levenshtein.ts';
import { engineKey } from '../core/engine-key.ts';
import type { OperationError } from '../core/ops/contract.ts';
import { invalidParam } from '../core/ops/op-fix.ts';
import type { Action } from '../core/agent-output.ts';

/** One validation failure: the message (never echoes the caller's value) and the param it names. */
export interface ParamValidationFailure { message: string; param: string }

/** Validate required params exist and have the expected type. Returns the first failure, or null. */
export function findInvalidParam(op: Operation, params: Record<string, unknown>): ParamValidationFailure | null {
  for (const [key, def] of Object.entries(op.params)) {
    const fail = (message: string) => ({ message, param: key });
    if (def.required && (params[key] === undefined || params[key] === null)) {
      return fail(`Missing required parameter: ${key}`);
    }
    if (params[key] !== undefined && params[key] !== null) {
      const val = params[key];
      const expected = def.type;
      if (expected === 'string' && typeof val !== 'string') return fail(`Parameter "${key}" must be a string`);
      if (expected === 'number' && typeof val !== 'number') return fail(`Parameter "${key}" must be a number`);
      if (expected === 'integer' && !Number.isInteger(val)) return fail(`Parameter "${key}" must be a whole number`);
      if (expected === 'boolean' && typeof val !== 'boolean') return fail(`Parameter "${key}" must be a boolean`);
      if (expected === 'object' && (typeof val !== 'object' || Array.isArray(val))) return fail(`Parameter "${key}" must be an object`);
      if (expected === 'array' && !Array.isArray(val)) return fail(`Parameter "${key}" must be an array`);
      // WP3: enum membership is a TYPE error, enforced in BOTH strict modes
      // (warn and reject). The message names the declared values only — the
      // caller's raw value is never echoed (it can land in persistent logs
      // via the error_message column; declared values are safe by definition).
      if (def.enum && typeof val === 'string' && !def.enum.includes(val)) {
        return fail(`Parameter "${key}" must be one of: ${def.enum.join(', ')}`);
      }
    }
  }
  return null;
}

/** Validate required params exist and have the expected type. Returns null on success, error message on failure. */
export function validateParams(op: Operation, params: Record<string, unknown>): string | null {
  return findInvalidParam(op, params)?.message ?? null;
}

/**
 * B3: the `invalid_params` error for a schema failure — the param's type,
 * description, valid choices and one example call on the caller's surface
 * (from the op's ParamDef), never the caller's raw value in `message`.
 * Over MCP, a read op's wrong-typed or out-of-enum param also gets a `fix`:
 * the same call with the caller's other arguments and a valid value for the
 * param (H1a: a caller mistake returns a fix the agent can run).
 */
export function schemaInvalidParams(
  op: Operation,
  failure: ParamValidationFailure,
  ctx: { remote?: boolean; transport?: 'stdio' | 'http' },
  params?: Record<string, unknown>,
): OperationError {
  const fix = params && ctx.remote !== false ? retryWithValidParam(op, failure, params) : undefined;
  return invalidParam({ remote: ctx.remote ?? true, transport: ctx.transport }, op.cliHints?.name && ctx.remote === false ? op.cliHints.name : op.name,
    failure.param, failure.message, { def: op.params[failure.param], ...(fix ? { fix } : {}) });
}

/**
 * The corrected call, or undefined when no safe one exists: never for a
 * mutating op (an example value could change what gets written), a missing
 * required param (only the caller knows its value), or a param whose valid
 * value is not a closed choice, number or boolean. Arguments that are not
 * short scalars are dropped; if a required one would be dropped, no fix.
 */
function retryWithValidParam(op: Operation, failure: ParamValidationFailure, params: Record<string, unknown>): Action | undefined {
  if (op.mutating !== false) return undefined;
  const def = op.params[failure.param];
  if (!def || params[failure.param] === undefined || params[failure.param] === null) return undefined;
  const value = def.enum?.length ? (def.default !== undefined && def.enum.includes(String(def.default)) ? def.default : def.enum[0])
    : def.type === 'number' || def.type === 'integer' ? (typeof def.default === 'number' ? def.default : 10)
      : def.type === 'boolean' ? (typeof def.default === 'boolean' ? def.default : true)
        : undefined;
  if (value === undefined) return undefined;
  const args: Record<string, unknown> = {};
  for (const [key, val] of Object.entries(params)) {
    if (key === failure.param || !(key in op.params)) continue;
    const scalar = typeof val === 'number' || typeof val === 'boolean' || (typeof val === 'string' && val.length <= 200);
    if (scalar) args[key] = val;
    else if (op.params[key]?.required) return undefined;
  }
  args[failure.param] = value;
  return {
    mcp: { tool: op.name, arguments: args },
    consent: [], actor: 'agent', requires_exclusive: false,
    why: `The call failed validation before it ran, so nothing changed. This is the same call with your other arguments kept and \`${failure.param}\` set to ${JSON.stringify(value)}.`,
  };
}

/**
 * Normalize the absent-idioms real MCP clients send for OPTIONAL params
 * before validation and dispatch: `null` (any type), `''` (string-typed
 * params) and the schema-ruled-out empty values in `isAbsentValue` (GST-927)
 * become "not provided"; then a param declared `appliesWith` another one that
 * is absent is dropped too (get_page `context` without `grep`).
 *
 * Why: non-Claude models routinely fill optional params with `""` or `null`
 * instead of omitting them. `validateParams` already reads null as absent
 * for the required-param check (see above); handlers do not — some guard
 * with `typeof p.x === 'string' && p.x.length > 0` (entity / session_id in
 * `recall`), others with `p.x !== undefined` (since in `recall`), so
 * `recall {since: ""}` silently returned zero facts where the same call
 * with `since` omitted returns rows. Normalizing once at the shared
 * dispatch layer gives every handler one canonical absence instead of
 * per-handler guards.
 *
 * Deliberately narrow:
 *   - Required params are untouched — null on a required param still fails
 *     validation loudly, and `''` on a required string still reaches the
 *     handler exactly as before.
 *   - Type-mismatched junk is untouched — `limit: ""` keeps its loud
 *     "must be a number" error rather than silently succeeding.
 *   - A value inside the param's valid range is never dropped, except that an
 *     `appliesWith` param is dropped whatever its value when its partner is
 *     absent, because it has no effect then. Nothing is dropped from a param
 *     that declares none of these: the result is always a call the caller
 *     could have sent by leaving the argument out.
 *   - Undeclared keys are untouched (they were already ignored).
 * Copy-on-write: callers' param objects are never mutated.
 */
export function normalizeOptionalParams(op: Operation, params: Record<string, unknown>): Record<string, unknown> {
  let out: Record<string, unknown> | null = null;
  const drop = (key: string) => {
    if (out === null) out = { ...params };
    delete out[key];
  };
  for (const [key, def] of Object.entries(op.params)) {
    if (!def.required && isAbsentValue(op, def, params[key])) drop(key);
  }
  for (const [key, def] of Object.entries(op.params)) {
    const current = out ?? params;
    if (!def.required && def.appliesWith && current[key] !== undefined && current[def.appliesWith] === undefined) drop(key);
  }
  return out ?? params;
}

/**
 * GST-927: a value that can only mean "not provided" for this param's schema. `null` anywhere and `''` on a string
 * (GST-923), plus the empty values GPT-style callers fill in that the schema rules out: 0 below a numeric range that
 * excludes it, `[]` where the list must be non-empty, `{}` where a read op's object requires a member, and `false` on a
 * flag that acts only when true. Every other value, including any value inside the valid range, is kept.
 */
function isAbsentValue(op: Operation, def: Operation['params'][string], val: unknown): boolean {
  if (val === null) return true;
  if (val === '') return def.type === 'string';
  if (val === 0) return (def.minimum ?? 0) > 0 || (def.exclusiveMinimum ?? -1) >= 0;
  if (val === false) return def.actsWhenTrue === true;
  if (Array.isArray(val)) return val.length === 0 && (def.minItems ?? 0) >= 1;
  if (typeof val === 'object' && def.type === 'object' && op.mutating === false) {
    return Object.keys(val as object).length === 0 && Object.values(def.properties ?? {}).some(member => member.required);
  }
  return false;
}

// ---------------------------------------------------------------------------
// WP3 — strict/warn unknown-argument validation
// ---------------------------------------------------------------------------

/**
 * Top-level keys that are legitimate on ANY tool call without being declared
 * in the op's params: `_meta` is the MCP client metadata slot (several
 * clients fold it into `arguments`; dispatch reads `_meta.session_id` from
 * it), and `dry_run` is the contract-wide preview flag consumed by
 * buildOperationContext.
 */
export const UNKNOWN_PARAM_ALLOWLIST: ReadonlySet<string> = new Set(['_meta', 'dry_run']);

/**
 * #5970: names clients send for a declared param that edit distance cannot
 * reach. The suggestion names only the op's own declared params (checked at
 * use), so an alias can never point at another op's surface.
 */
const PARAM_ALIAS_HINTS: Readonly<Record<string, Readonly<Record<string, string>>>> = {
  add_timeline_entry: { content: 'detail', text: 'detail', body: 'detail' },
  remember: { facts: 'items', text: 'fact', source: 'provenance' },
};

/** GBRA-431: source-scope spellings edit distance ties or misses (`sources` is as near `source_id` as `source_ids`). */
const SOURCE_PARAM_ALIASES: Readonly<Record<string, string>> = { source: 'source_id', sourceid: 'source_id', sources: 'source_ids', sourceids: 'source_ids' };

/**
 * `_meta.warnings` entry shape (amendment 13) — documented in
 * docs/protocol/MCP_META_CHANNELS.md. `suggestion` is the nearest DECLARED
 * param name when one is within edit distance; the candidates are ONLY the
 * op's declared params, so a suggestion can never leak another op's surface.
 */
export interface UnknownParamWarning {
  code: 'unknown_param';
  param: string;
  suggestion?: string;
}

/**
 * Detect submitted top-level keys the op does not declare. Runs on the
 * NORMALIZED params object (normalizeOptionalParams only deletes DECLARED
 * optional keys, so null/'' absent-idioms are never reported here).
 *
 * Privacy note (amendment 11 / C8 class): the raw unknown key names returned
 * here reach the CALLER (warn block, `_meta.warnings`, reject `suggestion`)
 * but must NEVER be written to `mcp_request_log` — the redacted summarizer
 * counts unknown keys without naming them, and the reject-mode envelope keeps
 * the raw key out of `message` (the one field serve-http persists to
 * error_message).
 */
export function findUnknownParams(op: Operation, params: Record<string, unknown>): UnknownParamWarning[] {
  const declared = Object.keys(op.params);
  const declaredSet = new Set(declared);
  const aliases = PARAM_ALIAS_HINTS[op.name];
  const warnings: UnknownParamWarning[] = [];
  for (const key of Object.keys(params)) {
    if (declaredSet.has(key) || UNKNOWN_PARAM_ALLOWLIST.has(key)) continue;
    const alias = aliases?.[key] ?? SOURCE_PARAM_ALIASES[key.toLowerCase().replace(/[^a-z]/g, '')];
    const nearest = alias && declaredSet.has(alias) ? alias : suggestNearest(key, declared);
    warnings.push({ code: 'unknown_param', param: key, ...(nearest ? { suggestion: nearest } : {}) });
  }
  return warnings;
}

/** The families of parameter names that narrow a read's result: a source scope or a type, tag, entity, date, trust or visibility filter. */
const NARROWING_FAMILIES: readonly RegExp[] = [
  /^sources?(id|ids|name|names)?$/, /^(types?|kinds?)$/, /^tags?$/, /^(entity|entities)$/,
  /^(since|until|after|before)$/, /^(min)?trust$/, /^visibility$/,
];

function narrowingFamily(name: string): RegExp | undefined {
  const normalized = name.toLowerCase().replace(/[^a-z]/g, '');
  return NARROWING_FAMILIES.find(family => family.test(normalized));
}

/**
 * GBRA-431: the unknown keys a read must refuse whatever `mcp.strict_params` says, because ignoring them answers
 * unnarrowed: a key whose nearest declared param is a scope or filter (`source` for `source_id`, `type` for `types`),
 * or whose own name is in a scope or filter family the op declares (`source_name` on an op declaring `source_id`,
 * `kind` on one declaring `types`). A key whose family the op does not declare cannot narrow it, so it keeps the warn
 * grace period like any other unknown key (a client adding `source_id` to every call).
 */
export function narrowingUnknownParams(warnings: readonly UnknownParamWarning[], declared: readonly string[]): UnknownParamWarning[] {
  const declaredFamilies = new Set(declared.map(narrowingFamily).filter(family => family !== undefined));
  return warnings.filter(w => {
    if (w.suggestion !== undefined && narrowingFamily(w.suggestion)) return true;
    const family = narrowingFamily(w.param);
    return family !== undefined && declaredFamilies.has(family);
  });
}

/**
 * The warn-mode notice lines (one per unknown key) hosts before GST-900 appended
 * as an extra content block. Dispatch no longer sends it (the warning lives in
 * `_meta.warnings` only, so harnesses never store it in a turn); it stays the
 * reference for the old-host block `ignoredRemoteParams` still parses.
 */
export function buildUnknownParamWarnBlock(warnings: UnknownParamWarning[]): string {
  return warnings
    .map(w => w.suggestion
      ? `warning: unknown parameter "${w.param}" ignored — did you mean "${w.suggestion}"? A future release rejects unknown parameters.`
      : `warning: unknown parameter "${w.param}" ignored. A future release rejects unknown parameters.`)
    .join('\n');
}

export type StrictParamsMode = 'warn' | 'reject';

/** Strict value parse: anything but the two known modes resolves null. */
export function parseStrictParamsMode(v: unknown): StrictParamsMode | null {
  return v === 'warn' || v === 'reject' ? v : null;
}

/**
 * Dual-plane resolution for `mcp.strict_params`: DB plane (`engine.getConfig`)
 * wins, file plane (`config.mcp.strict_params`) is the fallback, absent or
 * unparseable on both = 'warn' (the grace-period default). A failed DB read
 * holds the LAST successfully resolved DB mode (per engine) before falling
 * to the file plane — a transient config outage on a reject-mode server must
 * not silently re-open the warn-mode grace period. Validation posture never
 * takes a tool call down. Resolved once per dispatch (amendment 12);
 * serve-http's tools/list also reads it per request so `gbrain config set
 * mcp.strict_params reject` flips the advertised schema without a restart
 * (stdio + the legacy bearer transport resolve once at startup — restart to
 * flip there, deliberate).
 */
let lastKnownDbStrictMode = new WeakMap<object, StrictParamsMode | null>();

/** Test seam: clear the last-known-good DB mode between cases. */
export function resetStrictParamsModeCache(): void {
  lastKnownDbStrictMode = new WeakMap();
}

export async function resolveStrictParamsMode(
  engine: BrainEngine,
  config: GBrainConfig | null | undefined,
): Promise<StrictParamsMode> {
  try {
    const dbMode = parseStrictParamsMode(await engine.getConfig('mcp.strict_params'));
    lastKnownDbStrictMode.set(engineKey(engine), dbMode);
    if (dbMode) return dbMode;
  } catch {
    // Engine without a config table / transient error: last-known-good DB
    // mode wins; with no prior successful read, the file plane decides.
    const lastKnown = lastKnownDbStrictMode.get(engineKey(engine));
    if (lastKnown) return lastKnown;
  }
  return parseStrictParamsMode(config?.mcp?.strict_params) ?? 'warn';
}