@backbencher/brain 0.0.0-stage → 0.1.0

package/dist/chunk-5SD45FLC.js

@@ -0,0 +1,818 @@
+import {
+  embedLocal,
+  initLocalModel,
+  projectVocabulary
+} from "./chunk-7AN7U5IZ.js";
+import {
+  Config,
+  resolveEmbeddingConfig
+} from "./chunk-UGR4QIGS.js";
+import {
+  create
+} from "./chunk-BQ3OVQ3P.js";
+
+// src/brain/semantic/engine.ts
+import { createHash } from "crypto";
+import * as fs from "fs";
+import * as path from "path";
+
+// src/provider/provider.ts
+var Provider;
+((Provider2) => {
+  async function list() {
+    const config = await Config.get();
+    const providers = config.providers ?? {};
+    const result = {};
+    for (const [id, p] of Object.entries(providers)) {
+      result[id] = {
+        id,
+        baseURL: p?.baseURL ?? p?.baseUrl,
+        apiKey: p?.apiKey ?? p?.api_key,
+        models: p?.models ?? {}
+      };
+    }
+    if (process.env.BB_EMBEDDING_BASE_URL) {
+      result["bb"] = {
+        id: "bb",
+        baseURL: process.env.BB_EMBEDDING_BASE_URL,
+        apiKey: process.env.BB_EMBEDDING_API_KEY,
+        models: { [process.env.BB_EMBEDDING_MODEL ?? "text-embedding-3-small"]: { id: process.env.BB_EMBEDDING_MODEL ?? "text-embedding-3-small" } }
+      };
+    }
+    return result;
+  }
+  Provider2.list = list;
+})(Provider || (Provider = {}));
+
+// src/brain/semantic/embedding-config.ts
+var LOOPBACK_HOSTS = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "::1", "[::1]", "0.0.0.0"]);
+function intFromEnv(raw, fallback, min, max) {
+  if (raw === void 0 || raw === "") return fallback;
+  const n = Number(raw);
+  if (!Number.isFinite(n)) return fallback;
+  return Math.min(max, Math.max(min, Math.floor(n)));
+}
+function isEmbeddingDisabled(env = process.env) {
+  const raw = (env.BB_EMBEDDING_DISABLED ?? "").trim().toLowerCase();
+  if (raw === "") return false;
+  return raw === "1" || raw === "true" || raw === "yes" || raw === "on";
+}
+function readRuntimeOptions(env = process.env) {
+  const fbBase = (env.BB_EMBEDDING_FALLBACK_BASE_URL ?? "").trim();
+  const fbModel = (env.BB_EMBEDDING_FALLBACK_MODEL ?? "").trim();
+  const fbKey = (env.BB_EMBEDDING_FALLBACK_API_KEY ?? "").trim();
+  return {
+    disabled: isEmbeddingDisabled(env),
+    timeoutMs: intFromEnv(env.BB_EMBEDDING_TIMEOUT_MS, 3e4, 1e3, 6e5),
+    // 256, and the number is load-bearing rather than arbitrary.
+    //
+    // The indexer already chunks to `maxBatch = 100` snippets per call, so 256
+    // keeps every real indexing request a SINGLE request. An earlier default of
+    // 64 fragmented those 100-item batches into 64 + 36, and because a failure in
+    // any chunk discards the whole batch (SemanticEngine falls back to local for
+    // all of it, so a partial result is useless) the second request's failure
+    // threw away the first request's 64 good vectors. Measured: a mock that
+    // answered once and then 503ed stored 0 API vectors for 260 snippets under
+    // the 64 default, and all 260 under this one — the run no longer loses a
+    // completed request to an unrelated failure. 2048 is OpenAI's own input
+    // ceiling; staying well under it keeps self-hosted servers (llama.cpp caps
+    // far lower) working without configuration.
+    maxInputsPerRequest: intFromEnv(env.BB_EMBEDDING_MAX_INPUTS, 256, 1, 2048),
+    // Only the fallback provider retries inside the client. The PRIMARY provider's
+    // retry is the per-batch path in engine.ts (`_apiRetryAt` + per-batch degrade),
+    // which script/m30/verify-rate-limit.ts pins to EXACT call counts; a second
+    // client-side retry loop for the primary would double-retry and change those
+    // counts. See verifyNoteOnRetryOwnership below.
+    fallbackRetries: intFromEnv(env.BB_EMBEDDING_FALLBACK_RETRIES, 2, 0, 5),
+    retryBaseMs: intFromEnv(env.BB_EMBEDDING_RETRY_BASE_MS, 250, 10, 1e4),
+    retryCapMs: intFromEnv(env.BB_EMBEDDING_RETRY_CAP_MS, 4e3, 100, 6e4),
+    fallback: fbBase && fbModel ? { baseURL: fbBase.replace(/\/+$/, ""), model: fbModel, apiKey: fbKey } : null,
+    assertedDimension: readDimensionAssertion(env)
+  };
+}
+function readDimensionAssertion(env) {
+  const raw = (env.BB_EMBEDDING_DIMENSION ?? "").trim();
+  if (raw === "") return void 0;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n <= 0) return void 0;
+  return Math.floor(n);
+}
+function rawDimensionAssertion(env = process.env) {
+  return (env.BB_EMBEDDING_DIMENSION ?? "").trim();
+}
+function parseEndpoint(baseURL) {
+  let parsed;
+  try {
+    parsed = new URL(baseURL);
+  } catch {
+    return null;
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return null;
+  return { host: parsed.hostname, loopback: LOOPBACK_HOSTS.has(parsed.hostname.toLowerCase()) };
+}
+function assessEndpoint(baseURL, keySource, apiKeySource) {
+  const problems = [];
+  const parsed = parseEndpoint(baseURL);
+  const hasKey = keySource !== "none" && keySource !== "default";
+  if (!parsed) {
+    problems.push({
+      severity: "error",
+      envVar: "BB_EMBEDDING_BASE_URL",
+      message: `embedding base URL is not a usable http(s) endpoint (${JSON.stringify(baseURL)}). Set BB_EMBEDDING_BASE_URL to a full OpenAI-compatible /v1 URL, e.g. https://openrouter.ai/api/v1`
+    });
+    return { usable: false, loopback: false, hasKey, keySource, problems };
+  }
+  if (!parsed.loopback && !hasKey) {
+    problems.push({
+      severity: "error",
+      envVar: "BB_EMBEDDING_API_KEY",
+      message: `embedding provider ${parsed.host} is not local, so it needs a key, and none is set (source: ${apiKeySource}). Set BB_EMBEDDING_API_KEY, or point BB_EMBEDDING_BASE_URL at a loopback endpoint that needs no key. Until then every batch degrades to local word vectors.`
+    });
+  } else if (!parsed.loopback && hasKey && apiKeySource === "default") {
+    problems.push({
+      severity: "warning",
+      envVar: null,
+      message: "embedding key resolved from a config file; confirm that file is mode 0600 (bb doctor --fix)"
+    });
+  }
+  return { usable: true, loopback: parsed.loopback, hasKey, keySource, problems };
+}
+function describeEmbeddingSetup(eff, env = process.env) {
+  const options = readRuntimeOptions(env);
+  const problems = [];
+  if (options.disabled) {
+    return {
+      remoteReady: false,
+      disabled: true,
+      fallbackConfigured: options.fallback !== null,
+      problems: [
+        {
+          severity: "warning",
+          envVar: "BB_EMBEDDING_DISABLED",
+          message: "embeddings are disabled (BB_EMBEDDING_DISABLED). Indexing uses local word vectors; no embedding request will be made."
+        }
+      ]
+    };
+  }
+  if (!eff.configured) {
+    const missingEnvVar = eff.sources.baseURL === "default" ? "BB_EMBEDDING_BASE_URL" : "BB_EMBEDDING_MODEL";
+    const sourceHint = eff.sources.baseURL === "default" && eff.sources.model === "default" ? "No embedding provider is configured, so semantic search uses local word vectors (50-dim, keyword-level). To enable a provider run `bb setup`, or set both BB_EMBEDDING_BASE_URL and BB_EMBEDDING_MODEL." : `Embedding provider is partially configured: ${missingEnvVar} is not set. Set ${missingEnvVar} (and BB_EMBEDDING_API_KEY for a hosted endpoint).`;
+    problems.push({ severity: "warning", envVar: missingEnvVar, message: sourceHint });
+  } else {
+    const readiness = assessEndpoint(eff.baseURL, eff.sources.apiKey, eff.sources.apiKey);
+    problems.push(...readiness.problems);
+  }
+  const rawDimension = rawDimensionAssertion(env);
+  if (rawDimension !== "" && options.assertedDimension === void 0) {
+    problems.push({
+      severity: "warning",
+      envVar: "BB_EMBEDDING_DIMENSION",
+      message: `BB_EMBEDDING_DIMENSION is set to ${JSON.stringify(rawDimension)}, which is not a positive integer. The assertion is ignored \u2014 vectors of any width will be accepted.`
+    });
+  }
+  if (options.fallback) {
+    const fb = assessEndpoint(options.fallback.baseURL, options.fallback.apiKey ? "env:BB_EMBEDDING_API_KEY" : "none", "env:BB_EMBEDDING_FALLBACK_API_KEY");
+    for (const problem of fb.problems) {
+      problems.push({
+        ...problem,
+        message: `fallback provider: ${problem.message}`,
+        envVar: problem.envVar ? problem.envVar.replace("BB_EMBEDDING_API_KEY", "BB_EMBEDDING_FALLBACK_API_KEY").replace("BB_EMBEDDING_BASE_URL", "BB_EMBEDDING_FALLBACK_BASE_URL") : null
+      });
+    }
+    if (!options.fallback.model) {
+      problems.push({ severity: "error", envVar: "BB_EMBEDDING_FALLBACK_MODEL", message: "fallback provider is missing BB_EMBEDDING_FALLBACK_MODEL" });
+    }
+  } else {
+    const wantsFallback = (env.BB_EMBEDDING_FALLBACK_BASE_URL ?? "") !== "" || (env.BB_EMBEDDING_FALLBACK_MODEL ?? "") !== "";
+    if (wantsFallback) {
+      problems.push({
+        severity: "error",
+        envVar: wantsFallback && (env.BB_EMBEDDING_FALLBACK_BASE_URL ?? "") === "" ? "BB_EMBEDDING_FALLBACK_BASE_URL" : "BB_EMBEDDING_FALLBACK_MODEL",
+        message: "BB_EMBEDDING_FALLBACK_BASE_URL / BB_EMBEDDING_FALLBACK_MODEL are set inconsistently; both are required for the fallback provider"
+      });
+    }
+  }
+  return {
+    remoteReady: eff.configured && problems.every((p) => p.severity !== "error"),
+    disabled: false,
+    fallbackConfigured: options.fallback !== null,
+    problems
+  };
+}
+function redactSecrets(text, ...secrets) {
+  let out = text;
+  for (const secret of secrets) {
+    if (typeof secret !== "string" || secret.length < 8) continue;
+    while (out.includes(secret)) out = out.replaceAll(secret, "[REDACTED]");
+  }
+  return out.replace(/(Bearer\s+)[A-Za-z0-9._~+/=-]{8,}/gi, "$1[REDACTED]");
+}
+
+// src/brain/semantic/openai-embed.ts
+var log = create({ service: "openai-embed" });
+function isEmbeddingConfigured(config) {
+  return resolveEmbeddingConfig(config).configured && !readRuntimeOptions().disabled;
+}
+async function getEmbeddingConfig() {
+  const config = await Config.get();
+  const eff = resolveEmbeddingConfig(config);
+  if (!eff.configured) return null;
+  const asserted = readRuntimeOptions().assertedDimension;
+  const cfg = {
+    baseURL: eff.baseURL,
+    apiKey: eff.apiKey,
+    model: eff.model,
+    dimension: asserted ?? (typeof config.embedding_dimension === "number" ? config.embedding_dimension : void 0)
+  };
+  if (!parseEndpoint(cfg.baseURL)) {
+    log.debug("embedding base URL is not a usable endpoint; remote embeddings off", { baseURL: cfg.baseURL });
+    return null;
+  }
+  return cfg;
+}
+var ADVICE = {
+  auth: "The provider rejected the API key. Set a valid key, or run `bb setup` to re-enter it. Nothing will be embedded until this is fixed.",
+  not_found: "The provider has no /embeddings endpoint at that base URL, or does not know the model name. Check BB_EMBEDDING_BASE_URL and BB_EMBEDDING_MODEL.",
+  rate_limit: "Rate limited. The key looks valid; indexing backs off and retries. On a free tier this is a quota, not a fault.",
+  server: "The provider returned a server error. Usually transient; indexing retries and falls back per batch meanwhile.",
+  timeout: "The provider did not respond in time. Check network reachability and the base URL.",
+  network: "Could not reach the provider. Check the base URL and network access.",
+  protocol: "The provider answered with something that is not an embeddings response. The base URL is probably not an OpenAI-compatible /v1 endpoint."
+};
+function classifyStatus(status) {
+  if (status === 401 || status === 403) return "auth";
+  if (status === 404) return "not_found";
+  if (status === 429) return "rate_limit";
+  if (status >= 500) return "server";
+  if (status >= 400) return "protocol";
+  return "server";
+}
+var EmbeddingApiError = class extends Error {
+  status;
+  retryAfterSec;
+  /** Actionable classification. `status === 429` keeps working unchanged. */
+  kind;
+  /** One line the user can act on. Never contains a key. */
+  advice;
+  /** Which provider produced it: "primary" | "fallback" | "probe". */
+  source;
+  /** Endpoint and model that failed — so a report can name them. Never a key. */
+  endpoint;
+  model;
+  constructor(status, message, retryAfterSec, opts = {}) {
+    super(message);
+    this.name = "EmbeddingApiError";
+    this.status = status;
+    this.retryAfterSec = retryAfterSec;
+    this.kind = opts.kind ?? (status === 0 ? "network" : classifyStatus(status));
+    this.advice = ADVICE[this.kind];
+    this.source = opts.source ?? "primary";
+    this.endpoint = opts.baseURL ?? "";
+    this.model = opts.model ?? "";
+  }
+};
+var authLatch = /* @__PURE__ */ new Map();
+function observedEmbeddingFailures() {
+  return [...authLatch.values()].map((error) => ({
+    baseURL: error.endpoint,
+    model: error.model,
+    status: error.status,
+    kind: error.kind,
+    advice: error.advice,
+    message: error.message
+  }));
+}
+function latchKey(baseURL, model) {
+  return `${baseURL}|${model}`;
+}
+async function probeEmbeddingEndpoint(cfg, optionsOverride) {
+  const started = Date.now();
+  const options = { ...readRuntimeOptions(), ...optionsOverride };
+  try {
+    const result = await attemptRequest(["bb doctor embedding probe"], cfg, options, "probe");
+    return { ok: true, elapsedMs: Date.now() - started, dimension: result.vectors[0]?.length };
+  } catch (e) {
+    const err = e?.name === "EmbeddingApiError" ? e : new EmbeddingApiError(0, String(e?.message ?? e), void 0, { kind: "network", source: "probe", baseURL: cfg.baseURL, model: cfg.model });
+    return {
+      ok: false,
+      elapsedMs: Date.now() - started,
+      status: err.status,
+      kind: err.kind,
+      advice: err.advice,
+      message: err.message
+    };
+  }
+}
+function chunk(items, size) {
+  if (size <= 1 || items.length <= size) return [items];
+  const out = [];
+  for (let i = 0; i < items.length; i += size) out.push(items.slice(i, i + size));
+  return out;
+}
+function sleep(ms) {
+  return new Promise((resolve2) => {
+    const t = setTimeout(resolve2, ms);
+    if (typeof t === "object" && t && typeof t.unref === "function") t.unref();
+  });
+}
+function backoffFor(attempt, opts, retryAfterSec) {
+  if (retryAfterSec && retryAfterSec > 0) {
+    return Math.min(retryAfterSec * 1e3, opts.retryCapMs) + Math.floor(Math.random() * 100);
+  }
+  const exponential = opts.retryBaseMs * 2 ** attempt;
+  const capped = Math.min(exponential, opts.retryCapMs);
+  return capped + Math.floor(Math.random() * Math.max(1, Math.floor(capped / 4)));
+}
+function isRetryable(error, attempt, maxAttempts) {
+  if (attempt >= maxAttempts - 1) return false;
+  return error.kind === "rate_limit" || error.kind === "server" || error.kind === "timeout" || error.kind === "network";
+}
+async function attemptRequest(texts, cfg, options, source) {
+  const who = { source, baseURL: cfg.baseURL, model: cfg.model };
+  const url = `${cfg.baseURL}/embeddings`;
+  const payload = JSON.stringify({
+    model: cfg.model,
+    input: texts.length === 1 ? texts[0] : texts,
+    encoding_format: "float"
+  });
+  const parsedUrl = new URL(url);
+  const endpoint = parseEndpoint(cfg.baseURL);
+  const isLocal = endpoint?.loopback ?? false;
+  if (isLocal) {
+    const loopbackHosts = ["127.0.0.1", "localhost", "::1"];
+    for (const key of ["NO_PROXY", "no_proxy"]) {
+      const existing = process.env[key] ?? "";
+      const values = new Set(existing.split(",").map((v) => v.trim()).filter(Boolean));
+      for (const host of loopbackHosts) values.add(host);
+      process.env[key] = [...values].join(",");
+    }
+  }
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), options.timeoutMs);
+  let res;
+  try {
+    res = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        ...cfg.apiKey ? { Authorization: `Bearer ${cfg.apiKey}` } : {}
+      },
+      body: payload,
+      signal: controller.signal
+    });
+    const status = res.status;
+    let retryAfterRaw = null;
+    if (status === 429 || status === 503) retryAfterRaw = res.headers.get("retry-after");
+    const body = await res.text();
+    clearTimeout(timer);
+    if (status < 200 || status >= 300) {
+      let retryAfterSec;
+      if (status === 429) {
+        const secs = retryAfterRaw ? Number(retryAfterRaw) : NaN;
+        if (Number.isFinite(secs) && secs > 0) retryAfterSec = secs;
+      }
+      throw new EmbeddingApiError(
+        status,
+        // Message text is part of the observed contract: script/m21/verify-embedding-provider.ts
+        // matches /embedding API 429/ on it. Redaction is added, not substituted.
+        `embedding API ${status}: ${redactSecrets(body.slice(0, 200), cfg.apiKey)}`,
+        retryAfterSec,
+        who
+      );
+    }
+    let data;
+    try {
+      data = JSON.parse(body);
+    } catch {
+      throw new EmbeddingApiError(status, `embedding API ${status}: response is not JSON \u2014 ${redactSecrets(body.slice(0, 200), cfg.apiKey)}`, void 0, { kind: "protocol", ...who });
+    }
+    if (!data || !Array.isArray(data.data)) {
+      throw new EmbeddingApiError(status, `embedding API ${status}: response has no data array`, void 0, { kind: "protocol", ...who });
+    }
+    const rows = [...data.data];
+    if (rows.some((row) => typeof row?.index === "number")) {
+      rows.sort((a, b) => (typeof a?.index === "number" ? a.index : 0) - (typeof b?.index === "number" ? b.index : 0));
+    }
+    const embeddings = rows.map((row) => row?.embedding);
+    if (embeddings.length !== texts.length) {
+      throw new Error(`embedding API returned ${embeddings.length} vectors for ${texts.length} inputs`);
+    }
+    return { vectors: validateVectors(embeddings, texts.length, cfg, source) };
+  } catch (e) {
+    clearTimeout(timer);
+    if (e?.name === "EmbeddingApiError") throw e;
+    if (e?.name === "AbortError") {
+      throw new EmbeddingApiError(0, `embedding provider did not respond within ${options.timeoutMs}ms`, void 0, { kind: "timeout", ...who });
+    }
+    throw new EmbeddingApiError(0, `embedding request failed: ${redactSecrets(String(e?.message ?? e).slice(0, 200), cfg.apiKey)}`, void 0, { kind: "network", ...who });
+  }
+}
+function validateVectors(embeddings, expected, cfg, source) {
+  const who = { source, baseURL: cfg.baseURL, model: cfg.model };
+  const out = [];
+  let dimension = null;
+  for (let i = 0; i < embeddings.length; i++) {
+    const vector = embeddings[i];
+    if (!Array.isArray(vector) || vector.length === 0) {
+      throw new EmbeddingApiError(200, `embedding API returned a non-vector for input ${i} of ${expected}`, void 0, { kind: "protocol", ...who });
+    }
+    for (const component of vector) {
+      if (typeof component !== "number" || !Number.isFinite(component)) {
+        throw new EmbeddingApiError(200, `embedding API returned a non-finite component in vector ${i}`, void 0, { kind: "protocol", ...who });
+      }
+    }
+    if (dimension === null) dimension = vector.length;
+    else if (vector.length !== dimension) {
+      throw new EmbeddingApiError(
+        200,
+        `embedding API returned mixed dimensions (${dimension} and ${vector.length}) in one batch \u2014 these vectors cannot be stored together`,
+        void 0,
+        { kind: "protocol", ...who }
+      );
+    }
+    out.push(vector);
+  }
+  if (cfg.dimension !== void 0 && dimension !== null && dimension !== cfg.dimension) {
+    throw new EmbeddingApiError(
+      200,
+      `embedding API returned ${dimension}-dimensional vectors but BB_EMBEDDING_DIMENSION declares ${cfg.dimension} \u2014 refusing to store vectors from a different space than the index already holds under "${cfg.model}". Reindex with the real dimension, or unset BB_EMBEDDING_DIMENSION.`,
+      void 0,
+      { kind: "protocol", ...who }
+    );
+  }
+  return out;
+}
+async function embedOpenAICompatible(texts, cfg, optionsOverride) {
+  if (!Array.isArray(texts) || texts.length === 0) return [];
+  const options = optionsOverride ?? readRuntimeOptions();
+  if (options.disabled) {
+    throw new EmbeddingApiError(
+      0,
+      "embeddings are disabled (BB_EMBEDDING_DISABLED)",
+      void 0,
+      { kind: "protocol", source: "primary", baseURL: cfg.baseURL, model: cfg.model }
+    );
+  }
+  const latched = authLatch.get(latchKey(cfg.baseURL, cfg.model));
+  if (latched) throw latched;
+  try {
+    return await runProvider(texts, cfg, options, "primary", 1);
+  } catch (primaryError) {
+    if (primaryError?.name !== "EmbeddingApiError") throw primaryError;
+    if (primaryError.kind === "auth" || primaryError.kind === "not_found") {
+      log.warn("embedding provider rejected the request; further calls skipped for this process", {
+        kind: primaryError.kind,
+        status: primaryError.status,
+        source: primaryError.source,
+        advice: primaryError.advice
+      });
+      authLatch.set(latchKey(cfg.baseURL, cfg.model), primaryError);
+      throw primaryError;
+    }
+    if (!options.fallback) throw primaryError;
+    log.debug("primary embedding provider failed; trying the configured fallback", {
+      kind: primaryError.kind,
+      status: primaryError.status
+    });
+    const fbCfg = {
+      baseURL: options.fallback.baseURL,
+      apiKey: options.fallback.apiKey,
+      model: options.fallback.model,
+      dimension: cfg.dimension
+    };
+    const fbLatched = authLatch.get(latchKey(fbCfg.baseURL, fbCfg.model));
+    if (fbLatched) throw fbLatched;
+    try {
+      const vectors = await runProvider(texts, fbCfg, options, "fallback", options.fallbackRetries + 1);
+      log.debug("fallback embedding provider served the batch", { model: fbCfg.model });
+      return vectors;
+    } catch (fallbackError) {
+      if (fallbackError?.name === "EmbeddingApiError" && (fallbackError.kind === "auth" || fallbackError.kind === "not_found")) {
+        log.warn("fallback embedding provider rejected the request; further calls skipped for this process", {
+          kind: fallbackError.kind,
+          status: fallbackError.status
+        });
+        authLatch.set(latchKey(fbCfg.baseURL, fbCfg.model), fallbackError);
+      }
+      throw fallbackError;
+    }
+  }
+}
+async function runProvider(texts, cfg, options, source, maxAttempts) {
+  const batches = chunk(texts, Math.max(1, options.maxInputsPerRequest));
+  const out = [];
+  for (let b = 0; b < batches.length; b++) {
+    const batch = batches[b];
+    let attempt = 0;
+    for (; ; ) {
+      try {
+        const result = await attemptRequest(batch, cfg, options, source);
+        out.push(...result.vectors);
+        break;
+      } catch (e) {
+        const err = e?.name === "EmbeddingApiError" ? e : new EmbeddingApiError(0, String(e?.message ?? e), void 0, { kind: "network", source });
+        if (!isRetryable(err, attempt, maxAttempts)) throw err;
+        const wait = backoffFor(attempt, options, err.retryAfterSec);
+        log.debug("embedding attempt failed; backing off before retry", {
+          source,
+          attempt: attempt + 1,
+          maxAttempts,
+          kind: err.kind,
+          status: err.status,
+          waitMs: wait
+        });
+        await sleep(wait);
+        attempt++;
+      }
+    }
+  }
+  return out;
+}
+
+// src/brain/semantic/engine.ts
+var log2 = create({ service: "brain-semantic-engine" });
+function loadConfigWorkerFallback() {
+  try {
+    const bbJsonPath = process.env.BB_CONFIG_FILE ? path.resolve(process.env.BB_CONFIG_FILE) : path.join(process.cwd(), "bb.json");
+    if (fs.existsSync(bbJsonPath)) {
+      return JSON.parse(fs.readFileSync(bbJsonPath, "utf8"));
+    }
+  } catch (_) {
+  }
+  return {};
+}
+var SemanticEngine;
+((SemanticEngine2) => {
+  let _embeddingAvailable = null;
+  let _checked = false;
+  let _localAvailable = null;
+  let _lastModel = null;
+  SemanticEngine2.LOCAL_MODEL_LABEL = "local-word-vectors-v3";
+  function getLastEmbeddingModel() {
+    return _lastModel || SemanticEngine2.LOCAL_MODEL_LABEL;
+  }
+  SemanticEngine2.getLastEmbeddingModel = getLastEmbeddingModel;
+  async function isEmbeddingAvailable() {
+    if (_checked) return _embeddingAvailable === true;
+    _checked = true;
+    if (_localAvailable === null) {
+      try {
+        _localAvailable = await initLocalModel();
+      } catch {
+        _localAvailable = false;
+      }
+    }
+    if (_localAvailable) {
+      _embeddingAvailable = true;
+      return true;
+    }
+    try {
+      const config = await loadConfig();
+      if (!isEmbeddingConfigured(config)) {
+        _embeddingAvailable = false;
+        return false;
+      }
+      _embeddingAvailable = true;
+      return true;
+    } catch {
+      _embeddingAvailable = false;
+      return false;
+    }
+  }
+  SemanticEngine2.isEmbeddingAvailable = isEmbeddingAvailable;
+  async function getEmbeddingModel(configModel) {
+    if (configModel) return configModel;
+    try {
+      const cfg = await getEmbeddingConfig();
+      if (cfg) return cfg.model;
+    } catch {
+    }
+    try {
+      const providers = await Provider.list();
+      const providerMap = providers;
+      if (providerMap["openai"]?.models?.["text-embedding-3-small"]) return "openai/text-embedding-3-small";
+      if (providerMap["azure"]?.models?.["text-embedding-3-small"]) return "azure/text-embedding-3-small";
+      if (providerMap["mistral"]?.models?.["mistral-embed"]) return "mistral/mistral-embed";
+      if (providerMap["google"]?.models?.["text-embedding-004"]) return "google/text-embedding-004";
+      if (providerMap["google-vertex"]?.models?.["text-embedding-004"]) return "google-vertex/text-embedding-004";
+      if (providerMap["cohere"]?.models?.["embed-english-v3.0"]) return "cohere/embed-english-v3.0";
+      if (providerMap["nvidia"]?.models?.["nvidia/nv-embedqa-e5-v5"]) return "nvidia/nvidia/nv-embedqa-e5-v5";
+      if (providerMap["cloudflare-workers-ai"]?.models?.["@cf/baai/bge-small-en-v1.5"])
+        return "cloudflare-workers-ai/@cf/baai/bge-small-en-v1.5";
+      if (providerMap["opencode"]?.models?.["text-embedding-3-small"]) return "opencode/text-embedding-3-small";
+      for (const p of Object.values(providerMap)) {
+        for (const m of Object.values(p.models || {})) {
+          if (m.id.toLowerCase().includes("embed")) return `${p.id}/${m.id}`;
+        }
+      }
+    } catch (e) {
+      log2.debug("Failed to list providers for embedding model", { error: e });
+    }
+    log2.debug("No embedding model configured \u2014 defaulting to opencode/text-embedding-3-small");
+    return "opencode/text-embedding-3-small";
+  }
+  SemanticEngine2.getEmbeddingModel = getEmbeddingModel;
+  async function loadConfig() {
+    if (SemanticEngine2.__config) {
+      return SemanticEngine2.__config;
+    }
+    const bbJson = loadConfigWorkerFallback();
+    if (bbJson && (bbJson.embedding_model || bbJson.provider)) {
+      const eff = resolveEmbeddingConfig(bbJson);
+      const merged = { ...bbJson };
+      if (eff.configured) {
+        merged.embedding_base_url = eff.baseURL;
+        merged.embedding_model = eff.model;
+        merged.embedding_api_key = eff.apiKey;
+      }
+      return merged;
+    }
+    try {
+      return await Config.get();
+    } catch (_) {
+      return bbJson;
+    }
+  }
+  const EMBED_CACHE_MAX = Number(process.env.BB_EMBEDDING_CACHE_MAX || 128);
+  const _embedCache = /* @__PURE__ */ new Map();
+  let _embedCacheHits = 0;
+  let _embedCacheMisses = 0;
+  function embedCacheKey(space, text) {
+    return `${space}\0${createHash("sha1").update(text).digest("hex")}`;
+  }
+  function embedCacheGet(key) {
+    const hit = _embedCache.get(key);
+    if (!hit) {
+      _embedCacheMisses++;
+      return null;
+    }
+    _embedCacheHits++;
+    _embedCache.delete(key);
+    _embedCache.set(key, hit);
+    return hit.slice();
+  }
+  function embedCachePut(key, vec) {
+    if (!Array.isArray(vec) || vec.length === 0) return;
+    if (!Number.isFinite(EMBED_CACHE_MAX) || EMBED_CACHE_MAX <= 0) return;
+    if (_embedCache.has(key)) _embedCache.delete(key);
+    _embedCache.set(key, vec.slice());
+    while (_embedCache.size > EMBED_CACHE_MAX) {
+      const oldest = _embedCache.keys().next().value;
+      if (oldest === void 0) break;
+      _embedCache.delete(oldest);
+    }
+  }
+  function embeddingCacheStats() {
+    return { size: _embedCache.size, max: EMBED_CACHE_MAX, hits: _embedCacheHits, misses: _embedCacheMisses };
+  }
+  SemanticEngine2.embeddingCacheStats = embeddingCacheStats;
+  function clearEmbeddingCache() {
+    _embedCache.clear();
+    _embedCacheHits = 0;
+    _embedCacheMisses = 0;
+  }
+  SemanticEngine2.clearEmbeddingCache = clearEmbeddingCache;
+  async function embed(text, projectId) {
+    if (_checked && !_embeddingAvailable) return [];
+    const config = await loadConfig();
+    if (isEmbeddingConfigured(config)) {
+      try {
+        const cfg = await getEmbeddingConfig();
+        if (cfg) {
+          const key = embedCacheKey(`${cfg.model}|${cfg.baseURL}`, text);
+          const cached = embedCacheGet(key);
+          if (cached) {
+            _embeddingAvailable = true;
+            _checked = true;
+            _lastModel = cfg.model;
+            return cached;
+          }
+          const res = await embedOpenAICompatible([text], cfg);
+          if (res.length > 0) {
+            _embeddingAvailable = true;
+            _checked = true;
+            _lastModel = cfg.model;
+            embedCachePut(key, res[0]);
+            return res[0];
+          }
+        }
+      } catch (e) {
+        log2.debug("API embedding failed", { error: e?.message?.slice(0, 80) });
+      }
+    }
+    try {
+      if (_localAvailable === null) _localAvailable = await initLocalModel();
+      if (_localAvailable) {
+        const key = embedCacheKey(projectId ? `${SemanticEngine2.LOCAL_MODEL_LABEL}|${projectId}` : SemanticEngine2.LOCAL_MODEL_LABEL, text);
+        const cachedLocal = embedCacheGet(key);
+        if (cachedLocal) {
+          _embeddingAvailable = true;
+          _checked = true;
+          _lastModel = SemanticEngine2.LOCAL_MODEL_LABEL;
+          return cachedLocal;
+        }
+        const localResult = await embedLocal([text], await localVocabulary(projectId));
+        if (localResult.length > 0 && localResult[0].length > 0) {
+          _embeddingAvailable = true;
+          _checked = true;
+          _lastModel = SemanticEngine2.LOCAL_MODEL_LABEL;
+          embedCachePut(key, localResult[0]);
+          return localResult[0];
+        }
+      }
+    } catch {
+    }
+    return [];
+  }
+  SemanticEngine2.embed = embed;
+  async function localVocabulary(projectId) {
+    if (!projectId) return null;
+    try {
+      const { BrainDatabase } = await import("./database-TCTZDLE5.js");
+      const raw = await BrainDatabase.getRawInstance(projectId, { readonly: true });
+      return projectVocabulary(raw, String(projectId));
+    } catch {
+      return null;
+    }
+  }
+  let _apiRetryAt = 0;
+  SemanticEngine2.API_BACKOFF_CAP_MS = 3e4;
+  SemanticEngine2.API_BACKOFF_JITTER_MS = 500;
+  function backoffMs(retryAfterSec) {
+    const base = retryAfterSec && retryAfterSec > 0 ? retryAfterSec * 1e3 : 5e3;
+    const capped = Math.min(base, SemanticEngine2.API_BACKOFF_CAP_MS);
+    return capped + Math.floor(Math.random() * SemanticEngine2.API_BACKOFF_JITTER_MS);
+  }
+  async function embedMany(texts, projectId) {
+    if (_checked && !_embeddingAvailable) return [];
+    if (!texts || texts.length === 0) return [];
+    const config = await loadConfig();
+    if (Date.now() >= _apiRetryAt && isEmbeddingConfigured(config)) {
+      try {
+        const cfg = await getEmbeddingConfig();
+        if (cfg) {
+          const embeddings = await embedOpenAICompatible(texts, cfg);
+          if (embeddings.length > 0) {
+            _apiRetryAt = 0;
+            _embeddingAvailable = true;
+            _checked = true;
+            _lastModel = cfg.model;
+            return embeddings;
+          }
+        }
+      } catch (e) {
+        if (e?.name === "EmbeddingApiError" && e?.status === 429) {
+          _apiRetryAt = Date.now() + backoffMs(e?.retryAfterSec);
+          log2.debug("API 429 \u2014 backing off before next attempt", { retryAfterSec: e?.retryAfterSec });
+        } else {
+          log2.debug("API embedding failed for this batch; next batch retries", { error: e?.message?.slice(0, 60) });
+        }
+      }
+    }
+    try {
+      if (_localAvailable === null) _localAvailable = await initLocalModel();
+      if (_localAvailable) {
+        const vocabulary = await localVocabulary(projectId);
+        const localResult = await embedLocal(texts, vocabulary);
+        if (localResult.length > 0) {
+          _embeddingAvailable = true;
+          _checked = true;
+          _lastModel = SemanticEngine2.LOCAL_MODEL_LABEL;
+          return localResult;
+        }
+      }
+    } catch (e) {
+      log2.debug("local embedding failed", { error: e?.message });
+    }
+    return [];
+  }
+  SemanticEngine2.embedMany = embedMany;
+  function cosineSimilarity(vecA, vecB) {
+    if (!vecA || !vecB || vecA.length !== vecB.length || vecA.length === 0) return 0;
+    let dotProduct = 0, normA = 0, normB = 0;
+    for (let i = 0; i < vecA.length; i++) {
+      dotProduct += vecA[i] * vecB[i];
+      normA += vecA[i] * vecA[i];
+      normB += vecB[i] * vecB[i];
+    }
+    if (normA === 0 || normB === 0) return 0;
+    return dotProduct / (Math.sqrt(normA) * Math.sqrt(normB));
+  }
+  SemanticEngine2.cosineSimilarity = cosineSimilarity;
+  function hashContent(text) {
+    return createHash("md5").update(text).digest("hex");
+  }
+  SemanticEngine2.hashContent = hashContent;
+})(SemanticEngine || (SemanticEngine = {}));
+
+export {
+  isEmbeddingDisabled,
+  readRuntimeOptions,
+  parseEndpoint,
+  assessEndpoint,
+  describeEmbeddingSetup,
+  classifyStatus,
+  observedEmbeddingFailures,
+  probeEmbeddingEndpoint,
+  SemanticEngine
+};