opencode-semantic-search 0.1.0

package/src/logger.ts

@@ -0,0 +1,121 @@
+import { appendFileSync } from "fs";
+
+export type LogLevel = "debug" | "info" | "warn" | "error";
+
+interface AppLogClient {
+  app?: {
+    log?: (entry: {
+      body: {
+        service: string;
+        level: LogLevel;
+        message: string;
+        extra?: Record<string, unknown>;
+      };
+    }) => Promise<unknown>;
+  };
+}
+
+interface LoggerOptions {
+  enabled: boolean;
+  level: LogLevel;
+  verbosePaths?: string[];
+  client?: AppLogClient;
+  /** Absolute path to a local log file. When set, all log entries are appended as newline-delimited JSON (in addition to any other sink). Useful for local testing without the OpenCode host. */
+  logFile?: string;
+}
+
+interface LogPayload {
+  message: string;
+  extra?: Record<string, unknown>;
+}
+
+const levelWeight: Record<LogLevel, number> = {
+  debug: 10,
+  info: 20,
+  warn: 30,
+  error: 40
+};
+
+function normalizeError(error: unknown): { name?: string; message: string; stack?: string } {
+  if (error instanceof Error) {
+    return {
+      name: error.name,
+      message: error.message,
+      stack: error.stack
+    };
+  }
+  if (typeof error === "string") return { message: error };
+  return { message: "Unknown error", stack: JSON.stringify(error) };
+}
+
+function pickPath(extra?: Record<string, unknown>): string | undefined {
+  const candidate = extra?.filePath ?? extra?.path;
+  return typeof candidate === "string" ? candidate : undefined;
+}
+
+export interface Logger {
+  debug(scope: string, payload: LogPayload): Promise<void>;
+  info(scope: string, payload: LogPayload): Promise<void>;
+  warn(scope: string, payload: LogPayload): Promise<void>;
+  error(scope: string, payload: LogPayload & { error?: unknown }): Promise<void>;
+}
+
+export function createLogger(options: LoggerOptions): Logger {
+  const verbosePaths = options.verbosePaths ?? [];
+  const appRef = options.client?.app;
+  const emitAppLog = appRef?.log?.bind(appRef);
+  const logFile = options.logFile ?? null;
+
+  function shouldLog(level: LogLevel, extra?: Record<string, unknown>): boolean {
+    if (!options.enabled) return false;
+    if (levelWeight[level] < levelWeight[options.level]) return false;
+    if (level !== "debug" || verbosePaths.length === 0) return true;
+    const path = pickPath(extra);
+    if (!path) return true;
+    return verbosePaths.some((prefix) => path.startsWith(prefix));
+  }
+
+  async function emit(level: LogLevel, scope: string, payload: LogPayload & { error?: unknown }): Promise<void> {
+    const errorDetails = payload.error ? normalizeError(payload.error) : undefined;
+    const extra = {
+      scope,
+      ...(payload.extra ?? {}),
+      ...(errorDetails ? { error: errorDetails } : {})
+    };
+
+    if (!shouldLog(level, extra)) return;
+
+    const message = `[${scope}] ${payload.message}`;
+    const entry = { ts: new Date().toISOString(), service: "opencode-semantic-search", level, message, extra };
+
+    if (logFile) {
+      try {
+        appendFileSync(logFile, JSON.stringify(entry) + "\n");
+      } catch {
+        // Ignore file-write errors so a bad path never crashes the plugin.
+      }
+    }
+
+    if (emitAppLog) {
+      await emitAppLog({ body: { service: entry.service, level, message, extra } });
+      return;
+    }
+
+    const sink = level === "error" ? console.error : level === "warn" ? console.warn : console.log;
+    sink(JSON.stringify(entry));
+  }
+
+  return {
+    debug: (scope, payload) => emit("debug", scope, payload),
+    info: (scope, payload) => emit("info", scope, payload),
+    warn: (scope, payload) => emit("warn", scope, payload),
+    error: (scope, payload) => emit("error", scope, payload)
+  };
+}
+
+export const noopLogger: Logger = {
+  async debug() {},
+  async info() {},
+  async warn() {},
+  async error() {}
+};

package/src/runtime.ts

@@ -0,0 +1,111 @@
+import crypto from "node:crypto";
+import path from "node:path";
+import type { OpencodeClient } from "@opencode-ai/sdk";
+import type { PluginConfig } from "./config";
+import { createEmbedder, type Embedder } from "./embedder/interface";
+import type { Logger } from "./logger";
+import { SemanticStore } from "./store/sqlite";
+import { notifyIndexingProgressToast, resetIndexingToastThrottle } from "./tui_toast";
+
+export type IndexingPhase = "idle" | "scanning" | "indexing" | "gc";
+
+export interface IndexingProgressState {
+  phase: IndexingPhase;
+  current: number;
+  total: number;
+  startedAt: number;
+  label?: string;
+  source?: "background" | "reindex";
+  /** Paths that failed during the last indexing run (when reported on idle). */
+  failedFiles?: string[];
+}
+
+export interface DeltaProgressPayload {
+  phase: IndexingPhase;
+  current: number;
+  total: number;
+  label?: string;
+  failedFiles?: string[];
+}
+
+export interface RuntimeContext {
+  worktree: string;
+  dbPath: string;
+  config: PluginConfig;
+  store: SemanticStore;
+  embedder: Embedder;
+  logger: Logger;
+  indexingLock: boolean;
+  indexingProgress: IndexingProgressState;
+  /** Set by the OpenCode plugin host — enables `src/tui_toast.ts` showTuiToast. */
+  opencodeClient?: OpencodeClient;
+  /** OpenCode project `directory` — used as TUI API `query.directory` when showing toasts. */
+  projectDirectory?: string;
+  /** Throttle state for `notifyIndexingProgressToast` in `src/tui_toast.ts`. */
+  indexingToastLastMs?: number;
+  indexingToastLastPhase?: IndexingPhase;
+  indexingToastLastLabel?: string;
+}
+
+export function createIdleIndexingProgress(): IndexingProgressState {
+  return { phase: "idle", current: 0, total: 0, startedAt: Date.now() };
+}
+
+export function applyDeltaProgress(
+  runtime: RuntimeContext,
+  payload: DeltaProgressPayload,
+  source: "background" | "reindex"
+): void {
+  const prev = runtime.indexingProgress;
+  const startedAt =
+    payload.phase === "scanning" && prev.phase === "idle" ? Date.now() : prev.startedAt;
+  runtime.indexingProgress = {
+    phase: payload.phase,
+    current: payload.current,
+    total: payload.total,
+    startedAt,
+    label: payload.label,
+    source: payload.phase === "idle" ? undefined : source,
+    failedFiles: payload.failedFiles,
+  };
+  if (payload.phase === "idle") {
+    resetIndexingToastThrottle(runtime);
+  } else {
+    notifyIndexingProgressToast(runtime);
+  }
+}
+
+export function setIncrementalIndexingProgress(runtime: RuntimeContext, filePath: string): void {
+  runtime.indexingProgress = {
+    phase: "indexing",
+    current: 1,
+    total: 1,
+    startedAt: Date.now(),
+    label: path.basename(filePath),
+    source: "background",
+  };
+  notifyIndexingProgressToast(runtime);
+}
+
+export function clearIndexingProgress(runtime: RuntimeContext): void {
+  runtime.indexingProgress = createIdleIndexingProgress();
+  resetIndexingToastThrottle(runtime);
+}
+
+export async function createRuntime(worktree: string, config: PluginConfig, logger: Logger): Promise<RuntimeContext> {
+  const digest = crypto.createHash("sha256").update(worktree).digest("hex").slice(0, 16);
+  const dbPath = path.join(config.storage.global_cache_dir, digest, "embeddings.db");
+  const schemaFile = path.join(path.dirname(new URL(import.meta.url).pathname), "store", "schema.sql");
+  const store = new SemanticStore(dbPath, schemaFile, logger);
+  const embedder = await createEmbedder(config, logger);
+  return {
+    worktree,
+    dbPath,
+    config,
+    store,
+    embedder,
+    logger,
+    indexingLock: false,
+    indexingProgress: createIdleIndexingProgress(),
+  };
+}

package/src/search/context.ts

@@ -0,0 +1,17 @@
+export interface ContextSlice {
+  startLine: number;
+  endLine: number;
+  preview: string;
+}
+
+export function buildContextPreview(fullText: string, startLine: number, endLine: number, contextLines: number): ContextSlice {
+  const lines = fullText.split("\n");
+  const from = Math.max(1, startLine - contextLines);
+  const to = Math.min(lines.length, endLine + contextLines);
+  const preview = lines.slice(from - 1, to).join("\n");
+  return {
+    startLine: from,
+    endLine: to,
+    preview,
+  };
+}

package/src/search/hybrid.ts

@@ -0,0 +1,65 @@
+import type { PluginConfig } from "../config";
+import { withQueryExpansion, type Embedder } from "../embedder/interface";
+import type { SearchRow, SemanticStore } from "../store/sqlite";
+
+export interface RankedResult {
+  file: string;
+  startLine: number;
+  endLine: number;
+  score: number;
+  vectorScore: number;
+  bm25Score: number;
+  preview: string;
+}
+
+function identifierBoost(query: string, text: string, base: number, factor: number): number {
+  const tokens = query
+    .split(/\W+/)
+    .map((t) => t.trim())
+    .filter(Boolean);
+  const hasIdentifier = tokens.some((token) => text.includes(token));
+  return hasIdentifier ? base * factor : base;
+}
+
+function rankRow(row: SearchRow, query: string, config: PluginConfig): number {
+  const score =
+    config.search.hybrid.weight_vector * row.vectorScore +
+    config.search.hybrid.weight_bm25 * row.bm25Score +
+    config.search.hybrid.weight_rrf * (1 / (1 + row.vectorScore + row.bm25Score));
+  return identifierBoost(query, row.text, score, config.search.hybrid.identifier_boost);
+}
+
+export async function hybridSearch(
+  store: SemanticStore,
+  embedder: Embedder,
+  query: string,
+  topK: number,
+  config: PluginConfig,
+): Promise<RankedResult[]> {
+  const [queryEmbedding] = await embedder.embed([withQueryExpansion(query)]);
+  const multiplier = config.search.hybrid.candidate_multiplier ?? 1.5;
+  const rows = store.searchHybrid(queryEmbedding ?? [], query, Math.ceil(topK * multiplier));
+  const sorted = rows
+    .map((row) => {
+      const score = rankRow(row, query, config);
+      return {
+        file: row.filePath,
+        startLine: row.startLine,
+        endLine: row.endLine,
+        score,
+        vectorScore: row.vectorScore,
+        bm25Score: row.bm25Score,
+        preview: row.text,
+      };
+    })
+    .filter((row) => row.score >= config.search.similarity_threshold)
+    .sort((a, b) => b.score - a.score);
+  const seen = new Set<string>();
+  const deduped = sorted.filter((r) => {
+    const key = r.preview.trim().slice(0, 120);
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+  return deduped.slice(0, topK);
+}

package/src/store/schema.sql

@@ -0,0 +1,31 @@
+CREATE TABLE IF NOT EXISTS files (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  path TEXT NOT NULL UNIQUE,
+  content_hash TEXT NOT NULL,
+  indexed_at INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS chunks (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  file_id INTEGER NOT NULL,
+  start_line INTEGER NOT NULL,
+  end_line INTEGER NOT NULL,
+  text TEXT NOT NULL,
+  chunk_hash TEXT NOT NULL UNIQUE,
+  embedding TEXT NOT NULL,
+  FOREIGN KEY(file_id) REFERENCES files(id) ON DELETE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS sync_state (
+  key TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+
+CREATE VIRTUAL TABLE IF NOT EXISTS chunks_fts USING fts5(
+  text,
+  chunk_id UNINDEXED,
+  tokenize='porter unicode61'
+);
+
+CREATE INDEX IF NOT EXISTS idx_chunks_file_id ON chunks(file_id);
+CREATE INDEX IF NOT EXISTS idx_files_indexed_at ON files(indexed_at);

package/src/store/sqlite.ts

@@ -0,0 +1,269 @@
+import { Database } from "bun:sqlite";
+import { load as loadSqliteVec } from "sqlite-vec";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import type { Logger } from "../logger";
+
+export interface SearchRow {
+  chunkId: number;
+  filePath: string;
+  startLine: number;
+  endLine: number;
+  text: string;
+  vectorScore: number;
+  bm25Score: number;
+}
+
+export function projectHash(worktree: string): string {
+  return crypto.createHash("sha256").update(worktree).digest("hex").slice(0, 16);
+}
+
+function loadSchema(db: Database, schemaFile: string): void {
+  const sql = fs.readFileSync(schemaFile, "utf8");
+  db.exec(sql);
+}
+
+/** Split camelCase and separators so FTS5 can match substrings like getUser / profile. */
+function expandCodeIdentifiers(text: string): string {
+  const split = text
+    .replace(/([a-z])([A-Z])/g, "$1 $2")
+    .replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2")
+    .replace(/[_\-./]/g, " ");
+  return `${text} ${split}`.toLowerCase();
+}
+
+const ftsSchemaVersionKey = "fts_schema_version";
+
+export class SemanticStore {
+  public readonly db: Database;
+  private readonly logger?: Logger;
+
+  constructor(dbPath: string, schemaFile: string, logger?: Logger) {
+    this.logger = logger;
+    try {
+      fs.mkdirSync(path.dirname(dbPath), { recursive: true });
+      this.db = new Database(dbPath, { create: true });
+      this.db.exec("PRAGMA journal_mode=WAL;");
+      this.db.exec("PRAGMA busy_timeout=5000;");
+      this.db.exec("PRAGMA foreign_keys=ON;");
+      loadSqliteVec(this.db as never);
+      loadSchema(this.db, schemaFile);
+      this.migrateFtsSchemaIfNeeded();
+      this.db.exec("CREATE VIRTUAL TABLE IF NOT EXISTS chunk_vec USING vec0(chunk_id INTEGER, embedding FLOAT[768]);");
+      void this.logger?.info("store.sqlite", {
+        message: "Database initialized",
+        extra: { dbPath }
+      });
+    } catch (error) {
+      void this.logger?.error("store.sqlite", {
+        message: "Database open/init failed",
+        extra: { dbPath, schemaFile },
+        error
+      });
+      throw error;
+    }
+  }
+
+  close(): void {
+    this.db.close();
+  }
+
+  /** Rebuild FTS5 when tokenizer changes (porter unicode61 + expanded identifier text). */
+  private migrateFtsSchemaIfNeeded(): void {
+    if (this.getSyncState(ftsSchemaVersionKey) === "2") return;
+    const tx = this.db.transaction(() => {
+      this.db.exec("DROP TABLE IF EXISTS chunks_fts");
+      this.db.exec(`
+CREATE VIRTUAL TABLE chunks_fts USING fts5(
+  text,
+  chunk_id UNINDEXED,
+  tokenize='porter unicode61'
+);
+`);
+      const rows = this.db.query("SELECT id, text FROM chunks").all() as Array<{ id: number; text: string }>;
+      const insert = this.db.query("INSERT INTO chunks_fts(rowid, text, chunk_id) VALUES(?, ?, ?)");
+      for (const row of rows) {
+        insert.run(row.id, expandCodeIdentifiers(row.text), row.id);
+      }
+      this.setSyncState(ftsSchemaVersionKey, "2");
+    });
+    tx();
+    void this.logger?.info("store.sqlite", {
+      message: "chunks_fts migrated to schema v2 (porter unicode61 + identifier expansion)",
+      extra: { chunkRows: this.db.query("SELECT COUNT(*) AS c FROM chunks").get() as { c: number } }
+    });
+  }
+
+  getSyncState(key: string): string | null {
+    const row = this.db.query("SELECT value FROM sync_state WHERE key = ?").get(key) as { value: string } | null;
+    return row?.value ?? null;
+  }
+
+  setSyncState(key: string, value: string): void {
+    this.db.query("INSERT INTO sync_state(key, value) VALUES(?, ?) ON CONFLICT(key) DO UPDATE SET value=excluded.value").run(key, value);
+  }
+
+  upsertFile(filePath: string, contentHash: string): number {
+    const now = Date.now();
+    this.db.query(
+      "INSERT INTO files(path, content_hash, indexed_at) VALUES(?, ?, ?) ON CONFLICT(path) DO UPDATE SET content_hash=excluded.content_hash, indexed_at=excluded.indexed_at",
+    ).run(filePath, contentHash, now);
+    const row = this.db.query("SELECT id FROM files WHERE path = ?").get(filePath) as { id: number };
+    return row.id;
+  }
+
+  removeMissingFiles(existing: Set<string>): void {
+    const rows = this.db.query("SELECT path FROM files").all() as Array<{ path: string }>;
+    for (const row of rows) {
+      if (existing.has(row.path)) continue;
+      this.db.query("DELETE FROM files WHERE path = ?").run(row.path);
+    }
+  }
+
+  clearChunksForFile(fileId: number): void {
+    const chunkRows = this.db.query("SELECT id FROM chunks WHERE file_id = ?").all(fileId) as Array<{ id: number }>;
+    for (const row of chunkRows) {
+      this.db.query("DELETE FROM chunks_fts WHERE chunk_id = ?").run(row.id);
+      this.db.query("DELETE FROM chunk_vec WHERE chunk_id = ?").run(row.id);
+    }
+    this.db.query("DELETE FROM chunks WHERE file_id = ?").run(fileId);
+  }
+
+  /**
+   * Replace all chunks for a file atomically: clear existing rows then insert new ones.
+   * Use for indexing so concurrent workers do not interleave deletes/inserts.
+   */
+  writeFileChunks(
+    fileId: number,
+    writes: Array<{ startLine: number; endLine: number; text: string; chunkHash: string; embedding: number[] }>
+  ): void {
+    const tx = this.db.transaction(() => {
+      this.clearChunksForFile(fileId);
+      for (const w of writes) {
+        this.insertChunk(fileId, w.startLine, w.endLine, w.text, w.chunkHash, w.embedding);
+      }
+    });
+    tx();
+  }
+
+  /**
+   * Upsert the file record AND replace all its chunks in one atomic transaction.
+   * Prevents the atomicity gap where `upsertFile` commits a new content_hash before
+   * `writeFileChunks` succeeds — which would permanently hide the file from future
+   * delta scans if the chunk write later fails.
+   */
+  writeFileAndChunks(
+    filePath: string,
+    contentHash: string,
+    writes: Array<{ startLine: number; endLine: number; text: string; chunkHash: string; embedding: number[] }>
+  ): number {
+    let fileId = 0;
+    const tx = this.db.transaction(() => {
+      fileId = this.upsertFile(filePath, contentHash);
+      this.clearChunksForFile(fileId);
+      for (const w of writes) {
+        this.insertChunk(fileId, w.startLine, w.endLine, w.text, w.chunkHash, w.embedding);
+      }
+    });
+    tx();
+    return fileId;
+  }
+
+  insertChunk(fileId: number, startLine: number, endLine: number, text: string, chunkHash: string, embedding: number[]): number {
+    this.db
+      .query("INSERT OR IGNORE INTO chunks(file_id, start_line, end_line, text, chunk_hash, embedding) VALUES(?, ?, ?, ?, ?, ?)")
+      .run(fileId, startLine, endLine, text, chunkHash, JSON.stringify(embedding));
+    const row = this.db.query("SELECT id FROM chunks WHERE chunk_hash = ?").get(chunkHash) as { id: number };
+    const vecLiteral = JSON.stringify(embedding);
+    this.db.query("INSERT OR REPLACE INTO chunk_vec(chunk_id, embedding) VALUES(?, ?)").run(row.id, vecLiteral);
+    this.db.query("INSERT OR REPLACE INTO chunks_fts(rowid, text, chunk_id) VALUES(?, ?, ?)").run(
+      row.id,
+      expandCodeIdentifiers(text),
+      row.id,
+    );
+    return row.id;
+  }
+
+  getChunkByHash(chunkHash: string): { embedding: number[] } | null {
+    const row = this.db.query("SELECT embedding FROM chunks WHERE chunk_hash = ?").get(chunkHash) as { embedding: string } | null;
+    if (!row) return null;
+    return { embedding: JSON.parse(row.embedding) as number[] };
+  }
+
+  stats(): { files: number; chunks: number; lastSync: string | null } {
+    const files = (this.db.query("SELECT COUNT(*) AS c FROM files").get() as { c: number }).c;
+    const chunks = (this.db.query("SELECT COUNT(*) AS c FROM chunks").get() as { c: number }).c;
+    const lastSync = this.getSyncState("last_sync");
+    return { files, chunks, lastSync };
+  }
+
+  searchHybrid(queryEmbedding: number[], queryText: string, topK: number): SearchRow[] {
+    const vecRows = this.db
+      .query(
+        `
+      SELECT c.id as chunkId, f.path as filePath, c.start_line as startLine, c.end_line as endLine, c.text as text,
+             (1.0 / (1.0 + distance)) as vectorScore
+      FROM chunk_vec v
+      JOIN chunks c ON c.id = v.chunk_id
+      JOIN files f ON f.id = c.file_id
+      WHERE v.embedding MATCH ?
+        AND v.k = ?
+      ORDER BY distance
+      `,
+      )
+      .all(JSON.stringify(queryEmbedding), topK) as Array<Omit<SearchRow, "bm25Score">>;
+
+    const sanitizedBm25Query = queryText
+      .match(/[a-zA-Z0-9_]{2,}/g)
+      ?.join(" OR ");
+
+    const bm25Rows = sanitizedBm25Query
+      ? (this.db
+          .query(
+            `
+      SELECT c.id as chunkId, f.path as filePath, c.start_line as startLine, c.end_line as endLine, c.text as text,
+             bm25(chunks_fts) as score
+      FROM chunks_fts
+      JOIN chunks c ON c.id = chunks_fts.chunk_id
+      JOIN files f ON f.id = c.file_id
+      WHERE chunks_fts MATCH ?
+      ORDER BY score
+      LIMIT ?
+      `,
+          )
+          .all(sanitizedBm25Query, topK) as Array<{
+          chunkId: number;
+          filePath: string;
+          startLine: number;
+          endLine: number;
+          text: string;
+          score: number;
+        }>)
+      : [];
+
+    const maxBm25 = Math.max(...bm25Rows.map((r) => -r.score));
+    const safeMax = maxBm25 <= 0 || !isFinite(maxBm25) ? 1 : maxBm25;
+
+    const merged = new Map<number, SearchRow>();
+    for (const row of vecRows) merged.set(row.chunkId, { ...row, bm25Score: 0 });
+    for (const row of bm25Rows) {
+      const existing = merged.get(row.chunkId);
+      const normalizedBm25 = (-row.score) / safeMax;
+      if (!existing) {
+        merged.set(row.chunkId, {
+          chunkId: row.chunkId,
+          filePath: row.filePath,
+          startLine: row.startLine,
+          endLine: row.endLine,
+          text: row.text,
+          vectorScore: 0,
+          bm25Score: normalizedBm25,
+        });
+      } else {
+        existing.bm25Score = normalizedBm25;
+      }
+    }
+    return [...merged.values()];
+  }
+}

package/src/tools/diagnostic_bundle.ts

@@ -0,0 +1,34 @@
+import type { ToolContext } from "@opencode-ai/plugin";
+import { tool } from "@opencode-ai/plugin";
+import { buildDiagnosticBundle } from "../diagnostics/bundle";
+import type { RuntimeContext } from "../runtime";
+
+export async function executeDiagnosticBundle(
+  runtime: RuntimeContext,
+  ctx?: Pick<ToolContext, "metadata">
+): Promise<string> {
+  const startedAt = Date.now();
+  ctx?.metadata?.({ title: "diagnostic_bundle", metadata: { phase: "collecting" } });
+  const bundle = await buildDiagnosticBundle(runtime);
+  const elapsedMs = Date.now() - startedAt;
+  await runtime.logger.debug("tool.diagnostic_bundle", {
+    message: "Diagnostic bundle requested",
+    extra: { filesIndexed: bundle.index.files_indexed, chunks: bundle.index.chunks_indexed },
+  });
+  ctx?.metadata?.({
+    title: "diagnostic_bundle",
+    metadata: { phase: "done", elapsed_ms: elapsedMs, chunks: bundle.index.chunks_indexed },
+  });
+  return JSON.stringify(bundle, null, 2);
+}
+
+export function createDiagnosticBundleTool(runtime: RuntimeContext) {
+  return tool({
+    description:
+      "Export a JSON diagnostic bundle for support and debugging: embedding provider health, index stats, DB path, and recent smart-grep routing outcomes. Same data as `bun run diagnostic:bundle` from the plugin repo.",
+    args: {},
+    async execute(_args, toolCtx) {
+      return executeDiagnosticBundle(runtime, toolCtx);
+    },
+  });
+}