Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
fix(tools): GST-927 review notes: known_as_of fix carries argv, write-op guard test, doc comments
garrytanc847bc074547
diff --git a/src/core/ops/contract.ts b/src/core/ops/contract.tsindex f3e50a6baa..1477396e24 100644--- a/src/core/ops/contract.ts+++ b/src/core/ops/contract.ts@@ -260,16 +260,16 @@ export interface ParamDef {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.+ * GST-927: the valid range's lower bound (inclusive / exclusive). Read by normalizeOptionalParams and carried in the+ * operation manifest, never in the tools/list schema. Only on read ops (test/tool-args-empty-optional-sol.test.ts): 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. */+ /** GST-927: on an optional array param, `[]` reads as omitted when this is at least 1. Not in tools/list. */minItems?: number;- /** GST-927: a flag that acts only when true, so an optional `false` reads as omitted. Not advertised. */+ /** GST-927: a flag that acts only when true, so an optional `false` reads as omitted. Not in tools/list. */actsWhenTrue?: boolean;- /** GST-927: the param has no effect without this one, so it reads as omitted when that param is absent. Not advertised. */+ /** GST-927: the param has no effect without this one, so any value of it reads as omitted when that param is absent. Not in tools/list. */appliesWith?: string;items?: ParamDef;/** Object members (O-DX-3); a member with `required: true` lands in the schema's `required`. */diff --git a/src/core/ops/known-as-of.ts b/src/core/ops/known-as-of.tsindex 201248b4dc..1c8403ac09 100644--- a/src/core/ops/known-as-of.ts+++ b/src/core/ops/known-as-of.ts@@ -111,7 +111,8 @@ export async function getPageKnownAsOf(ctx: OperationContext, p: Record<string,throw opError('invalid_params', `get_page: known_as_of does not combine with ${extra.length ? extra.join(', ') : `body: ${String(p.body)}`}.`,`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 } }) });+ { argv: ['gbrain', 'get', ...Object.entries(kept).filter(([k]) => k !== 'slug').flatMap(([k, v]) => v === true ? [`--${k.replace(/_/g, '-')}`] : v === false ? [] : [`--${k.replace(/_/g, '-')}`, String(v)]), '--', String(p.slug)],+ 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/loops.ts b/src/core/ops/loops.tsindex 67d8ed1126..561b208f29 100644--- a/src/core/ops/loops.ts+++ b/src/core/ops/loops.ts@@ -614,7 +614,8 @@ const open_loops: Operation = {};/**- * open_loops `id`: absent or null means a list read. Anything else must be a+ * open_loops `id`: absent or null means a list read (over the tool paths, 0+ * reads as absent too: `minimum: 1`, GST-927). Anything else must be a* positive safe integer. The refusal never echoes the raw value. The digest* stays off for a lookup because it describes the open list ("waiting on* you", "You are clean"), which is false for a closed or missing loop.diff --git a/src/mcp/validate-params.ts b/src/mcp/validate-params.tsindex 3c540055fa..01d8d5bfde 100644--- a/src/mcp/validate-params.ts+++ b/src/mcp/validate-params.ts@@ -129,9 +129,11 @@ 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.+ * - 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.*/diff --git a/test/tool-args-empty-optional-sol.test.ts b/test/tool-args-empty-optional-sol.test.tsindex c3934d0796..dead8dc550 100644--- a/test/tool-args-empty-optional-sol.test.ts+++ b/test/tool-args-empty-optional-sol.test.ts@@ -297,9 +297,18 @@ describe("GST-927: GBEV-3's replayed Sol shapes", () => {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 as { fix?: { argv?: string[] } } | null)?.fix?.argv).toEqual(['gbrain', 'get', '--known-as-of', '2026-10-01T12:00:00Z', '--source-id', 'default', '--body', 'full', '--', SLUG]);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');});});++test('GST-927: the absence annotations sit only on optional params of read ops, so normalization never drops a write argument', () => {+ const keys = ['minimum', 'exclusiveMinimum', 'minItems', 'actsWhenTrue', 'appliesWith'] as const;+ const misplaced = operations.flatMap(op => Object.entries(op.params)+ .filter(([, d]) => keys.some(k => d[k] !== undefined) && (op.mutating !== false || d.required))+ .map(([k]) => `${op.name}.${k}`));+ expect(misplaced).toEqual([]);+});