Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

Refuse a scope or filter key when the read declares a parameter of the same family

garrytan4c7a968b968b
diff --git a/src/mcp/dispatch.ts b/src/mcp/dispatch.ts
index 1fec859971..7538d900a4 100644
--- a/src/mcp/dispatch.ts
+++ b/src/mcp/dispatch.ts
@@ -1181,7 +1181,7 @@ async function dispatchResolvedCall(
if (unknownParamWarnings.length > 0) {
const strictMode = op.mutating === true ? 'reject' : await resolveStrictParamsMode(engine, opts.config ?? loadConfig());
// GBRA-431: a misspelled scope or filter on a read would answer unnarrowed, so it rejects in every mode.
- const narrowing = strictMode === 'reject' ? [] : narrowingUnknownParams(unknownParamWarnings);
+ const narrowing = strictMode === 'reject' ? [] : narrowingUnknownParams(unknownParamWarnings, Object.keys(op.params));
if (strictMode === 'reject' || narrowing.length > 0) {
logVerb(false);
// Privacy (amendment 11): the raw unknown key rides `suggestion` ONLY.
diff --git a/src/mcp/validate-params.ts b/src/mcp/validate-params.ts
index 080b604dd6..98dab13d19 100644
--- a/src/mcp/validate-params.ts
+++ b/src/mcp/validate-params.ts
@@ -236,21 +236,31 @@ export function findUnknownParams(op: Operation, params: Record<string, unknown>
return warnings;
}
-/** A parameter name that narrows a read's result: a source scope or a type, tag, entity, date, trust or visibility filter. */
-const NARROWING_PARAM_RE = /^(sources?(id|ids|name|names)?|types?|kinds?|tags?|entity|entities|since|until|after|before|mintrust|visibility)$/;
+/** 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 isNarrowingName(name: string): boolean {
- return NARROWING_PARAM_RE.test(name.toLowerCase().replace(/[^a-z]/g, ''));
+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 of this op (`source` for `source_id`, `sources`
- * for `source_ids`, `type` for `types`). An op that declares no such param cannot narrow, so a scope key sent to it
- * (a client adding `source_id` to every call) keeps the warn grace period like any other unknown key.
+ * 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[]): UnknownParamWarning[] {
- return warnings.filter(w => w.suggestion !== undefined && isNarrowingName(w.suggestion));
+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);
+ });
}
/**
diff --git a/test/validate-params.test.ts b/test/validate-params.test.ts
index 9c47c6eb7c..6b0f66d7ba 100644
--- a/test/validate-params.test.ts
+++ b/test/validate-params.test.ts
@@ -29,7 +29,7 @@ import {
UNKNOWN_PARAM_ALLOWLIST,
narrowingUnknownParams,
} from '../src/mcp/validate-params.ts';
-import { operations, operationsByName } from '../src/core/operations.ts';
+import { operations, operationsByName, type Operation } from '../src/core/operations.ts';
import type { BrainEngine } from '../src/core/engine.ts';
/**
@@ -533,12 +533,28 @@ describe('a read rejects an unknown scope or filter parameter even in warn mode
{ code: 'unknown_param', param: 'source', suggestion: 'source_id' }, { code: 'unknown_param', param: 'Source-IDs', suggestion: 'source_ids' },
{ code: 'unknown_param', param: 'srcid', suggestion: 'source_id' }, { code: 'unknown_param', param: 'tag', suggestion: 'types' },
{ code: 'unknown_param', param: 'limt', suggestion: 'limit' }, { code: 'unknown_param', param: 'partal', suggestion: 'partial' },
- ]).map(w => w.param)).toEqual(['source', 'Source-IDs', 'srcid', 'tag']);
+ ], ['source_id', 'source_ids', 'types', 'limit', 'partial']).map(w => w.param)).toEqual(['source', 'Source-IDs', 'srcid', 'tag']);
});
test('a scope key sent to an op that declares no scope param keeps the warn grace period', () => {
expect(narrowingUnknownParams([
{ code: 'unknown_param', param: 'source_id' }, { code: 'unknown_param', param: 'source_id', suggestion: 'request_id' },
- ])).toEqual([]);
+ ], ['request_id', 'applied'])).toEqual([]);
+ });
+
+ const refusedOn = (declared: string[], key: string) => {
+ const op = { name: 'family_probe', params: Object.fromEntries(declared.map(name => [name, { type: 'string' }])) } as unknown as Operation;
+ return narrowingUnknownParams(findUnknownParams(op, { [key]: 'x' }), declared).map(w => w.param);
+ };
+
+ test('a key in a scope or filter family the op declares is refused even with no near suggestion', () => {
+ expect(refusedOn(['source_ids', 'limit'], 'source')).toEqual(['source']);
+ expect(refusedOn(['source_id', 'limit'], 'source_name')).toEqual(['source_name']);
+ expect(refusedOn(['types', 'limit'], 'kind')).toEqual(['kind']);
+ });
+
+ test('a key whose family the op does not declare keeps the warn grace period', () => {
+ expect(refusedOn(['types', 'limit'], 'source_id')).toEqual([]);
+ expect(refusedOn(['source_id', 'limit'], 'since')).toEqual([]);
});
});