@byterover/byterover 1.0.0

package/README.md

@@ -0,0 +1,189 @@
+# @byterover/byterover
+
+ByteRover context engine plugin for [OpenClaw](https://github.com/openclaw/openclaw). Integrates the [brv CLI](https://www.byterover.dev) as a context engine that curates conversation knowledge and retrieves relevant context for each prompt — giving your AI agent persistent, queryable memory.
+
+## Table of contents
+
+- [What it does](#what-it-does)
+- [Prerequisites](#prerequisites)
+- [Quick start](#quick-start)
+- [Configuration](#configuration)
+- [How it works](#how-it-works)
+- [Development](#development)
+- [Project structure](#project-structure)
+- [License](#license)
+
+## What it does
+
+When you chat with an OpenClaw agent, the conversation is ephemeral — older messages get compacted or lost as the context window fills up. ByteRover changes that by:
+
+1. **Curating every turn** — after each conversation turn, the plugin feeds the new messages to `brv curate`, which extracts and stores facts, decisions, technical details, and preferences worth remembering
+2. **Querying on demand** — before each new prompt is sent to the LLM, the plugin runs `brv query` with the user's message to retrieve curated knowledge relevant to the current request
+3. **Injecting context** — retrieved knowledge is appended to the system prompt so the LLM has the right context without the user needing to repeat themselves
+
+The result: your agent remembers what matters, forgets what doesn't, and retrieves context that's actually relevant to what you're asking about right now.
+
+## Prerequisites
+
+- [OpenClaw](https://github.com/openclaw/openclaw) with plugin context engine support
+- Node.js 22+
+- [brv CLI](https://www.byterover.dev) installed and available on your `PATH` (or provide a custom path via config). The brv path depends on how you installed it:
+  - **curl**: the default path is `~/.brv-cli/bin/brv`
+  - **npm**: run `which brv` to find the path, then set it via `brvPath` in the plugin config
+
+## Quick start
+
+### 1. Install the plugin
+
+```bash
+openclaw plugins install @byterover/byterover
+```
+
+For local development, link your working copy instead:
+
+```bash
+openclaw plugins install --link /path/to/brv-openclaw-plugin
+```
+
+### 2. Configure the context engine slot
+
+```bash
+openclaw config set plugins.slots.contextEngine byterover
+```
+
+### 3. Set plugin options
+
+Point the plugin to your brv binary and project directory:
+
+```bash
+openclaw config set plugins.entries.byterover.config.brvPath /path/to/brv
+openclaw config set plugins.entries.byterover.config.cwd /path/to/your/project
+```
+
+### 4. Verify
+
+```bash
+openclaw plugins list
+```
+
+You should see `byterover` listed and enabled. Restart OpenClaw, then start a conversation — you'll see `[byterover] Plugin loaded` in the gateway logs.
+
+### 5. Uninstall (if needed)
+
+```bash
+openclaw plugins uninstall byterover
+openclaw config set plugins.slots.contextEngine ""
+```
+
+## Configuration
+
+ByteRover is configured through `plugins.entries.byterover.config` in your OpenClaw config file (`~/.openclaw/openclaw.json`):
+
+```json
+{
+  "plugins": {
+    "slots": {
+      "contextEngine": "byterover"
+    },
+    "entries": {
+      "byterover": {
+        "enabled": true,
+        "config": {
+          "brvPath": "/usr/local/bin/brv",
+          "cwd": "/path/to/your/project",
+          "queryTimeoutMs": 12000,
+          "curateTimeoutMs": 60000
+        }
+      }
+    }
+  }
+}
+```
+
+### Options
+
+
+| Option            | Type     | Default         | Description                                                                                                                                   |
+| ----------------- | -------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `brvPath`         | `string` | `"brv"`         | Path to the brv CLI binary. Defaults to resolving `brv` from `PATH`.                                                                          |
+| `cwd`             | `string` | `process.cwd()` | Working directory for brv commands. Must be a project with `.brv/` initialized.                                                               |
+| `queryTimeoutMs`  | `number` | `12000`         | Timeout in milliseconds for `brv query` calls. The effective assemble deadline is capped at 10,000 ms to stay within the agent ready timeout. |
+| `curateTimeoutMs` | `number` | `60000`         | Timeout in milliseconds for `brv curate` calls.                                                                                               |
+
+
+## How it works
+
+ByteRover hooks into three points in the OpenClaw context engine lifecycle:
+
+### `afterTurn` — curate conversation knowledge
+
+After each conversation turn completes, the plugin:
+
+1. Extracts new messages from the turn (skipping pre-prompt messages)
+2. Strips OpenClaw metadata (sender info, timestamps, tool results) to get clean text
+3. Serializes messages with sender attribution
+4. Sends the text to `brv curate --detach` for asynchronous knowledge extraction
+
+Curation runs in detached mode — the brv daemon queues the work and the CLI returns immediately, so it never blocks the conversation.
+
+### `assemble` — retrieve relevant context
+
+Before each prompt is sent to the LLM, the plugin:
+
+1. Takes the current user message (or falls back to scanning message history)
+2. Strips metadata and skips trivially short queries (< 5 chars)
+3. Runs `brv query` with a 10-second deadline
+4. Wraps the result in a `<byterover-context>` block and injects it as a system prompt addition
+
+If the query times out or fails, the conversation proceeds without context — it's always best-effort.
+
+### `compact` — delegated to runtime
+
+ByteRover does not own compaction. The plugin sets `ownsCompaction: false`, so OpenClaw's built-in sliding-window compaction handles context window management as usual.
+
+### `ingest` — no-op
+
+Ingestion is handled by `afterTurn` in batch (all new messages from the turn at once), so the per-message `ingest` hook is a no-op.
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Type check
+npx tsc --noEmit
+
+# Run tests
+npx vitest run --dir test
+
+# Link for local testing with OpenClaw
+openclaw plugins install --link .
+openclaw config set plugins.slots.contextEngine byterover
+```
+
+### Testing locally
+
+1. Initialize a brv project: `cd /your/project && brv init`
+2. Link the plugin and configure as shown in [Quick start](#quick-start)
+3. Restart OpenClaw
+4. Send a few messages — check gateway logs for:
+  - `[byterover] Plugin loaded` — plugin registered
+  - `afterTurn curating N new messages` — curation running
+  - `assemble injecting systemPromptAddition` — context being retrieved and injected
+
+## Project structure
+
+```
+index.ts                    # Plugin entry point and registration
+openclaw.plugin.json        # Plugin manifest (id, kind, config schema)
+src/
+  context-engine.ts         # ByteRoverContextEngine — implements ContextEngine
+  brv-process.ts            # brv CLI spawning (query, curate) with timeout/abort
+  message-utils.ts          # Metadata stripping and message text extraction
+  types.ts                  # Standalone type definitions (structurally compatible with openclaw/plugin-sdk)
+```
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1,28 @@
+import type { OpenClawPluginApi } from "./src/types.js";
+import type { BrvProcessConfig } from "./src/brv-process.js";
+import { ByteRoverContextEngine } from "./src/context-engine.js";
+
+const byteRoverPlugin = {
+  id: "byterover",
+  name: "ByteRover",
+  description: "ByteRover context engine — curates and queries conversation context via brv CLI",
+  kind: "context-engine" as const,
+  register(api: OpenClawPluginApi) {
+    const pluginConfig = (api.pluginConfig ?? {}) as Record<string, unknown>;
+
+    const brvConfig: BrvProcessConfig = {
+      brvPath: typeof pluginConfig.brvPath === "string" ? pluginConfig.brvPath : undefined,
+      cwd: typeof pluginConfig.cwd === "string" ? pluginConfig.cwd : undefined,
+      queryTimeoutMs:
+        typeof pluginConfig.queryTimeoutMs === "number" ? pluginConfig.queryTimeoutMs : undefined,
+      curateTimeoutMs:
+        typeof pluginConfig.curateTimeoutMs === "number" ? pluginConfig.curateTimeoutMs : undefined,
+    };
+
+    api.registerContextEngine("byterover", () => new ByteRoverContextEngine(brvConfig, api.logger));
+
+    api.logger.info("[byterover] Plugin loaded");
+  },
+};
+
+export default byteRoverPlugin;

package/openclaw.plugin.json

@@ -0,0 +1,28 @@
+{
+  "id": "byterover",
+  "kind": "context-engine",
+  "name": "ByteRover",
+  "description": "ByteRover context engine — curates and queries conversation context via brv CLI",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "brvPath": {
+        "type": "string",
+        "description": "Path to the brv CLI binary. Defaults to 'brv' (resolved from PATH)."
+      },
+      "queryTimeoutMs": {
+        "type": "number",
+        "description": "Timeout in milliseconds for brv query calls. Defaults to 12000. Note: effective assemble deadline is capped at 10000 ms to stay within the agent ready timeout."
+      },
+      "curateTimeoutMs": {
+        "type": "number",
+        "description": "Timeout in milliseconds for brv curate calls. Defaults to 60000."
+      },
+      "cwd": {
+        "type": "string",
+        "description": "Working directory for brv commands. Must be a project with .brv/ initialized."
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@byterover/byterover",
+  "version": "1.0.0",
+  "description": "ByteRover context engine plugin for OpenClaw — curates and queries conversation context via brv CLI",
+  "type": "module",
+  "main": "index.ts",
+  "license": "MIT",
+  "author": "ByteRover",
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "byterover",
+    "context-engine"
+  ],
+  "scripts": {
+    "test": "vitest run --dir test",
+    "typecheck": "tsc --noEmit"
+  },
+  "files": [
+    "index.ts",
+    "src/**/*.ts",
+    "openclaw.plugin.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "peerDependencies": {
+    "openclaw": "*"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}

package/src/brv-process.ts

@@ -0,0 +1,255 @@
+import { spawn } from "node:child_process";
+import type { PluginLogger } from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Types — brv CLI JSON output shapes
+// ---------------------------------------------------------------------------
+
+/** Wrapper envelope for all brv --format json responses. */
+export type BrvJsonResponse<T = unknown> = {
+  command: string;
+  success: boolean;
+  timestamp: string;
+  data: T;
+};
+
+export type BrvCurateResult = {
+  status: "completed" | "queued" | "error";
+  event?: string;
+  message?: string;
+  taskId?: string;
+  logId?: string;
+  changes?: {
+    created?: string[];
+    updated?: string[];
+  };
+  error?: string;
+};
+
+export type BrvQueryResult = {
+  status: "completed" | "error";
+  event?: string;
+  taskId?: string;
+  result?: string;
+  content?: string;
+  message?: string;
+  error?: string;
+};
+
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+
+export type BrvProcessConfig = {
+  /** Path to the brv binary. Defaults to "brv". */
+  brvPath?: string;
+  /** Working directory for brv commands. Defaults to process.cwd(). */
+  cwd?: string;
+  /** Timeout for query calls in ms. Defaults to 12_000. */
+  queryTimeoutMs?: number;
+  /** Timeout for curate calls in ms. Defaults to 60_000. */
+  curateTimeoutMs?: number;
+};
+
+// ---------------------------------------------------------------------------
+// Core spawning utility
+// ---------------------------------------------------------------------------
+
+function runBrv(params: {
+  brvPath: string;
+  args: string[];
+  cwd: string;
+  timeoutMs: number;
+  logger: PluginLogger;
+  signal?: AbortSignal;
+  maxOutputChars?: number;
+}): Promise<{ stdout: string; stderr: string }> {
+  const maxOutput = params.maxOutputChars ?? 512_000;
+
+  params.logger.debug?.(
+    `spawn: ${params.brvPath} ${params.args.join(" ")} (cwd=${params.cwd}, timeout=${params.timeoutMs}ms)`,
+  );
+
+  return new Promise((resolve, reject) => {
+    let settled = false;
+
+    function settle(
+      outcome: "resolve" | "reject",
+      value: { stdout: string; stderr: string } | Error,
+    ) {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (outcome === "resolve") {
+        resolve(value as { stdout: string; stderr: string });
+      } else {
+        reject(value);
+      }
+    }
+
+    const child = spawn(params.brvPath, params.args, {
+      cwd: params.cwd,
+      env: process.env,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    let stdout = "";
+    let stderr = "";
+
+    const timer = setTimeout(() => {
+      child.kill("SIGKILL");
+      settle(
+        "reject",
+        new Error(
+          `brv ${params.args[0]} timed out after ${params.timeoutMs}ms`,
+        ),
+      );
+    }, params.timeoutMs);
+
+    // External cancellation via AbortSignal (used by assemble deadline)
+    if (params.signal) {
+      if (params.signal.aborted) {
+        child.kill("SIGKILL");
+        settle("reject", new Error(`brv ${params.args[0]} aborted`));
+      } else {
+        params.signal.addEventListener(
+          "abort",
+          () => {
+            child.kill("SIGKILL");
+            settle("reject", new Error(`brv ${params.args[0]} aborted`));
+          },
+          { once: true },
+        );
+      }
+    }
+
+    child.stdout.on("data", (chunk: Buffer) => {
+      stdout += chunk.toString("utf8");
+      if (stdout.length > maxOutput) {
+        child.kill("SIGKILL");
+        settle(
+          "reject",
+          new Error(`brv ${params.args[0]} output exceeded ${maxOutput} chars`),
+        );
+      }
+    });
+
+    child.stderr.on("data", (chunk: Buffer) => {
+      stderr += chunk.toString("utf8");
+    });
+
+    child.on("error", (err) => {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+        settle(
+          "reject",
+          new Error(
+            `ByteRover CLI not found at "${params.brvPath}". ` +
+              `Install it (https://www.byterover.dev) or set brvPath in plugin config.`,
+          ),
+        );
+        return;
+      }
+      params.logger.warn(`spawn error: ${err.message}`);
+      settle("reject", err);
+    });
+
+    child.on("close", (code) => {
+      if (code === 0) {
+        params.logger.debug?.(
+          `exit 0 (stdout=${stdout.length} chars, stderr=${stderr.length} chars)`,
+        );
+        settle("resolve", { stdout, stderr });
+      } else {
+        const errMsg = `brv ${params.args[0]} failed (exit ${code}): ${stderr || stdout}`;
+        params.logger.warn(errMsg);
+        settle("reject", new Error(errMsg));
+      }
+    });
+  });
+}
+
+/**
+ * Parse the last complete JSON object from brv's newline-delimited JSON output.
+ * brv streams events as NDJSON; the final line with `status: "completed"` is the result.
+ */
+export function parseLastJsonLine<T>(stdout: string): BrvJsonResponse<T> {
+  const lines = stdout.trim().split("\n").filter(Boolean);
+  // Walk backwards to find the final completed result
+  for (let i = lines.length - 1; i >= 0; i--) {
+    try {
+      const parsed = JSON.parse(lines[i]) as BrvJsonResponse<T>;
+      return parsed;
+    } catch {
+      // Skip non-JSON lines (shouldn't happen with --format json, but be safe)
+    }
+  }
+  throw new Error("No valid JSON in brv output");
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Run `brv curate` with the given context text.
+ * Uses --detach for fire-and-forget (non-blocking) curation.
+ */
+export async function brvCurate(params: {
+  config: BrvProcessConfig;
+  logger: PluginLogger;
+  context: string;
+  files?: string[];
+  detach?: boolean;
+}): Promise<BrvJsonResponse<BrvCurateResult>> {
+  const brvPath = params.config.brvPath ?? "brv";
+  const cwd = params.config.cwd ?? process.cwd();
+  const timeoutMs = params.config.curateTimeoutMs ?? 60_000;
+
+  const args = ["curate", "--format", "json"];
+  if (params.detach) {
+    args.push("--detach");
+  }
+  if (params.files) {
+    for (const f of params.files) {
+      args.push("-f", f);
+    }
+  }
+  // "--" terminates flags so user text starting with "-" isn't parsed as a brv option
+  args.push("--", params.context);
+
+  const { stdout } = await runBrv({
+    brvPath,
+    args,
+    cwd,
+    timeoutMs,
+    logger: params.logger,
+  });
+  return parseLastJsonLine<BrvCurateResult>(stdout);
+}
+
+/**
+ * Run `brv query` and return the synthesized answer.
+ */
+export async function brvQuery(params: {
+  config: BrvProcessConfig;
+  logger: PluginLogger;
+  query: string;
+  signal?: AbortSignal;
+}): Promise<BrvJsonResponse<BrvQueryResult>> {
+  const brvPath = params.config.brvPath ?? "brv";
+  const cwd = params.config.cwd ?? process.cwd();
+  const timeoutMs = params.config.queryTimeoutMs ?? 12_000;
+
+  // "--" terminates flags so user text starting with "-" isn't parsed as a brv option
+  const args = ["query", "--format", "json", "--", params.query];
+
+  const { stdout } = await runBrv({
+    brvPath,
+    args,
+    cwd,
+    timeoutMs,
+    logger: params.logger,
+    signal: params.signal,
+  });
+  return parseLastJsonLine<BrvQueryResult>(stdout);
+}

package/src/context-engine.ts

@@ -0,0 +1,294 @@
+import type {
+  ContextEngine,
+  ContextEngineInfo,
+  AssembleResult,
+  CompactResult,
+  IngestResult,
+  PluginLogger,
+} from "./types.js";
+import { brvCurate, brvQuery, type BrvProcessConfig } from "./brv-process.js";
+import { stripUserMetadata, extractSenderInfo, stripAssistantTags } from "./message-utils.js";
+
+/**
+ * ByteRoverContextEngine integrates the brv CLI as an OpenClaw context engine.
+ *
+ * Lifecycle mapping:
+ *   - afterTurn  → `brv curate` (feed conversation turns for curation)
+ *   - assemble   → `brv query`  (retrieve curated knowledge as system prompt addition)
+ *   - ingest     → no-op (afterTurn handles batch ingestion)
+ *   - compact    → not owned (runtime handles compaction via legacy path)
+ */
+export class ByteRoverContextEngine implements ContextEngine {
+  readonly info: ContextEngineInfo = {
+    id: "byterover",
+    name: "ByteRover",
+    version: "0.1.0",
+    ownsCompaction: false,
+  };
+
+  private readonly config: BrvProcessConfig;
+  private readonly logger: PluginLogger;
+
+  constructor(config: BrvProcessConfig, logger: PluginLogger) {
+    this.config = config;
+    this.logger = logger;
+  }
+
+  // ---------------------------------------------------------------------------
+  // ingest — no-op (afterTurn handles it)
+  // ---------------------------------------------------------------------------
+
+  async ingest(_params: {
+    sessionId: string;
+    message: unknown;
+    isHeartbeat?: boolean;
+  }): Promise<IngestResult> {
+    return { ingested: false };
+  }
+
+  // ---------------------------------------------------------------------------
+  // afterTurn — feed the completed turn to brv curate
+  // ---------------------------------------------------------------------------
+
+  async afterTurn(params: {
+    sessionId: string;
+    sessionFile: string;
+    messages: unknown[];
+    prePromptMessageCount: number;
+    isHeartbeat?: boolean;
+  }): Promise<void> {
+    if (params.isHeartbeat) {
+      this.logger.debug?.("afterTurn skipped (heartbeat)");
+      return;
+    }
+
+    // Extract only the new messages from this turn
+    const newMessages = params.messages.slice(params.prePromptMessageCount);
+    if (newMessages.length === 0) {
+      this.logger.debug?.("afterTurn skipped (no new messages)");
+      return;
+    }
+
+    // Serialize messages into a text block for brv curate
+    const serialized = serializeMessagesForCurate(newMessages);
+    if (!serialized.trim()) {
+      this.logger.debug?.("afterTurn skipped (empty serialized context)");
+      return;
+    }
+
+    const context =
+      `The following is a conversation between a user and an AI assistant (OpenClaw).\n` +
+      `Curate only information with lasting value: facts, decisions, technical details, preferences, or notable outcomes.\n` +
+      `Skip trivial messages such as greetings, acknowledgments ("ok", "thanks", "sure", "got it"), one-word replies, anything with no substantive content, or automated session-start messages (e.g. "/new", "/reset" and their system-generated continuations).\n\n` +
+      `Conversation:\n${serialized}`;
+
+    this.logger.info(
+      `afterTurn curating ${newMessages.length} new messages (${context.length} chars)`,
+    );
+    try {
+      const result = await brvCurate({
+        config: this.config,
+        logger: this.logger,
+        context,
+        // --detach tells the brv daemon to queue curation work asynchronously.
+        // The CLI process itself exits immediately (~ms) after the daemon acknowledges
+        // the request, so the await here only waits for that quick handshake — not for
+        // the actual curation to complete. We still await to capture the JSON response
+        // (queued status, task ID) and to surface ENOENT / crash errors.
+        detach: true,
+      });
+      this.logger.debug?.(`afterTurn curate result: ${JSON.stringify(result.data?.status)}`);
+    } catch (err) {
+      // Best-effort: don't fail the turn if curation fails
+      this.logger.warn(`curate failed (best-effort): ${String(err)}`);
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // assemble — query brv for curated knowledge and inject as system prompt
+  // ---------------------------------------------------------------------------
+
+  async assemble(params: {
+    sessionId: string;
+    messages: unknown[];
+    tokenBudget?: number;
+    prompt?: string;
+  }): Promise<AssembleResult> {
+    // Use the incoming prompt (new upstream field) — this is the actual user
+    // message for this turn. Fall back to history scan for older runtimes.
+    const rawPrompt = params.prompt ?? null;
+    const query = rawPrompt
+      ? stripUserMetadata(rawPrompt).trim() || null
+      : extractLatestUserQuery(params.messages);
+    if (!query) {
+      this.logger.debug?.("assemble skipped brv query (no user message found)");
+      return {
+        messages: params.messages as AssembleResult["messages"],
+        estimatedTokens: 0,
+      };
+    }
+
+    // Skip trivially short queries (e.g. "ok", "hi", "yes") — not worth a brv spawn.
+    // Applied after metadata stripping so inflated raw prompts don't bypass this.
+    if (query.length < 5) {
+      this.logger.debug?.(`assemble skipped brv query (query too short: "${query}")`);
+      return {
+        messages: params.messages as AssembleResult["messages"],
+        estimatedTokens: 0,
+      };
+    }
+
+    // Abort-based deadline so we never exceed the agent ready timeout (15s).
+    // Default 10s — leaves headroom for the runtime's own overhead.
+    // The signal is passed to brvQuery → runBrv, which kills the child process on abort.
+    const assembleTimeout = this.config.queryTimeoutMs
+      ? Math.min(this.config.queryTimeoutMs, 10_000)
+      : 10_000;
+
+    this.logger.debug?.(
+      `assemble querying brv: "${query.slice(0, 100)}${query.length > 100 ? "..." : ""}" (timeout=${assembleTimeout}ms)`,
+    );
+    let systemPromptAddition: string | undefined;
+    const ac = new AbortController();
+    const deadline = setTimeout(() => ac.abort(), assembleTimeout);
+    try {
+      const result = await brvQuery({
+        config: this.config,
+        logger: this.logger,
+        query,
+        signal: ac.signal,
+      });
+
+      const answer = result.data?.result ?? result.data?.content;
+      if (answer && answer.trim()) {
+        systemPromptAddition =
+          `<byterover-context>\n` +
+          `The following curated knowledge is from ByteRover context engine:\n\n` +
+          `${answer.trim()}\n` +
+          `</byterover-context>`;
+        this.logger.info(
+          `assemble injecting systemPromptAddition (${systemPromptAddition.length} chars)`,
+        );
+      } else {
+        this.logger.debug?.("assemble brv query returned empty result");
+      }
+    } catch (err) {
+      // Don't fail the prompt if brv query fails or times out
+      const msg = String(err);
+      if (msg.includes("aborted")) {
+        this.logger.warn(
+          `assemble brv query timed out after ${assembleTimeout}ms — proceeding without context`,
+        );
+      } else {
+        this.logger.warn(`query failed (best-effort): ${msg}`);
+      }
+    } finally {
+      clearTimeout(deadline);
+    }
+
+    return {
+      messages: params.messages as AssembleResult["messages"],
+      estimatedTokens: 0, // Caller handles estimation
+      systemPromptAddition,
+    };
+  }
+
+  // ---------------------------------------------------------------------------
+  // compact — we don't own compaction; return not-compacted
+  // ---------------------------------------------------------------------------
+
+  async compact(_params: {
+    sessionId: string;
+    sessionFile: string;
+    tokenBudget?: number;
+    force?: boolean;
+  }): Promise<CompactResult> {
+    return {
+      ok: true,
+      compacted: false,
+      reason: "ByteRover does not own compaction; delegating to runtime.",
+    };
+  }
+
+  // ---------------------------------------------------------------------------
+  // dispose — no persistent resources to clean up
+  // ---------------------------------------------------------------------------
+
+  async dispose(): Promise<void> {
+    this.logger.debug?.("dispose called");
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Serialize agent messages into a human-readable text block for brv curate.
+ *
+ * - User messages: strip metadata noise, attribute with sender name + timestamp
+ * - Assistant messages: strip <final>/<think> tags
+ * - toolResult messages: skipped (internal implementation details)
+ */
+export function serializeMessagesForCurate(messages: unknown[]): string {
+  const lines: string[] = [];
+  for (const msg of messages) {
+    const m = msg as { role?: string; content?: unknown };
+    if (!m.role) continue;
+
+    // Skip tool results — internal details, not useful for curation
+    if (m.role === "toolResult") continue;
+
+    let text = extractTextContent(m.content);
+    if (!text.trim()) continue;
+
+    if (m.role === "user") {
+      // Extract sender info before stripping metadata
+      const sender = extractSenderInfo(text);
+      text = stripUserMetadata(text);
+      if (!text.trim()) continue;
+
+      // Build clean attribution header
+      const parts = [sender?.name, sender?.timestamp].filter(Boolean);
+      const label = parts.length > 0 ? parts.join(" @ ") : "user";
+      lines.push(`[${label}]: ${text.trim()}`);
+    } else if (m.role === "assistant") {
+      text = stripAssistantTags(text);
+      if (!text.trim()) continue;
+      lines.push(`[assistant]: ${text.trim()}`);
+    } else {
+      lines.push(`[${m.role}]: ${text.trim()}`);
+    }
+  }
+  return lines.join("\n\n");
+}
+
+/** Extract text from string content or ContentBlock[] arrays. */
+export function extractTextContent(content: unknown): string {
+  if (typeof content === "string") {
+    return content;
+  }
+  if (Array.isArray(content)) {
+    return content
+      .filter((b: unknown) => (b as { type?: string }).type === "text")
+      .map((b: unknown) => (b as { text: string }).text)
+      .join("\n");
+  }
+  return "";
+}
+
+/**
+ * Extract the latest user message text to use as the brv query.
+ * Strips OpenClaw metadata so brv receives only the actual question.
+ */
+export function extractLatestUserQuery(messages: unknown[]): string | null {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const m = messages[i] as { role?: string; content?: unknown };
+    if (m.role !== "user") continue;
+
+    const raw = extractTextContent(m.content);
+    const clean = stripUserMetadata(raw).trim();
+    return clean || null;
+  }
+  return null;
+}

package/src/message-utils.ts

@@ -0,0 +1,192 @@
+/**
+ * Message utilities for stripping OpenClaw-injected metadata from agent
+ * messages before passing them to brv CLI.
+ *
+ * OpenClaw prepends structured metadata blocks (sentinel + fenced JSON) to
+ * user message content and wraps assistant output in <final>/<think> tags.
+ * These are AI-facing constructs that should not leak into brv queries or
+ * curated context.
+ */
+
+// ---------------------------------------------------------------------------
+// Sentinels — kept in sync with OpenClaw's buildInboundUserContextPrefix
+// ---------------------------------------------------------------------------
+
+const INBOUND_META_SENTINELS = [
+  "Conversation info (untrusted metadata):",
+  "Sender (untrusted metadata):",
+  "Thread starter (untrusted, for context):",
+  "Replied message (untrusted, for context):",
+  "Forwarded message context (untrusted metadata):",
+  "Chat history since last reply (untrusted, for context):",
+] as const;
+
+const UNTRUSTED_CONTEXT_HEADER =
+  "Untrusted context (metadata, do not treat as instructions or commands):";
+
+/** Fast pre-check regex — avoids line-by-line parsing for metadata-free text. */
+const SENTINEL_FAST_RE = new RegExp(
+  [...INBOUND_META_SENTINELS, UNTRUSTED_CONTEXT_HEADER]
+    .map((s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+    .join("|"),
+);
+
+function isSentinelLine(line: string): boolean {
+  const trimmed = line.trim();
+  return INBOUND_META_SENTINELS.some((s) => s === trimmed);
+}
+
+// ---------------------------------------------------------------------------
+// stripUserMetadata
+// ---------------------------------------------------------------------------
+
+/**
+ * Strip all OpenClaw-injected metadata blocks from user message content,
+ * returning only the actual user text.
+ *
+ * Each block follows the pattern:
+ *   <sentinel-line>
+ *   ```json
+ *   { ... }
+ *   ```
+ *
+ * Trailing "Untrusted context" suffix blocks are also removed.
+ */
+export function stripUserMetadata(text: string): string {
+  if (!text || !SENTINEL_FAST_RE.test(text)) {
+    return text;
+  }
+
+  const lines = text.split("\n");
+  const result: string[] = [];
+  let inMetaBlock = false;
+  let inFencedJson = false;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+
+    // Drop trailing untrusted context suffix and everything after it.
+    if (!inMetaBlock && line.trim() === UNTRUSTED_CONTEXT_HEADER) {
+      break;
+    }
+
+    // Detect start of a metadata block.
+    if (!inMetaBlock && isSentinelLine(line)) {
+      const next = lines[i + 1];
+      if (next?.trim() === "```json") {
+        inMetaBlock = true;
+        inFencedJson = false;
+        continue;
+      }
+      // Sentinel without a following fence — keep it as content.
+      result.push(line);
+      continue;
+    }
+
+    if (inMetaBlock) {
+      if (!inFencedJson && line.trim() === "```json") {
+        inFencedJson = true;
+        continue;
+      }
+      if (inFencedJson) {
+        if (line.trim() === "```") {
+          inMetaBlock = false;
+          inFencedJson = false;
+        }
+        continue;
+      }
+      // Blank lines between consecutive blocks — drop.
+      if (line.trim() === "") {
+        continue;
+      }
+      // Non-blank line outside a fence — treat as user content.
+      inMetaBlock = false;
+    }
+
+    result.push(line);
+  }
+
+  return result.join("\n").replace(/^\n+/, "").replace(/\n+$/, "");
+}
+
+// ---------------------------------------------------------------------------
+// extractSenderInfo
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse the "Conversation info" and "Sender" metadata blocks from user
+ * message content to extract sender name and timestamp for clean curate
+ * attribution.
+ */
+export function extractSenderInfo(text: string): { name?: string; timestamp?: string } | null {
+  if (!text || !SENTINEL_FAST_RE.test(text)) {
+    return null;
+  }
+
+  const lines = text.split("\n");
+  const conversationInfo = parseMetaBlock(lines, "Conversation info (untrusted metadata):");
+  const senderInfo = parseMetaBlock(lines, "Sender (untrusted metadata):");
+
+  const name = firstNonEmpty(
+    senderInfo?.label,
+    senderInfo?.name,
+    senderInfo?.username,
+    conversationInfo?.sender,
+  );
+  const timestamp = firstNonEmpty(conversationInfo?.timestamp);
+
+  if (!name && !timestamp) {
+    return null;
+  }
+  return { name: name ?? undefined, timestamp: timestamp ?? undefined };
+}
+
+/**
+ * Parse a single sentinel + fenced-JSON metadata block and return the parsed
+ * JSON object, or null if not found / malformed.
+ */
+function parseMetaBlock(lines: string[], sentinel: string): Record<string, unknown> | null {
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i]?.trim() !== sentinel) continue;
+    if (lines[i + 1]?.trim() !== "```json") return null;
+
+    let end = i + 2;
+    while (end < lines.length && lines[end]?.trim() !== "```") {
+      end++;
+    }
+    if (end >= lines.length) return null;
+
+    const jsonText = lines
+      .slice(i + 2, end)
+      .join("\n")
+      .trim();
+    if (!jsonText) return null;
+
+    try {
+      const parsed = JSON.parse(jsonText);
+      return parsed && typeof parsed === "object" ? (parsed as Record<string, unknown>) : null;
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+function firstNonEmpty(...values: unknown[]): string | null {
+  for (const v of values) {
+    if (typeof v === "string" && v.trim()) return v.trim();
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// stripAssistantTags
+// ---------------------------------------------------------------------------
+
+/** Remove `<final>`, `</final>`, `<think>`, `</think>` tags from text. */
+const AGENT_TAG_RE = /<\s*\/?\s*(?:final|think)\s*>/gi;
+
+export function stripAssistantTags(text: string): string {
+  if (!text) return text;
+  return text.replace(AGENT_TAG_RE, "");
+}

package/src/types.ts

@@ -0,0 +1,160 @@
+/**
+ * Standalone type definitions mirroring openclaw/plugin-sdk.
+ *
+ * These are structurally compatible with the types exported by the OpenClaw
+ * plugin SDK. When the plugin runs inside OpenClaw, TypeScript's structural
+ * typing ensures our implementation satisfies the real interfaces.
+ *
+ * Source of truth: openclaw/src/context-engine/types.ts
+ *                  openclaw/src/plugins/types.ts
+ */
+
+// ---------------------------------------------------------------------------
+// PluginLogger — subset of openclaw/src/plugins/types.ts → PluginLogger
+// ---------------------------------------------------------------------------
+
+export type PluginLogger = {
+  debug?: (msg: string) => void;
+  info: (msg: string) => void;
+  warn: (msg: string) => void;
+  error: (msg: string) => void;
+};
+
+// ---------------------------------------------------------------------------
+// Context engine types — openclaw/src/context-engine/types.ts
+// ---------------------------------------------------------------------------
+
+export type ContextEngineInfo = {
+  id: string;
+  name: string;
+  version?: string;
+  ownsCompaction: boolean;
+};
+
+export type AssembleResult = {
+  messages: unknown[];
+  estimatedTokens: number;
+  systemPromptAddition?: string;
+};
+
+export type CompactResult = {
+  ok: boolean;
+  compacted: boolean;
+  reason?: string;
+  result?: {
+    tokensBefore: number;
+    tokensAfter: number;
+    details?: Record<string, unknown>;
+  };
+};
+
+export type IngestResult = {
+  ingested: boolean;
+};
+
+export type BootstrapResult = {
+  bootstrapped: boolean;
+  importedMessages?: number;
+  reason?: string;
+};
+
+export type IngestBatchResult = {
+  ingestedCount: number;
+};
+
+/**
+ * ContextEngine — the plugin-sdk interface a context engine must satisfy.
+ *
+ * Required methods: info, ingest, assemble, compact.
+ * Optional methods: bootstrap, ingestBatch, afterTurn, prepareSubagentSpawn,
+ *                   onSubagentEnded, dispose.
+ *
+ * ByteRover implements: ingest (no-op), afterTurn, assemble, compact, dispose.
+ */
+export interface ContextEngine {
+  readonly info: ContextEngineInfo;
+
+  bootstrap?(params: {
+    sessionId: string;
+    sessionFile: string;
+  }): Promise<BootstrapResult>;
+
+  ingest(params: {
+    sessionId: string;
+    sessionKey?: string;
+    message: unknown;
+    isHeartbeat?: boolean;
+  }): Promise<IngestResult>;
+
+  ingestBatch?(params: {
+    sessionId: string;
+    sessionKey?: string;
+    messages: unknown[];
+    isHeartbeat?: boolean;
+  }): Promise<IngestBatchResult>;
+
+  afterTurn?(params: {
+    sessionId: string;
+    sessionFile: string;
+    messages: unknown[];
+    prePromptMessageCount: number;
+    autoCompactionSummary?: string;
+    isHeartbeat?: boolean;
+    tokenBudget?: number;
+    runtimeContext?: Record<string, unknown>;
+  }): Promise<void>;
+
+  assemble(params: {
+    sessionId: string;
+    messages: unknown[];
+    tokenBudget?: number;
+    prompt?: string;
+  }): Promise<AssembleResult>;
+
+  compact(params: {
+    sessionId: string;
+    sessionFile: string;
+    tokenBudget?: number;
+    currentTokenCount?: number;
+    compactionTarget?: "budget" | "threshold";
+    force?: boolean;
+  }): Promise<CompactResult>;
+
+  prepareSubagentSpawn?(params: {
+    parentSessionKey: string;
+    childSessionKey: string;
+    ttlMs?: number;
+  }): Promise<unknown>;
+
+  onSubagentEnded?(params: {
+    childSessionKey: string;
+    reason: string;
+  }): Promise<void>;
+
+  dispose?(): Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// Plugin API — openclaw/src/plugins/types.ts → OpenClawPluginApi
+// ---------------------------------------------------------------------------
+
+export type OpenClawPluginApi = {
+  /** Validated runtime config (agents, session, etc.). */
+  config: unknown;
+  /** Raw plugin config from plugins.entries.<id>.config in openclaw.json. */
+  pluginConfig?: Record<string, unknown>;
+  /** Scoped logger for this plugin. */
+  logger: PluginLogger;
+  /** OpenClaw runtime surfaces (config loader, channel, subagent, etc.). */
+  runtime: unknown;
+  /** Register a context engine factory under a slot name. */
+  registerContextEngine(
+    id: string,
+    factory: () => ContextEngine | Promise<ContextEngine>,
+  ): void;
+  /** Register an agent-facing tool. */
+  registerTool(
+    factory: (ctx: { sessionKey: string }) => unknown,
+    opts: { name: string },
+  ): void;
+};