Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

fix: pre-landing review fixes

garrytan6d1f659a3b91
diff --git a/docs/guides/search-explain.md b/docs/guides/search-explain.md
index 5aaed61341..f1426c9617 100644
--- a/docs/guides/search-explain.md
+++ b/docs/guides/search-explain.md
@@ -115,7 +115,7 @@ failed on the call, `why` names it, since a failed arm is not evidence of absenc
| `target_dropped_return_sizing` | Autocut or adaptive return trimmed it. | `get_page`, or repeat with `autocut: false` (query). |
| `target_dropped_token_budget` | The evidence budget filled first. | Repeat with a larger `token_budget`. |
| `target_dropped_relaxed_keyword` | Only a loose keyword match found it. | `get_page`, or rephrase with the page's own terms. |
-| `target_not_retrieved` | No arm returned it for this query. | `query --expand` (`expand: true`; one call to the configured expansion model) or rephrase. |
+| `target_not_retrieved` | No arm returned it for this query. | `query --expand` (`expand: true`; one call to the configured expansion model) or rephrase. The fix carries `consent: ["paid", "egress"]`, so it renders `next: ask_user`: the agent asks before sending the query to the model. |
| `target_not_embedded` | Its chunks have no vectors (held from embedding or not embedded yet), so only a keyword or title match can return it. | `gbrain doctor --json` names the held pages and the embed command. |
| `target_not_indexed` | The page has no indexed chunks. | `gbrain doctor --json` names the re-index command. |
| `target_projection_stale` | The page changed and its searchable text is still being rebuilt. | Retry after `gbrain doctor` shows the backlog drained. |
diff --git a/src/core/search/explain-target.ts b/src/core/search/explain-target.ts
index d4a1375e88..abe3d201d0 100644
--- a/src/core/search/explain-target.ts
+++ b/src/core/search/explain-target.ts
@@ -22,7 +22,7 @@
*/
import type { SearchResult, PageReadPolicy } from '../types.ts';
-import type { Action } from '../agent-output.ts';
+import type { Action, Effect } from '../agent-output.ts';
import { pageReadFilter } from './read-policy-sql.ts';
import { belowSafeChunkFence, chunkGenerationFilter } from './safe-chunks.ts';
@@ -102,17 +102,18 @@ function armsOf(trace: TargetTrace): ExplainTargetDiagnosis['arms'] {
type Retry = { tool: 'search' | 'query'; arguments: Record<string, unknown> };
/** A complete retry: the MCP call and the CLI argv for the same arguments (#7192: a fix always names its command). */
-function retryAction(tool: 'search' | 'query', args: Record<string, unknown>, why: string): Action {
+function retryAction(tool: 'search' | 'query', args: Record<string, unknown>, why: string, consent: Effect[] = []): Action {
const { json, ...mcpArgs } = args;
const argv = ['gbrain', tool, String(args.query ?? '')];
for (const [key, value] of Object.entries(mcpArgs)) {
- if (key === 'query' || value === undefined || value === null || typeof value === 'object') continue;
+ if (key === 'query' || value === undefined || value === null) continue;
const flag = key.replace(/_/g, '-');
- if (typeof value === 'boolean') argv.push(value ? `--${flag}` : `--no-${flag}`);
+ if (typeof value === 'object') argv.push(`--${flag}`, JSON.stringify(value));
+ else if (typeof value === 'boolean') argv.push(value ? `--${flag}` : `--no-${flag}`);
else argv.push(`--${flag}`, String(value));
}
if (json === true) argv.push('--json');
- return { mcp: { tool, arguments: mcpArgs }, argv, consent: [], actor: 'agent', requires_exclusive: false, why };
+ return { mcp: { tool, arguments: mcpArgs }, argv, consent, actor: 'agent', requires_exclusive: false, why };
}
/** Recall-affecting arm failures on this call, as one clause (#7171): an arm that did not answer is not evidence of absence. */
@@ -165,7 +166,7 @@ export function diagnoseTrace(
if (arms.length === 0) {
return { target, state: 'not_retrieved', code: 'target_not_retrieved', arms, stages,
why: `No retrieval arm (semantic, keyword, title, relational) returned the page for this query.${degradedClause(degraded)}`,
- fix: retryAction('query', { ...retry.arguments, expand: true }, 'Expansion (one LLM call) recovers pages phrased differently from the question; or read the page directly with get_page.') };
+ fix: retryAction('query', { ...retry.arguments, expand: true }, 'Expansion (one LLM call) recovers pages phrased differently from the question; or read the page directly with get_page.', ['paid', 'egress']) };
}
// The page reached at least one arm: find the first post-arm stage that lost it.
const keywordRaw = trace.last('arm:keyword_raw');
diff --git a/test/search/explain-target-cli-json-7192.test.ts b/test/search/explain-target-cli-json-7192.test.ts
index 37bf34add6..b513ae72b2 100644
--- a/test/search/explain-target-cli-json-7192.test.ts
+++ b/test/search/explain-target-cli-json-7192.test.ts
@@ -42,7 +42,20 @@ describe('#7192 explain_target in CLI --json', () => {
captureRetrievalMeta('retrieval', { explain_target: diag });
const out = JSON.parse(formatResult('search', [], { json: true, explain_target: 'notes/x' }));
expect(out.results).toEqual([]);
- expect(out.explain_target.fix).toMatchObject({ next: 'run', argv: ['gbrain', 'query', 'q', '--expand'] });
+ expect(out.explain_target.fix).toMatchObject({ next: 'ask_user', argv: ['gbrain', 'query', 'q', '--expand'] });
+ expect(diag.fix?.consent).toEqual(['paid', 'egress']);
+ });
+
+ test('the retry argv carries array and object arguments, so it repeats the diagnosed call', () => {
+ const t = new TargetTrace({ slug: 'notes/x' });
+ const pool = [row('notes/a', 0.9), row('notes/x', 0.7)];
+ t.observe('arm:keyword', pool);
+ for (const stage of ['fused', 'deduped', 'return_pool'] as const) t.observe(stage, pool);
+ t.observe('limit_slice', pool.slice(0, 1));
+ const diag = diagnoseTrace(t, pool.slice(0, 1), { tool: 'query', arguments: { query: 'q', limit: 1, types: ['meeting'], source_ids: ['source-a', 'source-b'] } });
+ expect(diag.code).toBe('target_beyond_limit');
+ expect(diag.fix?.argv).toEqual(['gbrain', 'query', 'q', '--limit', '7', '--types', '["meeting"]', '--source-ids', '["source-a","source-b"]']);
+ expect(diag.fix?.mcp?.arguments).toEqual({ query: 'q', limit: 7, types: ['meeting'], source_ids: ['source-a', 'source-b'] });
});
test('with --timings the diagnosis joins the timings document instead of replacing it', () => {