Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
fix(tools): read schema-ruled-out empty optional args (0, [], {}, false, context without grep) as absent (GST-927)
garrytandb5331b845b5
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 15454695dc..4e9bc7b180 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -10,6 +10,20 @@ credits are retained; no result has been reassigned to another provider. Originaidentifiers and attribution are available in the pre-removal Git revision`6040075c6cb95be5881cc2e1b76ef7d71f4e5d29` (retained on 2026-09-23).+## [Unreleased]++**GPT models that fill every optional tool argument with an empty value can now read pages and walk the graph.** GPT-6.1 Sol fills optional arguments with `0`, `[]`, `{}` or `false` as well as `""` and `null`. The `""` and `null` case was fixed in v0.60.549.0, but read operations still refused the others. `get_page` refused `around_chunk_id: 0`, `lines: {}` and a `context` sent without `grep`. `traverse_graph` refused `hops: []` sent beside `depth`, `link_type` and `direction`. Twenty-seven other optional arguments refused the same way (`limit: 0` on nine read operations, `types: []`, `only: []`, `schema_version: 0`, `get_versions` `diff: false` and more). gbrain now reads these as not provided, but only where the argument's own schema rules the value out: `0` when the valid range starts above zero, `[]` when the list must not be empty, `{}` when the object needs a field, `false` on a flag that only acts when true, and `context` when there is no `grep`, since it has no effect without it. Any value inside the valid range is kept, and so is any value on an argument that declares no such rule. So the normalized call is always one the caller could have sent by leaving the argument out, and it never reads more than that call would. This runs on every path that hands model arguments to an operation: MCP over HTTP and stdio, `gbrain call`, the subagent tool registry and both SkillOpt registries.++`get_page` with `known_as_of` still refuses arguments that select a window or a view of the page, because those cut the current page's text and chunk ids and a recorded version has neither. The refusal now names each argument to drop and carries a `fix`: the same call with only the arguments a recorded-time read takes. Replaying GBEV-3's 651 recorded GPT-6.1 Sol calls, 30 of 38 `traverse_graph` calls now succeed. The other 8 send a non-empty hop chain beside `depth`. The 436 `get_page` calls that sent `context` without `grep` now pass that step and stop at the next rule, because they also send both `lines` and `bytes` (and often `around_chunk_id`), real window selectors that change the answer.++### Itemized changes++- `src/core/ops/contract.ts` (`ParamDef`): new schema fields `minimum`, `exclusiveMinimum`, `minItems`, `actsWhenTrue` and `appliesWith`. Only the normalizer reads them, and they are left out of the advertised tools/list schema.+- `src/mcp/validate-params.ts` (`normalizeOptionalParams`): drops the values those fields rule out, plus `{}` on an object whose properties require a member. It then drops any argument whose `appliesWith` argument is absent. Required arguments are never touched.+- Read operations declare the fields where GBRA-278's sweep showed the value refuses: `minimum: 1` on the swept limits, ids, `max_bytes`, `return_window`, `schema_version` and `min_n`; `exclusiveMinimum: 0` on `search_exact` `max_seconds`; `minItems: 1` on `types`, `only` and `hops`; `actsWhenTrue` on `get_versions` `diff`; `appliesWith: 'grep'` on `get_page` `context`.+- `src/core/ops/known-as-of.ts`: the `known_as_of does not combine with …` refusal names the arguments to drop for the caller's transport and carries a read `fix`.+- `test/tool-args-empty-optional-sol.test.ts`: a table test over the sweep's 29 cases on every entry point (each one refuses on master), checks that in-range and non-empty values still refuse, and replays the Sol shapes for `get_page` and `traverse_graph`.+## [0.60.549.0] - 2026-11-02**GPT models that fill every optional tool argument with `""` or `null` can read pages again in SkillOpt rollouts and `gbrain call`.** GPT-6.1 Sol sends `known_as_of: ""`, `cursor: ""`, `section: ""` and `grep: ""` instead of leaving those arguments out. MCP dispatch and the subagent tool registry already treated `""` on an optional string argument, and `null` on any optional argument, as not provided. The SkillOpt rollout and write-capture registries and `gbrain call` passed the arguments to the handler unchanged. There `known_as_of: ""` sent `get_page` into its recorded-time branch, which refused with "known_as_of must be an ISO 8601 instant", so a SkillOpt probe on GPT-6.1 Sol saw every `get_page` call fail and the model answered from search snippets. The same empty arguments broke about 30 other read operations on those paths (`search`, `get_links`, `traverse_graph`, `recall`, `whois` and more). All three paths now run the same step as MCP dispatch. Empty optional arguments are dropped, then the arguments are checked against the operation's schema. A missing required argument or a non-empty invalid value still refuses with `invalid_params`. The SkillOpt registries now also refuse a wrong-typed or out-of-enum argument before the handler runs, with the same `invalid_params` error MCP returns. Over remote MCP, `memory_recall` with `acting_user: ""` or `acting_user: null` refused with `actor_not_attested`, because the attested-actor check read the arguments before they were normalized. It now reads the normalized arguments, so an empty `acting_user` means the same as leaving it out. A non-empty `acting_user` is still accepted only on an attested call and only when it matches the `x-qm-actor` header.diff --git a/docs/architecture/key-files/mcp.md b/docs/architecture/key-files/mcp.mdindex 91f8201f8b..b274c0000d 100644--- a/docs/architecture/key-files/mcp.md+++ b/docs/architecture/key-files/mcp.md@@ -29,4 +29,4 @@ Current behavior and load-bearing invariants; history belongs in Git and CHANGEL- `src/mcp/tool-defs.ts` — `buildToolDefs(ops, opts?)` helper; the stdio MCP server, the OAuth HTTP `tools/list`, and the subagent tool registry all consume it, byte-for-byte equivalence pinned by `test/mcp-tool-defs.test.ts`. `opts.strictParams: true` (when `mcp.strict_params` resolves `'reject'`) additionally declares the `_meta`/`dry_run` passthrough keys in `properties` and closes each schema with `additionalProperties: false` (schema-validating clients must not strip `_meta.session_id`); both emission states pinned. Exports the recursive `paramDefToSchema(p: ParamDef)` — single source of truth for ParamDef→JSON Schema mapping shared by `buildToolDefs` and `src/core/minions/tools/brain-allowlist.ts` (subagent registry). Recursive on `items` so nested array-of-arrays preserves inner shape on the wire, and on object `properties` (closed with `additionalProperties: false`, member `required` keys). Key ordering (type, description, enum, default, items, properties) is intentional so `JSON.stringify` output stays byte-stable. `toolAnnotations(op)` is the one annotation rule: curated op annotations win; else `readOnlyHint: true` for a read-scope op tagged `mutating: false`, `readOnlyHint: false` for one tagged `mutating: true`, nothing for untagged ops. `test/mcp-tool-defs.test.ts` has a `findArrayWithoutItems` walker that fails on any `type: 'array'` lacking `items.type`. Annotations: curated `op.annotations` win; else `readOnlyHint: true` iff `mutating === false`, `readOnlyHint: false` (+ `idempotentHint: true` when `idempotent`) iff `mutating === true`; every op declares both tags (`test/ops-mutation-tags.test.ts`).-- `src/mcp/validate-params.ts` — param normalization + validation for dispatch (direct unit surface). `validateParams` (required/type/enum — enum membership is a TYPE error in BOTH strict modes; the caller's raw value is never echoed into the message), `normalizeOptionalParams` (null/`''` optional-param idioms become truly absent, copy-on-write), `findUnknownParams` (unknown top-level keys on the NORMALIZED object; `UNKNOWN_PARAM_ALLOWLIST` = `_meta` + `dry_run`; per-op did-you-mean from the op's OWN declared params only, plus the explicit `PARAM_ALIAS_HINTS` aliases edit distance cannot reach, e.g. `add_timeline_entry` `content` → `detail`; dispatch rejects unknown keys on every `mutating` op regardless of `mcp.strict_params`, so a typo never commits a write), `buildUnknownParamWarnBlock` (the model-visible warn notice), `resolveStrictParamsMode(engine, config)` (dual-plane `mcp.strict_params`, DB > file > `'warn'`; a failed DB read applies the LAST successfully read DB mode, held per process — fail-closed, so a transient config outage on a reject-mode server cannot re-open the warn grace period; test seam `resetStrictParamsModeCache()`). Privacy: raw unknown key names reach the CALLER only, never `mcp_request_log`. Pinned by test/validate-params.test.ts. Every path that hands arguments to an op handler runs normalize → validate first: `dispatchToolCall`, `handleToolCall` (`gbrain call`) and the SkillOpt rollout and write-capture registries, so a model that sends `""` or `null` for every optional argument reads the same as one that omits them (`test/tool-args-empty-optional-sol.test.ts`). On a remote call the audience and attested-actor checks in `dispatchToolCall` read the normalized arguments, so `acting_user: ""` or `null` counts as omitted.+- `src/mcp/validate-params.ts` — param normalization + validation for dispatch (direct unit surface). `validateParams` (required/type/enum — enum membership is a TYPE error in BOTH strict modes; the caller's raw value is never echoed into the message), `normalizeOptionalParams` (null/`''` optional-param idioms become truly absent, and so do the values a param's schema rules out: `0` below `minimum`/`exclusiveMinimum`, `[]` under `minItems`, `{}` on an object with a required member, `false` on an `actsWhenTrue` flag, then any param whose `appliesWith` param is absent (GST-927); required params untouched, copy-on-write), `findUnknownParams` (unknown top-level keys on the NORMALIZED object; `UNKNOWN_PARAM_ALLOWLIST` = `_meta` + `dry_run`; per-op did-you-mean from the op's OWN declared params only, plus the explicit `PARAM_ALIAS_HINTS` aliases edit distance cannot reach, e.g. `add_timeline_entry` `content` → `detail`; dispatch rejects unknown keys on every `mutating` op regardless of `mcp.strict_params`, so a typo never commits a write), `buildUnknownParamWarnBlock` (the model-visible warn notice), `resolveStrictParamsMode(engine, config)` (dual-plane `mcp.strict_params`, DB > file > `'warn'`; a failed DB read applies the LAST successfully read DB mode, held per process — fail-closed, so a transient config outage on a reject-mode server cannot re-open the warn grace period; test seam `resetStrictParamsModeCache()`). Privacy: raw unknown key names reach the CALLER only, never `mcp_request_log`. Pinned by test/validate-params.test.ts. Every path that hands arguments to an op handler runs normalize → validate first: `dispatchToolCall`, `handleToolCall` (`gbrain call`) and the SkillOpt rollout and write-capture registries, so a model that sends `""` or `null` for every optional argument reads the same as one that omits them (`test/tool-args-empty-optional-sol.test.ts`). On a remote call the audience and attested-actor checks in `dispatchToolCall` read the normalized arguments, so `acting_user: ""` or `null` counts as omitted.diff --git a/src/core/behavior-change-notice.ts b/src/core/behavior-change-notice.tsindex d82b345054..79a0f10f98 100644--- a/src/core/behavior-change-notice.ts+++ b/src/core/behavior-change-notice.ts@@ -1408,6 +1408,8 @@ export const BEHAVIOR_CHANGES: ReadonlyArray<{ since: string; text: ChangeText;{ since: '0.60.541.0', id: 'remote_quotes_followups_8384b', text: 'Agents connected over MCP now get a quoted page\'s title quoted on search, query, assemble_evidence and recall rows, its tags quoted on get_page, fetch and get_tags (add_tag and remove_tag take a copied tag without the fence), and a chronicle row\'s kind quoted by its event page\'s tier; a context_pack card below "your notes" carries its title under the card\'s trust label. A remote put_page of a whole-markdown read saved with CRLF line endings stores the page, not its fence, and a fenced value pasted into frontmatter leaves the other keys as sent. Facts from a quarantined page, or awaiting re-derivation after a purge, no longer appear in entity-fact reads, local ones included: recall, search and query entity facts, find_trajectory, the entity card\'s fact count and consolidate; standing-question evidence also skips such facts, takes and timeline entries. Other local reads are unchanged.' },// #8424 (GBRA-277) hook launcher. since stamped at the merge slot.{ since: '0.60.547.0', id: 'hook_launcher_8424', text: 'The hooks `gbrain setup claude-code|codex` writes, and the per-turn rule hook from `--instructions-only`, `gbrain connect --install` and `gbrain bootstrap harness`, now start gbrain through `<gbrain config dir>/hook-launcher/gbrain-hook`, so a session opened in a cloned repository never runs that repository\'s bunfig.toml preload or loads its .env. `gbrain post-upgrade` moves existing hooks onto it, except `gbrain setup codex`\'s, which the next `gbrain setup codex` rewrites, and doctor `harness_wiring` warns with `hook_session_cwd` on any that still start gbrain in the session directory.' },+ // GST-927 (GBRA-280) schema-ruled-out empty arguments; release:restamp stamps since at the merge slot.+ { since: 'TBD', id: 'empty_nonstring_args_gst927', text: 'Read tools now treat an optional argument as not provided when its own schema rules the value out: 0 where the range starts above zero (limit: 0, around_chunk_id: 0, schema_version: 0 and others), [] where the list must not be empty (types, only, traverse_graph hops), {} where the object needs a field (get_page lines and bytes), false on get_versions diff, and get_page context without grep. These calls used to refuse with invalid_params; now they answer as if the argument were left out. get_page known_as_of beside window or view arguments still refuses, and the refusal names the arguments to drop.' },];/** The newest disclosed change's release: the notice id moves only when a release adds rows. */diff --git a/src/core/operation-manifest.generated.ts b/src/core/operation-manifest.generated.tsindex 0a0c8dfa33..47a820e894 100644--- a/src/core/operation-manifest.generated.ts+++ b/src/core/operation-manifest.generated.ts@@ -313,6 +313,7 @@ export const OPERATION_MANIFEST: OperationMeta[] = [},"around_chunk_id": {"type": "number",+ "minimum": 1,"description": "Window around a search hit chunk_id.","fullSurfaceOnly": true},@@ -328,6 +329,7 @@ export const OPERATION_MANIFEST: OperationMeta[] = [},"max_bytes": {"type": "number",+ "minimum": 1,"description": "Window bytes (40000).","fullSurfaceOnly": true},@@ -357,6 +359,7 @@ export const OPERATION_MANIFEST: OperationMeta[] = [},"context": {"type": "number",+ "appliesWith": "grep","description": "With grep: paragraphs of context either side (default 1, max 5).","fullSurfaceOnly": true},@@ -1260,6 +1263,7 @@ export const OPERATION_MANIFEST: OperationMeta[] = [},"limit": {"type": "number",+ "minimum": 1,"default": 25,"description": "1-100 slugs (default 25)."},@@ -1375,6 +1379,7 @@ export const OPERATION_MANIFEST: OperationMeta[] = [},"return_window": {"type": "number",+ "minimum": 1,"description": "Window radius 1-3.","fullSurfaceOnly": true},@@ -1496,6 +1501,7 @@ export const OPERATION_MANIFEST: OperationMeta[] = [},"return_window": {"type": "number",+ "minimum": 1,"description": "Window radius 1-3.","fullSurfaceOnly": true},@@ -1677,6 +1683,7 @@ export const OPERATION_MANIFEST: OperationMeta[] = [},"return_window": {"type": "number",+ "minimum": 1,"description": "Window radius 1-3.","fullSurfaceOnly": true},@@ -1784,6 +1791,7 @@ export const OPERATION_MANIFEST: OperationMeta[] = [},"types": {"type": "array",+ "minItems": 1,"items": {"type": "string"},@@ -1795,6 +1803,7 @@ export const OPERATION_MANIFEST: OperationMeta[] = [},"limit": {"type": "number",+ "minimum": 1,"description": "Matching pages to return (default 100, max 1000)."},"after": {@@ -1803,6 +1812,7 @@ export const OPERATION_MANIFEST: OperationMeta[] = [},"max_seconds": {"type": "number",+ "exclusiveMinimum": 0,"description": "Scan budget in seconds (default 30, max 120)."},"min_trust": {@@ -2156,6 +2166,7 @@ export const OPERATION_MANIFEST: OperationMeta[] = [},"limit": {"type": "number",+ "minimum": 1,"description": "Rows per call (default 500, max 5000)."},"cursor": {@@ -2226,6 +2237,7 @@ export const OPERATION_MANIFEST: OperationMeta[] = [},"limit": {"type": "number",+ "minimum": 1,"description": "≤5000"},"cursor": {@@ -2291,6 +2303,7 @@ export const OPERATION_MANIFEST: OperationMeta[] = [},"hops": {"type": "array",+ "minItems": 1,"description": "≤3 typed hops, e.g. [{\"link_type\":\"founded\",\"toward\":\"subject\"}]; toward: object|subject.","items": {"type": "object",@@ -2338,6 +2351,7 @@ export const OPERATION_MANIFEST: OperationMeta[] = [},"limit": {"type": "number",+ "minimum": 1,"description": "Rows per page (default 50, max 100)."},"offset": {@@ -2508,6 +2522,7 @@ export const OPERATION_MANIFEST: OperationMeta[] = [},"only": {"type": "array",+ "minItems": 1,"items": {"type": "string"},@@ -2544,6 +2559,7 @@ export const OPERATION_MANIFEST: OperationMeta[] = [},"limit": {"type": "number",+ "minimum": 1,"description": "Return only the newest N versions (a positive integer). Default 20; MCP callers are capped at 100."},"include_body": {@@ -2557,6 +2573,7 @@ export const OPERATION_MANIFEST: OperationMeta[] = [},"diff": {"type": "boolean",+ "actsWhenTrue": true,"fullSurfaceOnly": true,"description": "With known_as_of: each version also carries a unified diff from the version before it."},@@ -2669,14 +2686,17 @@ export const OPERATION_MANIFEST: OperationMeta[] = [},"fact": {"type": "number",+ "minimum": 1,"description": "Attribute this fact id (a fact about or fenced on the page) instead of the page."},"take": {"type": "number",+ "minimum": 1,"description": "Attribute the take at this row number of the page's takes table."},"timeline": {"type": "number",+ "minimum": 1,"description": "Attribute this timeline entry id of the page."},"versions": {@@ -2721,6 +2741,7 @@ export const OPERATION_MANIFEST: OperationMeta[] = ["params": {"schema_version": {"type": "number",+ "minimum": 1,"description": "2 for the source-qualified catalog.","fullSurfaceOnly": true},@@ -2768,6 +2789,7 @@ export const OPERATION_MANIFEST: OperationMeta[] = ["params": {"schema_version": {"type": "number",+ "minimum": 1,"description": "2 for an exact canonical revision.","fullSurfaceOnly": true},@@ -3503,6 +3525,7 @@ export const OPERATION_MANIFEST: OperationMeta[] = [},"limit": {"type": "number",+ "minimum": 1,"description": "How many chunk_index positions to return (a positive integer). Default 50; MCP callers are capped at 500."}},@@ -3524,6 +3547,7 @@ export const OPERATION_MANIFEST: OperationMeta[] = [},"types": {"type": "array",+ "minItems": 1,"items": {"type": "string"},@@ -4041,6 +4065,7 @@ export const OPERATION_MANIFEST: OperationMeta[] = [},"limit": {"type": "number",+ "minimum": 1,"description": "Rows per page (default 100, max 1000); total_orphans counts every orphan, complete says whether this page holds the rest, and next_cursor (or next_offset) names the next page."},"offset": {@@ -4082,6 +4107,7 @@ export const OPERATION_MANIFEST: OperationMeta[] = [},"types": {"type": "array",+ "minItems": 1,"items": {"type": "string"},@@ -4101,6 +4127,7 @@ export const OPERATION_MANIFEST: OperationMeta[] = [},"limit": {"type": "number",+ "minimum": 1,"description": "Rows to return (default 20, max 100)."}},@@ -4311,6 +4338,7 @@ export const OPERATION_MANIFEST: OperationMeta[] = [},"min_n": {"type": "number",+ "minimum": 1,"description": "Trusted local CLI only: groups with fewer resolved predictions are flagged low_n (default 10)"}},@@ -6875,6 +6903,7 @@ export const OPERATION_MANIFEST: OperationMeta[] = [},"id": {"type": "number",+ "minimum": 1,"description": "Fetch the single loop with this id (ids come from earlier open_loops results). Matches any status unless `status` is passed; the source scope still applies, and the grouped view omits `text`."},"loop_type": {diff --git a/src/core/ops/admin.ts b/src/core/ops/admin.tsindex b665a2e6d5..31bf15b9a2 100644--- a/src/core/ops/admin.ts+++ b/src/core/ops/admin.ts@@ -177,7 +177,7 @@ const run_doctor: Operation = {description: 'Run brain health checks and return a structured DoctorReport (thin-client doctor surface). tier "ops": only the operational sections under a 4 s deadline; only: just the named checks.',params: {tier: { type: 'string', enum: ['ops'], description: 'ops: capacity, write failures, embedding state, sync movement, compaction, serve build and schema pack, under one 4 s deadline. Omit for the focused remote report.' },- only: { type: 'array', items: { type: 'string' }, description: 'Run just these checks (doctor check names, for example persistence_capacity).' },+ only: { type: 'array', minItems: 1, items: { type: 'string' }, description: 'Run just these checks (doctor check names, for example persistence_capacity).' },},handler: async (ctx, p) => {if (p.tier !== undefined || p.only !== undefined) return (await import('../../commands/doctor/remote-tier.ts')).runRemoteDoctorTier(ctx, p);@@ -206,7 +206,7 @@ const get_versions: Operation = {description: `Page version history, newest snapshot first: metadata only (id, snapshot_at, title, type, tags, frontmatter) for the newest ${GET_VERSIONS_DEFAULT_LIMIT} versions by default. Pass include_body: true for each version's compiled_truth and timeline, and a larger limit (at most ${GET_VERSIONS_REMOTE_MAX_LIMIT} over MCP) for older versions. Trusted local and admin callers also get written_by and archived_by (who wrote each snapshot and whose write archived it). revert_version takes the id field.`,params: {slug: { type: 'string', required: true, description: 'Slug of the page whose version history to list.' },- limit: { type: 'number', description: `Return only the newest N versions (a positive integer). Default ${GET_VERSIONS_DEFAULT_LIMIT}; MCP callers are capped at ${GET_VERSIONS_REMOTE_MAX_LIMIT}.` },+ limit: { type: 'number', minimum: 1, description: `Return only the newest N versions (a positive integer). Default ${GET_VERSIONS_DEFAULT_LIMIT}; MCP callers are capped at ${GET_VERSIONS_REMOTE_MAX_LIMIT}.` },include_body: { type: 'boolean', description: 'true adds compiled_truth and timeline to every version. Default false (metadata only).' },known_as_of: { ...KNOWN_AS_OF_PARAM, description: 'Recorded time: the validity intervals this brain had recorded by this ISO 8601 instant, from the belief ledger. Not as_of, which is valid time (a date).' },diff: VERSIONS_DIFF_PARAM,diff --git a/src/core/ops/attribution.ts b/src/core/ops/attribution.tsindex 70dc363268..a00f9346fd 100644--- a/src/core/ops/attribution.ts+++ b/src/core/ops/attribution.ts@@ -140,9 +140,9 @@ const get_write_attribution: Operation = {+ 'Remote callers stay inside their source grant and see only world facts.',params: {slug: { type: 'string', required: true, description: 'Slug of the page to attribute (or the page that holds the fact, take or timeline entry).' },- fact: { type: 'number', description: 'Attribute this fact id (a fact about or fenced on the page) instead of the page.' },- take: { type: 'number', description: 'Attribute the take at this row number of the page\'s takes table.' },- timeline: { type: 'number', description: 'Attribute this timeline entry id of the page.' },+ fact: { type: 'number', minimum: 1, description: 'Attribute this fact id (a fact about or fenced on the page) instead of the page.' },+ take: { type: 'number', minimum: 1, description: 'Attribute the take at this row number of the page\'s takes table.' },+ timeline: { type: 'number', minimum: 1, description: 'Attribute this timeline entry id of the page.' },versions: { type: 'boolean', description: 'Also list every version snapshot with who wrote and who archived it.' },},scope: 'admin',diff --git a/src/core/ops/chunks.ts b/src/core/ops/chunks.tsindex 6490f4bb97..fadaf36b74 100644--- a/src/core/ops/chunks.ts+++ b/src/core/ops/chunks.ts@@ -53,7 +53,7 @@ const get_chunks: Operation = {slug: { type: 'string', required: true, description: 'Slug of the page whose content chunks to return.' },min_trust: MIN_TRUST_PARAM,from_index: { type: 'number', description: 'Return chunks from this chunk_index on (a non-negative integer). Default 0.' },- limit: { type: 'number', description: `How many chunk_index positions to return (a positive integer). Default ${GET_CHUNKS_DEFAULT_LIMIT}; MCP callers are capped at ${GET_CHUNKS_REMOTE_MAX_LIMIT}.` },+ limit: { type: 'number', minimum: 1, description: `How many chunk_index positions to return (a positive integer). Default ${GET_CHUNKS_DEFAULT_LIMIT}; MCP callers are capped at ${GET_CHUNKS_REMOTE_MAX_LIMIT}.` },},handler: async (ctx, p) => {const fromIndex = p.from_index === undefined || p.from_index === null ? 0 : p.from_index;diff --git a/src/core/ops/contract.ts b/src/core/ops/contract.tsindex 68ed1e234f..f3e50a6baa 100644--- a/src/core/ops/contract.ts+++ b/src/core/ops/contract.ts@@ -259,6 +259,18 @@ export interface ParamDef {description?: string;default?: unknown;enum?: string[];+ /**+ * GST-927: the valid range's lower bound (inclusive / exclusive). Read by normalizeOptionalParams only, never+ * advertised: on an optional param whose range excludes 0, a 0 reads as omitted. Declare it only where 0 refuses.+ */+ minimum?: number;+ exclusiveMinimum?: number;+ /** GST-927: on an optional array param, `[]` reads as omitted when this is at least 1. Not advertised. */+ minItems?: number;+ /** GST-927: a flag that acts only when true, so an optional `false` reads as omitted. Not advertised. */+ actsWhenTrue?: boolean;+ /** GST-927: the param has no effect without this one, so it reads as omitted when that param is absent. Not advertised. */+ appliesWith?: string;items?: ParamDef;/** Object members (O-DX-3); a member with `required: true` lands in the schema's `required`. */properties?: Record<string, ParamDef>;diff --git a/src/core/ops/get-page-body.ts b/src/core/ops/get-page-body.tsindex 90201c619a..f6c22f0bbf 100644--- a/src/core/ops/get-page-body.ts+++ b/src/core/ops/get-page-body.ts@@ -71,10 +71,10 @@ export const GET_PAGE_BODY_PARAMS: Record<string, ParamDef> = {body: { type: 'string', enum: [...BODY_MODES], description: 'auto: whole up to 256 KB, else outline + window; a window\'s edit_target is edit_page `within`. none: revision + size + tail_sha256 (append_page expected_tail_sha256).', fullSurfaceOnly: true },lines: { type: 'object', cliRange: ['from', 'count'], description: 'Window: 1-based lines.', properties: { from: { type: 'number', required: true }, count: { type: 'number', required: true } }, fullSurfaceOnly: true },bytes: { type: 'object', cliRange: ['offset', 'length'], description: 'Window: UTF-8 bytes of size.total_bytes, not body_bytes (snapped to a line start).', properties: { offset: { type: 'number', required: true }, length: { type: 'number', required: true } }, fullSurfaceOnly: true },- around_chunk_id: { type: 'number', description: 'Window around a search hit chunk_id.', fullSurfaceOnly: true },+ around_chunk_id: { type: 'number', minimum: 1, description: 'Window around a search hit chunk_id.', fullSurfaceOnly: true },context_lines: { type: 'number', description: 'Lines around around_chunk_id (20).', fullSurfaceOnly: true },cursor: { type: 'string', description: 'next_cursor: read on.', fullSurfaceOnly: true },- max_bytes: { type: 'number', description: 'Window bytes (40000).', fullSurfaceOnly: true },+ max_bytes: { type: 'number', minimum: 1, description: 'Window bytes (40000).', fullSurfaceOnly: true },view: { type: 'string', enum: ['read', 'markdown'], description: 'markdown: page the round-trip content.', fullSurfaceOnly: true },outline_from: { type: 'number', description: 'Outline next_from_index.', fullSurfaceOnly: true },...GET_PAGE_SLICE_PARAMS,diff --git a/src/core/ops/get-page-slice.ts b/src/core/ops/get-page-slice.tsindex fc72b36678..5ecc145c81 100644--- a/src/core/ops/get-page-slice.ts+++ b/src/core/ops/get-page-slice.ts@@ -33,7 +33,7 @@ import { FENCE, HEADING, HEADING_MAX_CHARS, clip } from '../page-window/window.texport const GET_PAGE_SLICE_PARAMS: Record<string, ParamDef> = {section: { type: 'string', description: 'Only the section under this heading (case-insensitive, first match), with its heading_path.', fullSurfaceOnly: true },grep: { type: 'string', description: 'Only the paragraphs containing this text (case-insensitive substring, not a regex), with line numbers and total_matches.', fullSurfaceOnly: true },- context: { type: 'number', description: 'With grep: paragraphs of context either side (default 1, max 5).', fullSurfaceOnly: true },+ context: { type: 'number', appliesWith: 'grep', description: 'With grep: paragraphs of context either side (default 1, max 5).', fullSurfaceOnly: true },};export const DEFAULT_GREP_CONTEXT = 1;diff --git a/src/core/ops/graph-rank.ts b/src/core/ops/graph-rank.tsindex 773e30f02d..a9931931a0 100644--- a/src/core/ops/graph-rank.ts+++ b/src/core/ops/graph-rank.ts@@ -179,11 +179,11 @@ const rank_entities: Operation = {+ 'title-prefixed person duplicates are listed under possible_duplicates, never merged. Ties order by slug, then source_id. coverage.state is behind when link extraction lags, so counts cover only extracted pages.',params: {direction: { type: 'string', enum: [...DIRECTIONS], description: "Rank by 'in' (inbound edges, default), 'out' (outbound edges) or 'both' (inbound + outbound)." },- types: { type: 'array', items: { type: 'string' }, description: "Page types to rank, e.g. ['person']. Default: the schema pack's entity types." },+ types: { type: 'array', minItems: 1, items: { type: 'string' }, description: "Page types to rank, e.g. ['person']. Default: the schema pack's entity types." },source_id: { type: 'string', description: "Only this source (it must be inside your source grant); '__all__' spans every source you can read. Both ends of a counted edge stay in scope." },link_type: { type: 'string', description: 'Count only edges of this link type, e.g. works_at.' },include_mentions: { type: 'boolean', description: 'Also count mention links (link_source mentions); default false.' },- limit: { type: 'number', description: `Rows to return (default ${RANK_ENTITIES_DEFAULT_LIMIT}, max ${RANK_ENTITIES_MAX_LIMIT}).` },+ limit: { type: 'number', minimum: 1, description: `Rows to return (default ${RANK_ENTITIES_DEFAULT_LIMIT}, max ${RANK_ENTITIES_MAX_LIMIT}).` },},handler: async (ctx, p) => {const params = parseParams(ctx, p);diff --git a/src/core/ops/known-as-of.ts b/src/core/ops/known-as-of.tsindex b8e860d5e6..201248b4dc 100644--- a/src/core/ops/known-as-of.ts+++ b/src/core/ops/known-as-of.ts@@ -6,6 +6,7 @@*/import type { OperationContext, ParamDef } from './contract.ts';import { opError } from './contract.ts';+import { opTransport, readFix } from './op-fix.ts';import { assertExplicitSourceLive, federatedSearchScope, pageNotFoundError, parseSourceIdParam } from './context.ts';import { inlineBodyBytes } from './get-page-body.ts';import { pageTrustForRead } from './get-page-projection.ts';@@ -17,12 +18,15 @@ import { fenceTranscriptText, quotesStored } from '../search/transcript-quote.tsexport const KNOWN_AS_OF_PARAM: ParamDef = { type: 'string', fullSurfaceOnly: true,description: 'Recorded time: the page as this brain had recorded it at this ISO 8601 instant (2026-10-01T12:00:00Z), from the belief ledger. Not as_of, which is valid time (a date).' };-export const VERSIONS_DIFF_PARAM: ParamDef = { type: 'boolean', fullSurfaceOnly: true, description: 'With known_as_of: each version also carries a unified diff from the version before it.' };+export const VERSIONS_DIFF_PARAM: ParamDef = { type: 'boolean', actsWhenTrue: true, fullSurfaceOnly: true, description: 'With known_as_of: each version also carries a unified diff from the version before it.' };/** get_page parameters that select a body window, a fuzzy match or an edit view, none of which a historical read serves. */const GET_PAGE_UNSUPPORTED = ['fuzzy', 'include_content', 'content_only', 'include_timeline_entries', 'grammar_diagnostics', 'include_quarantined','lines', 'bytes', 'around_chunk_id', 'context_lines', 'cursor', 'max_bytes', 'view', 'outline_from', 'section', 'grep', 'context'] as const;+/** The get_page arguments a recorded-time read serves; the refusal's fix keeps only these. */+const GET_PAGE_AS_OF_ARGS = ['slug', 'known_as_of', 'source_id', 'include_deleted', 'min_trust', 'body'];+/*** The one source a recorded-time read targets: the explicit or ambient source, else the only granted source whose* ledger names the slug. A remote caller's search counts only world-visible events of a page it can see now, and@@ -99,9 +103,15 @@ function ledgerView(read: PageAtTime) {export async function getPageKnownAsOf(ctx: OperationContext, p: Record<string, unknown>): Promise<Record<string, unknown>> {const at = parseKnownAsOf(p.known_as_of);const extra = GET_PAGE_UNSUPPORTED.filter(k => p[k] !== undefined && p[k] !== false);- if (extra.length || (p.body !== undefined && p.body !== 'auto' && p.body !== 'full' && p.body !== 'none')) {+ const badBody = p.body !== undefined && p.body !== 'auto' && p.body !== 'full' && p.body !== 'none';+ if (extra.length || badBody) {+ const drop: string[] = badBody ? [...extra, 'body'] : extra;+ const name = (k: string) => opTransport(ctx) === 'cli' ? `--${k.replace(/_/g, '-')}` : `\`${k}\``;+ const kept = Object.fromEntries(GET_PAGE_AS_OF_ARGS.filter(k => p[k] !== undefined && !drop.includes(k)).map(k => [k, p[k]]));throw opError('invalid_params', `get_page: known_as_of does not combine with ${extra.length ? extra.join(', ') : `body: ${String(p.body)}`}.`,- 'Read the page as recorded with known_as_of alone (plus source_id, include_deleted or body: "none"), or drop known_as_of for the current page.');+ `Drop ${drop.map(name).join(', ')} to read the page as recorded at known_as_of, or drop ${name('known_as_of')} for the current page. A recorded-time read takes only ${GET_PAGE_AS_OF_ARGS.slice(2).map(name).join(', ')} (auto, full or none).`,+ { fix: readFix('The same call without the arguments that select a window or view of the current page, which a recorded-time read does not serve.',+ { mcp: { tool: 'get_page', arguments: kept } }) });}const slug = String(p.slug);const sourceId = await targetSource(ctx, p, 'get_page');diff --git a/src/core/ops/links.ts b/src/core/ops/links.tsindex 7d0c2ba88e..70207a8b0d 100644--- a/src/core/ops/links.ts+++ b/src/core/ops/links.ts@@ -247,7 +247,7 @@ const LINK_ALL_SOURCES_PARAM = {description: 'Same as source_id __all__.',fullSurfaceOnly: true,} as const;-const LINK_LIMIT_PARAM = { type: 'number', description: `Rows per call (default ${LINK_READ_DEFAULT_LIMIT}, max ${LINK_READ_MAX_LIMIT}).` } as const;+const LINK_LIMIT_PARAM = { type: 'number', minimum: 1, description: `Rows per call (default ${LINK_READ_DEFAULT_LIMIT}, max ${LINK_READ_MAX_LIMIT}).` } as const;const LINK_CURSOR_PARAM = { type: 'string', description: 'next_cursor from the previous call (same filters).' } as const;const LINK_ALL_PARAM = { type: 'boolean', description: 'Local CLI only: every row, paging internally.', fullSurfaceOnly: true } as const;@@ -449,7 +449,7 @@ const get_backlinks: Operation = {all_sources: LINK_ALL_SOURCES_PARAM,type: { type: 'string', description: 'Referrer type.' },group: { type: 'string', enum: ['page'], description: 'Per page.' },- limit: { type: 'number', description: `≤${LINK_READ_MAX_LIMIT}` },+ limit: { type: 'number', minimum: 1, description: `≤${LINK_READ_MAX_LIMIT}` },cursor: { type: 'string', description: 'Next.' },all: LINK_ALL_PARAM,},@@ -573,6 +573,7 @@ const traverse_graph: Operation = {direction: { type: 'string', description: 'Remote default both.', enum: ['in', 'out', 'both'] },hops: {type: 'array',+ minItems: 1,description: '≤3 typed hops, e.g. [{"link_type":"founded","toward":"subject"}]; toward: object|subject.',items: { type: 'object', properties: { link_type: { type: 'string' }, toward: { type: 'string' } } },fullSurfaceOnly: true,@@ -648,7 +649,7 @@ const wanted_pages: Operation = {description: 'Link targets that have no page yet, most-referenced first: each was written as a link but its page does not exist, so no edge exists. Use to find entities worth a page (enrichment) or typo links to fix. The edge appears on its own once the page is created.',params: {source_id: { type: 'string', description: 'Only targets referenced from this source (must be inside your source grant).' },- limit: { type: 'number', description: `Rows per page (default ${WANTED_DEFAULT_LIMIT}, max ${WANTED_MAX_LIMIT}).` },+ limit: { type: 'number', minimum: 1, description: `Rows per page (default ${WANTED_DEFAULT_LIMIT}, max ${WANTED_MAX_LIMIT}).` },offset: { type: 'number', description: 'Skip the first N targets.' },count_only: { type: 'boolean', description: 'Return the total with no rows.' },},diff --git a/src/core/ops/loops.ts b/src/core/ops/loops.tsindex 44e776d04d..67d8ed1126 100644--- a/src/core/ops/loops.ts+++ b/src/core/ops/loops.ts@@ -410,7 +410,7 @@ const open_loops: Operation = {params: {group_by: { type: 'string', enum: ['counterparty', 'none'], description: "Default 'counterparty' (ranked groups)." },status: { type: 'string', enum: ['open', 'done', 'dropped', 'stale'], description: "Default 'open', except with `id`, where any status matches." },- id: { type: 'number', description: 'Fetch the single loop with this id (ids come from earlier open_loops results). Matches any status unless `status` is passed; the source scope still applies, and the grouped view omits `text`.' },+ id: { type: 'number', minimum: 1, description: 'Fetch the single loop with this id (ids come from earlier open_loops results). Matches any status unless `status` is passed; the source scope still applies, and the grouped view omits `text`.' },loop_type: { type: 'string', enum: ['commitment_owed_by_me', 'commitment_owed_to_me', 'unanswered_inbound', 'unanswered_outbound', 'decision_pending'], description: 'Filter to one loop type.' },counterparty: { type: 'string', description: 'Filter to one counterparty (slug or email).' },limit: { type: 'number', description: 'Grouped: max groups (default 3). Flat: max loops (default 50). The internal fetch is capped at 500 rows; `truncated: true` marks a hit.' },diff --git a/src/core/ops/orphans.ts b/src/core/ops/orphans.tsindex 7c2ea3440c..747689f28d 100644--- a/src/core/ops/orphans.ts+++ b/src/core/ops/orphans.ts@@ -36,6 +36,7 @@ const find_orphans: Operation = {},limit: {type: 'number',+ minimum: 1,description: `Rows per page (default ${ORPHANS_DEFAULT_LIMIT}, max ${ORPHANS_MAX_LIMIT}); total_orphans counts every orphan, complete says whether this page holds the rest, and next_cursor (or next_offset) names the next page.`,},offset: { type: 'number', description: 'Skip the first N orphans (ordered by source_id, then slug).' },diff --git a/src/core/ops/persistence.ts b/src/core/ops/persistence.tsindex b86c79a56e..37fecab2c2 100644--- a/src/core/ops/persistence.ts+++ b/src/core/ops/persistence.ts@@ -235,7 +235,7 @@ export const persistenceOperations: Operation[] = [description: 'Pages whose writes keep ending in a source_changed conflict, grouped by slug.',params: {source_id: { type: 'string', description: 'Default: yours.' },- limit: { type: 'number', default: 25, description: '1-100 slugs (default 25).' },+ limit: { type: 'number', minimum: 1, default: 25, description: '1-100 slugs (default 25).' },cursor: { type: 'string', description: "Previous page's next." },},scope: 'read', mutating: false, area: 'pages',diff --git a/src/core/ops/search-exact.ts b/src/core/ops/search-exact.tsindex 7d6e310a8b..d091e4620c 100644--- a/src/core/ops/search-exact.ts+++ b/src/core/ops/search-exact.ts@@ -56,11 +56,11 @@ const search_exact: Operation = {phrase: { type: 'string', required: true, description: "The literal text, e.g. 'INV-2024-0042' or 'quarterly board pack'." },case_sensitive: { type: 'boolean', description: 'Match case exactly (default false).' },source_id: { type: 'string', description: "Only this source; '__all__' spans every source you can read." },- types: { type: 'array', items: { type: 'string' }, description: "Only these page types, e.g. ['meeting']." },+ types: { type: 'array', minItems: 1, items: { type: 'string' }, description: "Only these page types, e.g. ['meeting']." },slug_prefix: { type: 'string', description: "Only slugs starting with this, e.g. 'meetings/'." },- limit: { type: 'number', description: 'Matching pages to return (default ' + EXACT_DEFAULT_LIMIT + ', max ' + EXACT_MAX_LIMIT + ').' },+ limit: { type: 'number', minimum: 1, description: 'Matching pages to return (default ' + EXACT_DEFAULT_LIMIT + ', max ' + EXACT_MAX_LIMIT + ').' },after: { type: 'number', description: 'Resume a bounded scan: the resume_after of the previous call.' },- max_seconds: { type: 'number', description: 'Scan budget in seconds (default ' + EXACT_DEFAULT_SECONDS + ', max ' + EXACT_MAX_SECONDS + ').' },+ max_seconds: { type: 'number', exclusiveMinimum: 0, description: 'Scan budget in seconds (default ' + EXACT_DEFAULT_SECONDS + ', max ' + EXACT_MAX_SECONDS + ').' },min_trust: MIN_TRUST_PARAM,},handler: async (ctx, p) => {diff --git a/src/core/ops/search.ts b/src/core/ops/search.tsindex 0862189dec..4945166baf 100644--- a/src/core/ops/search.ts+++ b/src/core/ops/search.ts@@ -168,6 +168,7 @@ const RETURN_UNIT_PARAM = {};const RETURN_WINDOW_PARAM = {type: 'number' as const,+ minimum: 1,description: 'Window radius 1-3.',fullSurfaceOnly: true,};diff --git a/src/core/ops/skills-catalog.ts b/src/core/ops/skills-catalog.tsindex bf04b4710b..07dd2047a6 100644--- a/src/core/ops/skills-catalog.ts+++ b/src/core/ops/skills-catalog.ts@@ -29,7 +29,7 @@ const list_skills: Operation = {description: LIST_SKILLS_DESCRIPTION,publishGateKey: 'mcp.publish_skills',params: {- schema_version: { type: 'number', description: '2 for the source-qualified catalog.', fullSurfaceOnly: true },+ schema_version: { type: 'number', minimum: 1, description: '2 for the source-qualified catalog.', fullSurfaceOnly: true },limit: { type: 'number', description: 'Page size or rank cap (1-100).' },cursor: { type: 'string', description: 'Version 2 cursor.', fullSurfaceOnly: true },source_id: { type: 'string', description: 'Version 2: one source.', fullSurfaceOnly: true },@@ -82,7 +82,7 @@ const get_skill: Operation = {description: GET_SKILL_DESCRIPTION,publishGateKey: 'mcp.publish_skills',params: {- schema_version: { type: 'number', description: '2 for an exact canonical revision.', fullSurfaceOnly: true },+ schema_version: { type: 'number', minimum: 1, description: '2 for an exact canonical revision.', fullSurfaceOnly: true },qualified_id: { type: 'string', description: 'Version 2 skill id.', fullSurfaceOnly: true },expected_brain_id: { type: 'string', description: 'Brain id to assert.', fullSurfaceOnly: true },source_incarnation: { type: 'string', description: 'From discovery.', fullSurfaceOnly: true },diff --git a/src/core/ops/takes.ts b/src/core/ops/takes.tsindex 6e127c6fe4..375b38d2d6 100644--- a/src/core/ops/takes.ts+++ b/src/core/ops/takes.ts@@ -167,7 +167,7 @@ const takes_scorecard: Operation = {since: { type: 'string', description: 'Window start (YYYY-MM-DD)' },until: { type: 'string', description: 'Window end (YYYY-MM-DD)' },group_by: { type: 'string', enum: ['holder', 'source'], description: 'Trusted local CLI only: per-group journal statistics' },- min_n: { type: 'number', description: 'Trusted local CLI only: groups with fewer resolved predictions are flagged low_n (default 10)' },+ min_n: { type: 'number', minimum: 1, description: 'Trusted local CLI only: groups with fewer resolved predictions are flagged low_n (default 10)' },},handler: async (ctx, p) => {// W7: the grouped journal statistics are private. A remote caller thatdiff --git a/src/core/ops/whois.ts b/src/core/ops/whois.tsindex 59ebdb1e19..64dfad70e1 100644--- a/src/core/ops/whois.ts+++ b/src/core/ops/whois.ts@@ -112,7 +112,7 @@ const whois: Operation = {+ 'Never fuzzy: empty matches means no exact match; ambiguous means several.',params: {query: { type: 'string', required: true, description: "Email address or name, e.g. '[email protected]'." },- types: { type: 'array', items: { type: 'string' }, description: "Page types; default: the schema pack's entity types." },+ types: { type: 'array', minItems: 1, items: { type: 'string' }, description: "Page types; default: the schema pack's entity types." },source_id: { type: 'string', description: "One source; '__all__' spans your sources." },},handler: async (ctx, p) => {diff --git a/src/mcp/validate-params.ts b/src/mcp/validate-params.tsindex 43c5157463..3c540055fa 100644--- a/src/mcp/validate-params.ts+++ b/src/mcp/validate-params.ts@@ -108,8 +108,10 @@ function retryWithValidParam(op: Operation, failure: ParamValidationFailure, par/*** Normalize the absent-idioms real MCP clients send for OPTIONAL params- * before validation and dispatch: `null` (any type) and `''` (string-typed- * params) become "not provided".+ * 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@@ -127,22 +129,46 @@ function retryWithValidParam(op: Operation, failure: ParamValidationFailure, par* 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, and nothing is+ * dropped from a param that declares no range: 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;- for (const [key, def] of Object.entries(op.params)) {- if (def.required) continue;- const val = params[key];- const isAbsentIdiom = val === null || (val === '' && def.type === 'string');- if (!isAbsentIdiom) continue;+ 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(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 the 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(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') {+ return Object.keys(val as object).length === 0 && Object.values(def.properties ?? {}).some(member => member.required);+ }+ return false;+}+// ---------------------------------------------------------------------------// WP3 — strict/warn unknown-argument validation// ---------------------------------------------------------------------------diff --git a/test/tool-args-empty-optional-sol.test.ts b/test/tool-args-empty-optional-sol.test.tsindex fcc8fee077..c3934d0796 100644--- a/test/tool-args-empty-optional-sol.test.ts+++ b/test/tool-args-empty-optional-sol.test.ts@@ -185,3 +185,121 @@ describe('sweep: every read op treats "" and null on optional args as omitted',}, 300_000);}});++/**+ * GST-927: the non-string empty values GPT-6.1 Sol fills in, GBRA-278's sweep list (21 zeros, 5 empty arrays,+ * 2 empty objects, 1 false). Each read as absent only because the param's schema rules it out (minimum,+ * exclusiveMinimum, minItems, an object with a required member, actsWhenTrue): on master every one refused.+ */+const SWEEP: Array<[op: string, param: string, value: unknown]> = [+ ['get_page', 'around_chunk_id', 0], ['get_page', 'max_bytes', 0], ['get_page', 'context', 0],+ ['list_write_conflicts', 'limit', 0], ['search_exact', 'limit', 0], ['get_links', 'limit', 0], ['get_backlinks', 'limit', 0],+ ['wanted_pages', 'limit', 0], ['get_versions', 'limit', 0], ['get_chunks', 'limit', 0], ['find_orphans', 'limit', 0],+ ['rank_entities', 'limit', 0], ['search', 'return_window', 0], ['search_exact', 'max_seconds', 0],+ ['get_write_attribution', 'fact', 0], ['get_write_attribution', 'take', 0], ['get_write_attribution', 'timeline', 0],+ ['list_skills', 'schema_version', 0], ['get_skill', 'schema_version', 0], ['takes_scorecard', 'min_n', 0], ['open_loops', 'id', 0],+ ['search_exact', 'types', []], ['traverse_graph', 'hops', []], ['run_doctor', 'only', []], ['whois', 'types', []], ['rank_entities', 'types', []],+ ['get_page', 'lines', {}], ['get_page', 'bytes', {}],+ ['get_versions', 'diff', false],+];++describe('GST-927: schema-ruled-out empty values (0, [], {}, false) read as omitted', () => {+ test('the table is GBRA-278\'s sweep list', () => {+ const count = (pred: (v: unknown) => boolean) => SWEEP.filter(([, , v]) => pred(v)).length;+ expect([count(v => v === 0), count(v => Array.isArray(v)), count(v => !!v && typeof v === 'object' && !Array.isArray(v)), count(v => v === false)]).toEqual([21, 5, 2, 1]);+ for (const [op, param] of SWEEP) expect(operationsByName[op]?.params[param]?.required).not.toBe(true);+ });++ test('every sweep value matches the call with the argument omitted, on every entry point', async () => {+ const mismatches: string[] = [];+ for (const [opName, param, value] of SWEEP) {+ const op = operationsByName[opName]!;+ const base = { ...requiredArgs(op), ...(opName === 'get_page' || opName === 'get_versions' || opName === 'get_write_attribution' ? { slug: SLUG } : {}) };+ for (const [name, call] of Object.entries(paths)) {+ const omitted = await call(opName, base);+ const filled = await call(opName, { ...base, [param]: value });+ if (summary(filled) !== summary(omitted)) mismatches.push(`${name} ${opName} ${param}=${JSON.stringify(value)}: omitted=${summary(omitted)} filled=${summary(filled)} (${filled.text.slice(0, 120)})`);+ }+ }+ expect(mismatches).toEqual([]);+ }, 300_000);++ test('a value inside the valid range, a negative number and a non-empty list are never dropped', async () => {+ const outcomes: Record<string, string[]> = {};+ for (const [name, call] of Object.entries(paths)) {+ outcomes[name] = [+ refusal(await call('get_page', { slug: SLUG, around_chunk_id: -1 })),+ refusal(await call('get_page', { slug: SLUG, max_bytes: -5 })),+ refusal(await call('list_write_conflicts', { limit: 101 })),+ refusal(await call('get_page', { slug: SLUG, lines: { from: 1, count: 2 }, bytes: { offset: 0, length: 10 } })),+ refusal(await call('traverse_graph', { slug: SLUG, depth: 1, hops: [{ link_type: 'founded', toward: 'object' }] })),+ refusal(await call('get_versions', { slug: SLUG, diff: true })),+ ];+ }+ const refused = Object.fromEntries(Object.entries(outcomes).map(([k, v]) => [k, v.filter(o => o !== 'not_registered')]));+ expect(refused).toEqual(Object.fromEntries(Object.entries(outcomes).map(([k, v]) => [k, Array(v.filter(o => o !== 'not_registered').length).fill('invalid_params')])));+ expect(refused['mcp remote (http)']).toHaveLength(6);+ }, 120_000);+});++/**+ * GST-927: the shapes GBEV-3 replayed from 651 recorded Sol calls (gbrain-evals+ * test/eval/skillopt-rollout-empty-args.test.ts). On master, get_page refused `context` without `grep` and+ * traverse_graph refused `hops: []` beside depth/link_type/direction.+ */+const SOL_GET_PAGE = {+ fuzzy: false, include_content: true, content_only: false, body: 'full', lines: {}, bytes: {}, around_chunk_id: 0,+ context_lines: 20, cursor: '', outline_from: 0, section: '', grep: '', context: 1, include_deleted: false,+ include_timeline_entries: false, grammar_diagnostics: false, include_quarantined: false, known_as_of: '', source_id: 'default',+};++describe("GST-927: GBEV-3's replayed Sol shapes", () => {+ test('get_page with context but no grep, and every other optional filled Sol-style, reads the page on every entry point', async () => {+ const results: Record<string, string> = {};+ for (const [name, call] of Object.entries(paths)) {+ const out = await call('get_page', { slug: SLUG, ...SOL_GET_PAGE });+ results[name] = out.ok && out.text.includes(BODY_MARKER) ? 'read' : `${summary(out)}: ${out.text.slice(0, 160)}`;+ }+ expect(results).toEqual(Object.fromEntries(Object.keys(paths).map(k => [k, 'read'])));+ });++ test('context with grep still applies, and context with a real grep is never dropped', async () => {+ const out = await paths['mcp remote (http)']!('get_page', { slug: SLUG, grep: 'marker', context: 0 });+ expect(out.ok).toBe(true);+ expect(out.text).toContain('"context":0');+ });++ test('traverse_graph with hops: [] beside depth, link_type and direction walks the graph on every entry point', async () => {+ const results: Record<string, string> = {};+ for (const [name, call] of Object.entries(paths)) {+ const sol = await call('traverse_graph', { slug: SLUG, depth: 1, link_type: 'founded', direction: 'out', hops: [], source_id: 'default', all_sources: false });+ const plain = await call('traverse_graph', { slug: SLUG, depth: 1, link_type: 'founded', direction: 'out', source_id: 'default', all_sources: false });+ results[name] = sol.ok && summary(sol) === summary(plain) ? 'walked' : `${summary(sol)}: ${sol.text.slice(0, 160)}`;+ }+ expect(results).toEqual(Object.fromEntries(Object.keys(paths).map(k => [k, 'walked'])));+ });++ test("Sol's recorded window arguments still refuse: two window selectors are real values that change the answer", async () => {+ const out = await paths['mcp remote (http)']!('get_page', { slug: SLUG, ...SOL_GET_PAGE, lines: { from: 1, count: 200 }, bytes: { offset: 0, length: 40000 } });+ expect(out.ok).toBe(false);+ expect(out.text).toContain('pass one window selector, not 2');+ });++ test('known_as_of beside read-view arguments refuses, naming each argument to drop, with a fix that keeps only recorded-time arguments', async () => {+ const args = { slug: SLUG, ...SOL_GET_PAGE, known_as_of: '2026-10-01T12:00:00Z', max_bytes: 40000, view: 'read' };+ for (const [name, call] of Object.entries(paths)) {+ const out = await call('get_page', args);+ expect([name, refusal(out)]).toEqual([name, 'invalid_params']);+ expect(out.text).toContain('get_page: known_as_of does not combine with include_content');+ }+ expect((await paths['mcp remote (http)']!('get_page', args)).text).toContain('known_as_of does not combine with include_content, context_lines, max_bytes, view, outline_from.');+ const remote = JSON.parse((await dispatchToolCall(engine, 'get_page', args, { remote: true, transport: 'http', sourceId: 'default' })).content[0]!.text) as { suggestion?: string };+ expect(remote.suggestion).toContain('Drop `include_content`, `context_lines`, `max_bytes`, `view`, `outline_from` to read the page as recorded');+ const local = await handleToolCall(engine, 'get_page', args).then(() => null, (e: { suggestion?: string; fix?: { mcp?: { tool: string; arguments: Record<string, unknown> } } }) => e);+ expect(local?.suggestion).toContain('Drop --include-content, --context-lines, --max-bytes, --view, --outline-from to read the page as recorded');+ expect(local?.fix?.mcp).toEqual({ tool: 'get_page', arguments: { slug: SLUG, known_as_of: '2026-10-01T12:00:00Z', source_id: 'default', include_deleted: false, body: 'full' } });+ const retried = await dispatchToolCall(engine, 'get_page', local!.fix!.mcp!.arguments, { remote: true, transport: 'http', sourceId: 'default' });+ expect(retried.content[0]!.text).not.toContain('does not combine with');+ });+});+