Skip to content

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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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([]);
+});