Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

docs: evidence-delivery and key-files match the shipped budget and fence behavior (GBRA-156 /ship Steps 13-14.5)

garrytan609a0d9bcfb7
diff --git a/docs/architecture/key-files/core-search-evidence.md b/docs/architecture/key-files/core-search-evidence.md
index e73900529f..349870839e 100644
--- a/docs/architecture/key-files/core-search-evidence.md
+++ b/docs/architecture/key-files/core-search-evidence.md
@@ -5,4 +5,4 @@ Current behavior and load-bearing invariants; history belongs in Git and CHANGEL
- `src/core/search/evidence-date.ts` — C1 dated evidence blocks: the fixed header grammar (`[observed YYYY-MM-DD|unknown]` for page blocks; `[observed unknown; valid FROM to UNTIL]` for `recall` facts), `pageObservationDate` (effective-date precedence with `event_date` removed and no row-timestamp fallback; mirrors #6020's `resolveObservationDate`, the seam to swap once it lands), `formatBrainDay` from `effective-date.ts` (midnight UTC renders as written, other instants in `brain.timezone`; the one function think's `<page date>` also renders through, while the header's `observed` stays when the text was said, never the content date), `loadPageDateHeaders` (one `pages` read per delivery; only the derived day leaves it) and `evidenceDateHeaderEnabled` (`search.evidence_date_header`, default off). Tests: `test/evidence-date-header.test.ts`.
- `src/core/search/evidence-tail-trim.ts` — the protected tail trim (`search.evidence_tail_trim`, default off, GBRA-156). `resolveEvidencePlan` sets `EvidencePlan.tailTrim` only for `unit: auto` with the key on; `deliverEvidence` calls `trimEvidenceTail(results, opts.query)` on the rank-order delivered rows after redaction and before the token totals, and only when `DeliverOptions.query` is set (`search`/`query` pass `p.query`; the library `assembleEvidenceForHits` passes `input.query` and frozen hits may carry `score`; the `assemble_evidence` op passes neither, so the trim never runs there). Rows past `TAIL_TRIM_PROTECTED` = 3 that are whole-conversation blocks (`delivered.reason` `conversation_type`/`conversation_slug`) and score under `TAIL_TRIM_SCORE_FRACTION` = 0.5 of rank one are dropped, unless their `chunk_text` holds at least `TAIL_TRIM_TERM_FRACTION` = 0.8 of rank one's share of the query's terms (`queryTerms`: letter/digit runs, stopwords and single characters dropped, cut to six characters). Rank one's score must be a positive finite number and every row's finite, or nothing changes. `delivery.tail_trim` is `{ dropped, kept_by_query_terms }`; `dropped_reasons.tail_trim` counts drops. Pinned by `test/evidence-tail-trim.test.ts` (the knowledge-update regression case).
-- `src/core/search/transcript-quote.ts` — quotes conversation rows in `search`, `query` and `assemble_evidence` results (#7600). The signal is the stored page type: a row whose `type` is `conversation` (what `transcripts/render.ts` writes) and that is not a fact row; nothing reads the text to decide, so other pages come back byte-for-byte unchanged. `searchOutput` (`ops/search.ts`) runs `neutralizeTranscriptRows` before the snippet and evidence caps and `fenceTranscriptRows` after them, on copies, after ranking and evidence delivery; `assembleEvidenceForHits` (`evidence-delivery.ts`, so the `assemble_evidence` op and gbrain-evals) does the same around `capEvidenceToBudget`. That cap counts a conversation row as delivered, inside its fence (`deliveredQuoteText`, its `quote` flag; deliverEvidence's own cap, which recall uses, counts the text as returned), so an explicit token budget still holds, `snippet_chars` included; a row it cuts is shortened until the fenced text fits, and other rows are cut exactly as before. The neutralizer replaces each tool-call block with `[tool call: <name>, arguments omitted]` (`[tool calls: a, b, …]` for several): an object typed `tool_use`, `server_tool_use`, `mcp_tool_use`, `function_call`, `custom_tool_call`, `tool_call` or `toolCall` (the enclosing object, found by walking back over candidate `{` with a string-aware scan), the value of a `tool_calls` array or `function_call` object (the message object and its `content` stay), and an XML-style `function_calls`, `invoke` or `tool_use` element with its `parameter` children, namespace prefix optional (the name from `invoke name="…"` or a `<name>` child; result elements are never matched, and a tag counts as markup only when it ends its line or the text, runs into the next tag, or is an `invoke` with a name; blocks separated only by whitespace merge). The XML pass runs before the JSON pass. Text between evidence omission lines is read separately; a block cut by the end of the text is replaced to the end or the next message anchor line (an open-ended block never swallows a later message), one whose `{` lies before the text from the text start (or the last message anchor) when the type is followed by `,` or `}`, and prose that only names the shape is left alone. An XML block whose close lies past the text runs to the end or the next message anchor line; a closing tag with no opener (or a `parameter` opener outside a call) starts at the text start or the last message anchor. A trailing evidence cut marker and a leading `[observed …]` date header stay outside any block. Scanning is linear: anchors are indexed once, and past a per-text work budget the rest of a message is summarized (fails closed). Names outside `[A-Za-z0-9_.:/-]{1,64}` are dropped. The fence is a marker line naming the slug (`[`, `]`, `;` and line breaks shown as `?`), then a code fence one backtick longer than the longest run in the text; the row gets `quoted: "transcript"` (kept in lean rows). `rowPreview` is the CLI human line: `[quoted transcript]` and the start of the fenced text. Stored pages, chunks, ranking and scores are unchanged; delivered `match_spans` are remapped to the returned text, and `tokens`, `tokens_delivered` and `budget_used` count the fenced text (`fenceTranscriptRows` with a recount). Tests: `test/search/transcript-quote.test.ts`, `test/search-transcript-quote.test.ts` (ChatGPT export through the importer, with a JSON and an XML call; remote MCP `search`/`query`/`assemble_evidence` and CLI human/`--json`, both engines), `test/search-transcript-quote-budget.test.ts` (budget, spans and snippet cap through the ops).
+- `src/core/search/transcript-quote.ts` — quotes conversation rows in `search`, `query` and `assemble_evidence` results (#7600). The signal is the stored page type: a row whose `type` is `conversation` (what `transcripts/render.ts` writes) and that is not a fact row; nothing reads the text to decide, so other pages come back byte-for-byte unchanged. `searchOutput` (`ops/search.ts`) runs `neutralizeTranscriptRows` before the snippet and evidence caps and `fenceTranscriptRows` after them, on copies, after ranking and evidence delivery; `assembleEvidenceForHits` (`evidence-delivery.ts`, so the `assemble_evidence` op and gbrain-evals) does the same around `capEvidenceToBudget`. That cap counts a conversation row as delivered, inside its fence (`deliveredQuoteText`, its `quote` flag; deliverEvidence's own cap, which recall uses, counts the text as returned), so an explicit `auto` token budget still holds, `snippet_chars` included (a rank-one row is kept even when its fence alone exceeds a very small budget); a row it cuts is shortened until the fenced text fits, and other rows are cut exactly as before. The neutralizer replaces each tool-call block with `[tool call: <name>, arguments omitted]` (`[tool calls: a, b, …]` for several): an object typed `tool_use`, `server_tool_use`, `mcp_tool_use`, `function_call`, `custom_tool_call`, `tool_call` or `toolCall` (the enclosing object, found by walking back over candidate `{` with a string-aware scan), the value of a `tool_calls` array or `function_call` object (the message object and its `content` stay), and an XML-style `function_calls`, `invoke` or `tool_use` element with its `parameter` children, namespace prefix optional (the name from `invoke name="…"` or a `<name>` child; result elements are never matched, and a tag counts as markup only when it ends its line or the text, runs into the next tag, or is an `invoke` with a name; blocks separated only by whitespace merge). The XML pass runs before the JSON pass. Text between evidence omission lines is read separately; a block cut by the end of the text is replaced to the end or the next message anchor line (an open-ended block never swallows a later message), one whose `{` lies before the text from the text start (or the last message anchor) when the type is followed by `,` or `}`, and prose that only names the shape is left alone. An XML block whose close lies past the text runs to the end or the next message anchor line; a closing tag with no opener (or a `parameter` opener outside a call) starts at the text start or the last message anchor. A trailing evidence cut marker and a leading `[observed …]` date header stay outside any block. Scanning is linear: anchors are indexed once, and past a per-text work budget the rest of a message is summarized (fails closed). Names outside `[A-Za-z0-9_.:/-]{1,64}` are dropped. The fence is a marker line naming the slug (`[`, `]`, `;` and line breaks shown as `?`), then a code fence of at least three backticks, one longer than the longest run in the text; the row gets `quoted: "transcript"` (kept in lean rows). `rowPreview` is the CLI human line: `[quoted transcript]` and the start of the fenced text. Stored pages, chunks, ranking and scores are unchanged; delivered `match_spans` are remapped to the returned text, and `tokens`, `tokens_delivered` and `budget_used` count the fenced text (`fenceTranscriptRows` with a recount). Tests: `test/search/transcript-quote.test.ts`, `test/search-transcript-quote.test.ts` (ChatGPT export through the importer, with a JSON and an XML call; remote MCP `search`/`query`/`assemble_evidence` and CLI human/`--json`, both engines), `test/search-transcript-quote-budget.test.ts` (budget, spans and snippet cap through the ops).
diff --git a/docs/evidence-delivery.md b/docs/evidence-delivery.md
index 25bafab416..2d91384181 100644
--- a/docs/evidence-delivery.md
+++ b/docs/evidence-delivery.md
@@ -305,7 +305,9 @@ When the caller passes a budget (`token_budget` on `query`, `search` and
`assemble_evidence`, `budget_tokens` on `recall`) and the unit is `auto`, the
budget is a hard cap on the delivered evidence: the recount of every result's
title plus `chunk_text` (the evidence, its omission lines, cut markers and
-snippet markers) never exceeds it. JSON fields outside those two (`delivered`,
+snippet markers) never exceeds it, except that a quoted conversation row at
+rank one is kept when its quote fence alone exceeds a very small budget (see
+[Response shape](#response-shape-additive)). JSON fields outside those two (`delivered`,
spans, scores, the `delivery` meta) are not counted. The four operations share
one rule:
@@ -414,7 +416,10 @@ one-line summary, then a marker line and a code fence wrap the text. Its
covers the summary), and its `tokens`, the meta `tokens_delivered` and
`budget_used` and `evidenceFingerprint` count or hash the fenced text. An
explicit `snippet_chars` caps the text inside the fence, so the row can run
-longer than the cap by the marker and fence lines.
+longer than the cap by the marker and fence lines. Under `auto` an explicit
+budget pays for the fence, except that a rank-one row is kept when the fence
+alone exceeds a very small budget; budgets under other units do not count it.
+With `date_header`, the header is the first line inside the fence.
One result is returned per expanded page, at the page's best rank. `chunk_id`,
`chunk_index`, `score` and the other ranking fields stay those of the page's