feat: [ENG-2852] brv-bridge v2 — tool-mode adaptation#13
Open
cuongdo-byterover wants to merge 3 commits into
Open
feat: [ENG-2852] brv-bridge v2 — tool-mode adaptation#13cuongdo-byterover wants to merge 3 commits into
cuongdo-byterover wants to merge 3 commits into
Conversation
Adapts the bridge to byterover-cli's tool-mode `brv` (M1-M4 ship). Drops
the legacy "byterover-side LLM authors HTML from raw text" flow and gains
a new persist surface that drives the curate session protocol internally.
After publish, downstream consumers (brv-openclaw-plugin v2 — ENG-2853 —
and any future host plugin) get a clean API that works against the
tool-mode CLI with no provider configured.
Breaking
- `BrvBridge.persist(text)` throws at runtime with a clear migration
message pointing at `persistHtml`. Method signature kept so typed
imports compile; the legacy text→HTML path required an LLM byterover
no longer has. Removed entirely in v3.0.
- `RecallResult.content` is now the concatenation of
`matchedDocs[].rendered_md` separated by `\n\n---\n\n`. The legacy
`data.result` / `data.content` top-level fields silently returned ""
under the new envelope; this rewires content from the new source.
- `BrvQueryData` shape mirrors `QueryToolModeResult` exactly:
`{status, matchedDocs[], metadata}`. tier/durationMs/topScore moved
from `data.*` to `data.metadata.*` — bridge reads them from the new
location.
- `RecallMatchedDoc` includes the canonical `format` and `rendered_md`
fields.
Added
- `BrvBridge.persistHtml({html, meta?, confirmOverwrite?})` — drives the
kickoff + continuation session protocol (2 subprocess calls). Returns
`{status: 'ok' | 'validation-failed', ...}`. Bridge does NOT loop on
validation failure — calling agent owns retries.
- `BrvBridge.queryEnvelope(query, options)` — raw `QueryToolModeResult`
passthrough for callers that want structured matched-docs (e.g. an
agent-facing `brv-query` tool handler). Throws on subprocess failure
rather than swallowing.
- `RecallOptions.limit` — passed through as `--limit <n>`.
- `CurateMeta` type — agent-supplied operation metadata
(type/impact/reason/summary/previousSummary/confidence) that drives
the HITL review pipeline. Mirrors byterover-cli's M4 curate-metadata
schema. Bridge plumbs it through to the continuation envelope; older
CLIs silently ignore it (the curate still succeeds, no HITL surfacing).
- `PersistHtmlInput / PersistHtmlOptions / PersistHtmlResult /
PersistHtmlError` public types.
- `QueryToolModeResult / QueryToolModeMatchedDoc / QueryToolModeMetadata`
re-exports — consumers can type tool handlers without re-declaring.
- `brvCurateKickoff` + `brvCurateContinue` subprocess helpers in
`process.ts`. Reuse the existing `runBrv` discipline (timeout, abort
signal, stdout cap, NDJSON parsing).
Changed
- `recall().content` joins `rendered_md` bodies with `\n\n---\n\n`.
Empty entries are filtered out before joining so a missing rendered_md
doesn't produce a spurious separator gap.
- `recall()` reads tier/durationMs/topScore from `data.metadata.*`.
- topScore only surfaced when `matchedDocs.length > 0` so cache hits
with stripped metadata don't report a misleading "0 best match".
Deprecated
- `PersistOptions / PersistResult` types — kept exported as @deprecated
for typed-import back-compat. Removed in v3.0.
- `brvCurate` subprocess helper in `process.ts` — bridge no longer calls
it. Removed in v3.0.
Tests
- test/bridge.test.ts rewritten for the new envelope. 30 new cases added
across: recall (content-from-rendered_md, no-matches branch, metadata
nesting drift guard, empty-entry filtering, limit passthrough);
queryEnvelope (raw passthrough, no-matches, throws on failure,
cwd/limit options); persistHtml (happy path 2-subprocess sequence,
sessionId plumbing, html+meta in continuation, confirmOverwrite,
validation-failed branch, kickoff failure, missing sessionId,
cwd/signal propagation, placeholder marker); persist (throws with
v2.0/persistHtml/<bv-topic> markers in message).
Verified
- npm run typecheck: clean
- npm test: 44/44 passing (was 14; +30)
- npm run build: produces dist/ artifacts
Out of scope (deferred per plan)
- `brv curate --html` direct CLI flag (we use the 2-call session
protocol). Cost: ~500ms extra per persist; session leak risk on
validation failures. Revisit if metrics show problems.
- Session-leak cleanup. Sessions left in `correct-html` state persist
on disk under `.brv/sessions/curate-<id>/` until a TTL cleanup ships
(separate work).
- Per-tool concurrency / semaphore — callers serialize their own
persistHtml calls (the OpenClaw agent does this).
- Direct transport client — bridge stays subprocess-based.
Plan: /Users/cuong/workspaces/vibing-zone/plans/05-plugin-adaptation/tasks/01-brv-bridge-v2.md
Linear: https://linear.app/byterover/issue/ENG-2852
Regenerated by the release pipeline; not part of the source tree. Stays on disk locally; future regens won't be staged.
cuongdo-byterover
changed the title
danhdoan
approved these changes
May 21, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Bridge adaptation for ByteRover CLI v2 tool-mode. Hosts (OpenClaw plugin, future plugin integrations) talk to
brvwithout a daemon-side LLM; the bridge speaks the new CLI surface end-to-end.Linear: ENG-2852
Motivation
Tool-mode
brvdoes not run an LLM in its daemon. The legacy bridge (persist()) assumedbrv curatewould call the daemon LLM to author HTML; in tool-mode it cannot. The bridge needs a new shape that matches the CLI's two-phase session protocol — agent authors HTML, bridge forwards a JSON envelope.Implementation
Types (
src/types.ts)QueryToolModeResultmirroring the CLI--format jsonshape:matchedDocs[],metadata{tier, durationMs, topScore, cacheHit, skippedSharedCount, totalFound},status.CurateMeta,PersistHtmlInput/Options/Result/Errortypes.BrvCurateKickoffData,BrvCurateContinueData.PersistResult/PersistOptionsmarked@deprecated.Bridge (
src/bridge.ts)recall()now concatenatesmatchedDocs[].rendered_mdwith\n\n---\n\nseparators; reads metadata fromdata.metadata.*(not flatdata.*).queryEnvelope()returns the full structured result for callers that need per-doc paths / scores.persistHtml()drives the 2-call session protocol withCURATE_KICKOFF_PLACEHOLDER("_brv-bridge curate placeholder_") for the kickoff intent string.persist()throws a clear migration error pointing callers atpersistHtml().Spawn helpers (
src/process.ts)brvQuerygains alimitparam.brvCurateKickoff/brvCurateContinuehelpers wrapping the two CLI invocations.brvCuratemarked@deprecated.Test plan
npm run buildcleannpm run lint0 errorsnpm test)brvonproj/byterover-tool-mode:recall()returns concatenated rendered_md + metadataqueryEnvelope()returns structured resultpersistHtml()two-phase round-trip writes a topic file under.brv/context-tree/Breaking changes
persist()now throws — callers must migrate topersistHtml()and pre-author the<bv-topic>HTML themselves. This matches the v2 contract that the daemon no longer owns LLM authoring. v1 hosts will need an update.PersistResult/PersistOptionsdeprecated; mark for removal in a follow-up minor.`