Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
fix(get_page): say one window selector up front; the two-selector refusal carries a single-selector fix (GST-927)
garrytan5f500a568eeb
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 21ef34338f..e3988c5445 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -14,13 +14,14 @@ identifiers and attribution are available in the pre-removal Git revision**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 the 651 GPT-6.1 Sol calls recorded in the SkillOpt probe, 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.+`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 the 651 GPT-6.1 Sol calls recorded in the SkillOpt probe, 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. Those still refuse, but `get_page`'s description and its selector parameters now say to pass at most one window selector, and the refusal's `fix` is a runnable single-selector call built from the caller's own arguments: the first selector alone, with `body: "window"`. All 436 fixes read the page in the replay.### 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 a sweep of every read operation 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/get-page-body.ts`, `src/core/ops/pages.ts`, `src/core/ops/get-page-slice.ts`: the get_page description and the `lines`, `bytes`, `around_chunk_id`, `cursor` and `context` descriptions state the one-selector rule. The two-selector refusal names the selectors to drop and carries a read `fix`. `test/mcp-schema-budget.test.ts`: the starter list ceilings and the get_page budget rise by 100 characters for that sentence.- `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`.diff --git a/docs/guides/windowed-reads.md b/docs/guides/windowed-reads.mdindex 30f60e8521..879a5d5878 100644--- a/docs/guides/windowed-reads.md+++ b/docs/guides/windowed-reads.md@@ -37,8 +37,10 @@ contract in `get_brain_identity` as `capabilities: ["large_pages_v1"]`.| `max_bytes` | Window size (default 40,000, at most 1 MiB, and always inside the connection's cap). || `view: "markdown"` | Page the round-trip markdown (`include_content`'s `content`) instead of the read text; `size.sha256` verifies the joined pages. |-Passing two selectors, a selector with `body: "outline"`, or `include_content`-with a partial mode is `invalid_params` with an example. A window response+Passing a selector with `body: "outline"`, or `include_content` with a partial+mode, is `invalid_params` with an example. Passing two selectors is+`invalid_params` whose fix is the same call with the first one alone (lines,+then bytes, around_chunk_id, cursor) and `body: "window"`. A window responsecarries `window {text, byte_start, byte_end, line_start, line_end}`,`size {total_bytes, total_lines}`, `truncated`, and when more follows`next_cursor` plus `next`, the exact `get_page` call that reads on. The starterdiff --git a/src/core/operation-manifest.generated.ts b/src/core/operation-manifest.generated.tsindex 47a820e894..e650f0cdcb 100644--- a/src/core/operation-manifest.generated.ts+++ b/src/core/operation-manifest.generated.ts@@ -240,7 +240,7 @@ export const OPERATION_MANIFEST: OperationMeta[] = ["outputRedaction": {"exempt": "explicit page read by slug/id; governed by page visibility, not output redaction (CEO-17 raw-read exception)"},- "description": "Read a page; `section` or `grep` reads one part. Edit: include_content:true, `content` to put_page, or edit_page. >256 KB: outline+window, then `next`.",+ "description": "Read a page; `section`/`grep` reads one part. Pass at most one window selector: lines, bytes, around_chunk_id or cursor (context only with grep). Edit: include_content:true, `content` to put_page, or edit_page. >256 KB: outline+window, then `next`.","params": {"slug": {"type": "string",@@ -279,7 +279,7 @@ export const OPERATION_MANIFEST: OperationMeta[] = ["from","count"],- "description": "Window: 1-based lines.",+ "description": "Window: 1-based lines. One window selector only: not with bytes, around_chunk_id or cursor.","properties": {"from": {"type": "number",@@ -298,7 +298,7 @@ export const OPERATION_MANIFEST: OperationMeta[] = ["offset","length"],- "description": "Window: UTF-8 bytes of size.total_bytes, not body_bytes (snapped to a line start).",+ "description": "Window: UTF-8 bytes of size.total_bytes, not body_bytes (snapped to a line start). One window selector only: not with lines, around_chunk_id or cursor.","properties": {"offset": {"type": "number",@@ -314,7 +314,7 @@ export const OPERATION_MANIFEST: OperationMeta[] = ["around_chunk_id": {"type": "number","minimum": 1,- "description": "Window around a search hit chunk_id.",+ "description": "Window around a search hit chunk_id. One window selector only: not with lines, bytes or cursor.","fullSurfaceOnly": true},"context_lines": {@@ -324,7 +324,7 @@ export const OPERATION_MANIFEST: OperationMeta[] = [},"cursor": {"type": "string",- "description": "next_cursor: read on.",+ "description": "next_cursor: read on. One window selector only: not with lines, bytes or around_chunk_id.","fullSurfaceOnly": true},"max_bytes": {@@ -360,7 +360,7 @@ export const OPERATION_MANIFEST: OperationMeta[] = ["context": {"type": "number","appliesWith": "grep",- "description": "With grep: paragraphs of context either side (default 1, max 5).",+ "description": "Applies only with grep (ignored without it): paragraphs of context either side (default 1, max 5).","fullSurfaceOnly": true},"include_deleted": {diff --git a/src/core/ops/get-page-body.ts b/src/core/ops/get-page-body.tsindex f6c22f0bbf..6fd99fcac1 100644--- a/src/core/ops/get-page-body.ts+++ b/src/core/ops/get-page-body.ts@@ -31,7 +31,7 @@import type { Page } from '../types.ts';import type { OperationContext, ParamDef } from './contract.ts';import { opError, OperationError } from './contract.ts';-import { invalidParam, readFix } from './op-fix.ts';+import { invalidParam, opTransport, readFix } from './op-fix.ts';import { serializePageToMarkdown } from '../markdown.ts';import { isSegmentedPage, pageBodyBytes } from '../page-body/page-shape.ts';import { deepResearchPageUrl, encodeDeepResearchId } from '../deep-research-id.ts';@@ -69,11 +69,11 @@ export const LARGE_PAGES_CAPABILITY = 'large_pages_v1';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', minimum: 1, description: 'Window around a search hit chunk_id.', fullSurfaceOnly: true },+ lines: { type: 'object', cliRange: ['from', 'count'], description: 'Window: 1-based lines. One window selector only: not with bytes, around_chunk_id or cursor.', 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). One window selector only: not with lines, around_chunk_id or cursor.', properties: { offset: { type: 'number', required: true }, length: { type: 'number', required: true } }, fullSurfaceOnly: true },+ around_chunk_id: { type: 'number', minimum: 1, description: 'Window around a search hit chunk_id. One window selector only: not with lines, bytes or cursor.', 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 },+ cursor: { type: 'string', description: 'next_cursor: read on. One window selector only: not with lines, bytes or around_chunk_id.', 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 },@@ -136,7 +136,14 @@ export function parseBodyRequest(ctx: Pick<OperationContext, 'remote' | 'transposelectors.push({ kind: 'cursor', raw: p.cursor });}if (selectors.length > 1) {- throw bad(selectors[1].kind === 'around' ? 'around_chunk_id' : selectors[1].kind, `get_page: pass one window selector, not ${selectors.length} (got ${selectors.map(s => s.kind === 'around' ? 'around_chunk_id' : s.kind).join(' and ')}).`);+ const [keep, ...drop] = selectors.map(s => s.kind === 'around' ? 'around_chunk_id' : s.kind);+ const conflicts = ['include_content', 'content_only', ...(keep === 'around_chunk_id' && p.view === 'markdown' ? ['view'] : [])];+ const args = Object.fromEntries(Object.entries(p).filter(([k, v]) => v !== undefined && k !== '_meta' && !drop.includes(k) && !conflicts.includes(k)));+ const name = (k: string) => opTransport(ctx) === 'cli' ? `--${k.replace(/_/g, '-')}` : `\`${k}\``;+ throw opError('invalid_params', `get_page: pass one window selector, not ${selectors.length} (got ${[keep, ...drop].join(' and ')}).`,+ `Pass at most one window selector: lines, bytes, around_chunk_id or cursor. Drop ${drop.map(name).join(' and ')} to read the ${keep} window, or pass one of them alone to read there instead.`,+ { fix: readFix(`The same call with one window selector (${keep}) and body: "window"; ${[...drop, ...conflicts.filter(k => p[k] !== undefined)].join(', ')} dropped.`,+ { mcp: { tool: 'get_page', arguments: { ...args, body: 'window' } } }) });}const includeContent = p.include_content === true;const contentOnly = p.content_only === true;diff --git a/src/core/ops/get-page-slice.ts b/src/core/ops/get-page-slice.tsindex 5ecc145c81..279a2073ee 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', appliesWith: 'grep', description: 'With grep: paragraphs of context either side (default 1, max 5).', fullSurfaceOnly: true },+ context: { type: 'number', appliesWith: 'grep', description: 'Applies only with grep (ignored without it): paragraphs of context either side (default 1, max 5).', fullSurfaceOnly: true },};export const DEFAULT_GREP_CONTEXT = 1;diff --git a/src/core/ops/pages.ts b/src/core/ops/pages.tsindex ab0f3825bb..79bbb5a24f 100644--- a/src/core/ops/pages.ts+++ b/src/core/ops/pages.ts@@ -95,7 +95,7 @@ const get_page: Operation = {name: 'get_page',idempotent: true,outputRedaction: { exempt: 'explicit page read by slug/id; governed by page visibility, not output redaction (CEO-17 raw-read exception)' },- description: 'Read a page; `section` or `grep` reads one part. Edit: include_content:true, `content` to put_page, or edit_page. >256 KB: outline+window, then `next`.',+ description: 'Read a page; `section`/`grep` reads one part. Pass at most one window selector: lines, bytes, around_chunk_id or cursor (context only with grep). Edit: include_content:true, `content` to put_page, or edit_page. >256 KB: outline+window, then `next`.',params: {slug: { type: 'string', description: 'Page slug.', required: true },fuzzy: { type: 'boolean', description: 'Fuzzy match.', fullSurfaceOnly: true },diff --git a/test/mcp-schema-budget.test.ts b/test/mcp-schema-budget.test.tsindex 6b02278c1c..6b234dcd68 100644--- a/test/mcp-schema-budget.test.ts+++ b/test/mcp-schema-budget.test.ts@@ -63,14 +63,14 @@ import { stdioVisibleTools } from '../src/mcp/server.ts';import { buildMcpInstructions, GBRAIN_MCP_INSTRUCTIONS } from '../src/mcp/instructions.ts';import { cl100kAvailable, estimateTokens } from '../src/core/chunkers/token-estimate.ts';-const SERVED_STARTER_MAX_CHARS = 18_200;+const SERVED_STARTER_MAX_CHARS = 18_300; // GST-927: +100 for get_page's one-window-selector rule (GPT-6.1 Sol sent lines, bytes and around_chunk_id together on 436 of 607 recorded calls); get_page's own text paid 3/** Headroom the served starter list must keep under the ceiling (wave 16: 24,998 of 25,000 left 2 characters; 200 is what the wave reaches without touching text other threads own, raised to 300 once the entity card and query/search trims land). */const SERVED_STARTER_MIN_HEADROOM = 200;const SERVED_STARTER_MAX_TOKENS = 4_300;/** The whole tools/list JSON, annotations included (25,735 measured at v0.60.46.0; traverse_graph's `hops` is full-surface-only, 25,941 measured; 26,402 once mute_notice, the dismissal for the coaching notices starter sessions receive, joined starter; 26,671 with #6007's put_page wait_ms param and write guidance, which carry the put_pages hint and the receipt poll rule starter agents need; 26,679 with delta's opaque `cursor` param, paid for by trimming delta's own descriptions, model-visible 24,985; 26,692 with recall's `question` param, paid for by trimming recall's own parameter text, model-visible 24,998; 24,996 after the #6446 merge, recall's grep text trimmed again). */-const SERVED_STARTER_MAX_JSON_CHARS = 19_800; // GBRA-156: 19,431 measured+const SERVED_STARTER_MAX_JSON_CHARS = 19_900; // GBRA-156: 19,431 measured; GST-927: +100 for get_page's one-window-selector rule/** GBRA-156: the UTF-8 bytes of the served starter tools/list result (`{"tools":[...]}`, annotations included) that harnesses re-fetch every turn. */-const SERVED_STARTER_MAX_RESULT_BYTES = 19_800; // 26,546 before GBRA-156, 19,489 after+const SERVED_STARTER_MAX_RESULT_BYTES = 19_900; // 26,546 before GBRA-156, 19,489 after; GST-927: +100 for get_page's one-window-selector rule/** 4,042 at the cost wave + 586 for the operator contract's error protocol, notice prefix and memory loop (F1); no schema guidance moved here. */const INSTRUCTIONS_MAX_CHARS = 5_108; // #6007: +240 for the issue-required write guidance (put_pages, wait_ms); Cat 40 Hard round 4: +107 for batching lists of names (entity names, keyword OR) and sending independent calls together; d5b: +70 for the brief naming the fields compact `entity names` rows carry (the maximal rendering, record types enrolled; +39 at the default) instead of a `referenced_by` walk batch mode cannot do; F4: +63 for instruction 7's governing rule (the record whose terms are in effect on the date asked about governs; page dates are named as page dates), 74 characters longer than the "prefer the newest governing source" sentence it replaces, 11 paid by cutting "the best-ranked excerpts" to "top excerpts" in the same clauseconst DESCRIPTION_HARD_CAP = 1_200;@@ -104,7 +104,7 @@ const PARAM_DESCRIPTION_HARD_CAP = 200;const TOOL_BUDGETS: Record<string, number> = {add_timeline_entry: 730, cancel_job: 270, cancel_write_request: 350, capture: 710, context_pack: 500,delete_skill: 810, delta: 580, edit_page: 1040, entity: 550, find_anomalies: 400, forget: 530, get_agent_job: 270,- get_backlinks: 710, get_ingest_log: 280, get_page: 510, get_recent_salience: 450, get_skill: 490,+ get_backlinks: 710, get_ingest_log: 280, get_page: 600, get_recent_salience: 450, get_skill: 490,get_skill_asset: 530, get_write_request: 360, join_brain: 560, leave_brain: 540, list_brain_skillpack: 230,list_link_sources: 220, list_pages: 850, list_skills: 400, list_write_requests: 370, put_page: 1090,mute_notice: 420, put_skill: 1420, query: 1700, recall: 840, remember: 940, request_tools: 530, resolve_slugs: 410, search: 1420,diff --git a/test/tool-args-empty-optional-sol.test.ts b/test/tool-args-empty-optional-sol.test.tsindex dead8dc550..d46f5ae25e 100644--- a/test/tool-args-empty-optional-sol.test.ts+++ b/test/tool-args-empty-optional-sol.test.ts@@ -280,9 +280,25 @@ describe("GST-927: GBEV-3's replayed Sol shapes", () => {});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 } });+ const args = { slug: SLUG, ...SOL_GET_PAGE, lines: { from: 1, count: 200 }, bytes: { offset: 0, length: 40000 }, around_chunk_id: 7, max_bytes: 40000, view: 'read' };+ const out = await paths['mcp remote (http)']!('get_page', args);expect(out.ok).toBe(false);- expect(out.text).toContain('pass one window selector, not 2');+ expect(out.text).toContain('pass one window selector, not 3 (got lines and bytes and around_chunk_id)');+ expect(out.text).toContain('Drop `bytes` and `around_chunk_id` to read the lines window');+ const local = await handleToolCall(engine, 'get_page', args).then(() => null, (e: { fix?: { mcp?: { tool: string; arguments: Record<string, unknown> } } }) => e);+ const fixed = local?.fix?.mcp?.arguments ?? {};+ expect(Object.keys(fixed).filter(k => ['lines', 'bytes', 'around_chunk_id', 'cursor'].includes(k))).toEqual(['lines']);+ expect(fixed).toMatchObject({ slug: SLUG, lines: { from: 1, count: 200 }, body: 'window', max_bytes: 40000, view: 'read', source_id: 'default' });+ expect(fixed.include_content).toBeUndefined();+ const retried = await paths['mcp remote (http)']!('get_page', fixed);+ expect([retried.ok, retried.text.includes(BODY_MARKER)]).toEqual([true, true]);+ });++ test('get_page tells callers up front: at most one window selector, context only with grep', () => {+ const op = operationsByName.get_page!;+ expect(op.description).toContain('Pass at most one window selector: lines, bytes, around_chunk_id or cursor (context only with grep)');+ for (const k of ['lines', 'bytes', 'around_chunk_id', 'cursor']) expect(op.params[k]!.description).toContain('One window selector only');+ expect(op.params.context!.description).toContain('Applies only with grep');});test('known_as_of beside read-view arguments refuses, naming each argument to drop, with a fix that keeps only recorded-time arguments', async () => {