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.mdindex 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.tsindex 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.tsindex 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', () => {