npm - @cerefox/memory - Versions diffs - 0.7.2 → 0.8.0 - Mend

@cerefox/memory 0.7.2 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (47) hide show

package/dist/frontend/index.html CHANGED Viewed

@@ -5,7 +5,7 @@
     <link rel="icon" type="image/png" href="/app/cerefox_icon.png" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Cerefox</title>
-    <script type="module" crossorigin src="/app/assets/index-BzAPcCXA.js"></script>
+    <script type="module" crossorigin src="/app/assets/index-CAp2_lFX.js"></script>
     <link rel="stylesheet" crossorigin href="/app/assets/index-DoDJGRih.css">
   </head>
   <body>

package/dist/server-assets/_shared/ef-meta/index.ts ADDED Viewed

@@ -0,0 +1,97 @@
+/**
+ * Shared Edge Function metadata (iter-26 Part 26B).
+ *
+ * Every Cerefox Edge Function answers `GET <ef>/version` with
+ * `{ name, version }` so clients can detect server↔client drift
+ * (see `_shared/compatibility/`). `cerefox-mcp` additionally exposes an
+ * aggregator at `GET cerefox-mcp/version?peers=true` that probes every
+ * peer EF + the Postgres schema version, so `cerefox doctor` learns the
+ * whole server-side version picture in one round-trip.
+ *
+ * This module is Deno-runtime safe (no `node:` imports) so it can be
+ * imported by the EFs as well as the Node/Bun local client. It is one of
+ * the `_shared` subtrees bundled into the npm package's
+ * `dist/server-assets/_shared/` (Part 26A) so EFs deploy with it intact.
+ *
+ * `EF_VERSION` is bumped by `scripts/cut_release.ts` when EF source
+ * actually changed since the previous tag (guarded — a release that
+ * doesn't touch `supabase/functions/` leaves it alone).
+ */
+export const EF_VERSION = "0.8.0";
+/**
+ * The 8 peer EFs the cerefox-mcp aggregator probes (excludes cerefox-mcp
+ * itself). Order is the probe order.
+ */
+export const PEER_EF_NAMES = [
+  "cerefox-search",
+  "cerefox-ingest",
+  "cerefox-metadata",
+  "cerefox-get-document",
+  "cerefox-list-versions",
+  "cerefox-get-audit-log",
+  "cerefox-metadata-search",
+  "cerefox-list-projects",
+] as const;
+export interface EfVersionPayload {
+  name: string;
+  version: string;
+}
+/** A peer probe result for the aggregator response. */
+export interface PeerVersion {
+  name: string;
+  version: string;
+}
+export interface PeerError {
+  name: string;
+  error: string;
+}
+export interface AggregatedVersions {
+  /** This EF (cerefox-mcp). */
+  name: string;
+  version: string;
+  /** Deployed Postgres schema version, or null if the probe failed. */
+  schema: string | null;
+  /** Successfully-probed peer EFs. */
+  efs: PeerVersion[];
+  /** Peers that failed to respond (timeout, 404, network). */
+  errors: PeerError[];
+}
+/** True when a request targets an EF's `/version` path via GET. */
+export function isVersionRequest(req: Request): boolean {
+  if (req.method !== "GET") return false;
+  const { pathname } = new URL(req.url);
+  return pathname.endsWith("/version");
+}
+/** True when the aggregator was requested (`?peers=true`). */
+export function wantsPeers(req: Request): boolean {
+  return new URL(req.url).searchParams.get("peers") === "true";
+}
+/** Single-EF version response. */
+export function versionResponse(
+  name: string,
+  headers: Record<string, string>,
+): Response {
+  const payload: EfVersionPayload = { name, version: EF_VERSION };
+  return new Response(JSON.stringify(payload), { status: 200, headers });
+}
+/**
+ * Derive a peer EF's `/version` URL from the incoming cerefox-mcp request.
+ * Replaces the trailing `/cerefox-mcp[/...]` path segment with
+ * `/<peerName>/version`, preserving origin + the functions base path.
+ */
+export function peerVersionUrl(reqUrl: string, peerName: string): string {
+  const url = new URL(reqUrl);
+  // Strip everything from `/cerefox-mcp` onward, then append the peer path.
+  const base = url.pathname.replace(/\/cerefox-mcp(\/.*)?$/, "");
+  return `${url.origin}${base}/${peerName}/version`;
+}

package/dist/server-assets/_shared/embeddings/index.ts ADDED Viewed

@@ -0,0 +1,175 @@
+/**
+ * Shared OpenAI-compatible embedding client.
+ *
+ * Used by `_shared/mcp-tools/search.ts` (query embedding) and
+ * `_shared/mcp-tools/ingest.ts` (chunk embeddings). Both the Edge Function
+ * and the local TS MCP server use this module via `_shared/mcp-tools/`.
+ *
+ * Runtime-neutral: uses only `fetch` and `setTimeout`. No Deno- or Bun-
+ * specific APIs. The OpenAI API key is always passed in by the caller —
+ * the module never reads env vars directly.
+ *
+ * Mirrors `supabase/functions/cerefox-mcp/embeddings.ts` exactly for v0.4.0
+ * (extraction commit; no behaviour change). Future tweaks live here.
+ */
+export const OPENAI_EMBEDDING_URL = "https://api.openai.com/v1/embeddings";
+export const OPENAI_MODEL = "text-embedding-3-small";
+export const EMBEDDING_DIMENSIONS = 768;
+const EMBEDDING_MAX_RETRIES = 3;
+const EMBEDDING_INITIAL_BACKOFF_MS = 500; // 500ms → 1s → 2s
+/** Embed a single string. Used for the query vector in `cerefox_search`. */
+export async function getEmbedding(text: string, apiKey: string): Promise<number[]> {
+  let lastError: Error | null = null;
+  for (let attempt = 0; attempt < EMBEDDING_MAX_RETRIES; attempt++) {
+    try {
+      const response = await fetch(OPENAI_EMBEDDING_URL, {
+        method: "POST",
+        headers: {
+          "Authorization": `Bearer ${apiKey}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          model: OPENAI_MODEL,
+          input: text,
+          dimensions: EMBEDDING_DIMENSIONS,
+        }),
+      });
+      if (!response.ok) {
+        const err = await response.text();
+        if (response.status < 500) {
+          // 4xx — don't retry; throw immediately.
+          throw new Error(`OpenAI embedding error ${response.status}: ${err}`);
+        }
+        lastError = new Error(`OpenAI embedding error ${response.status}: ${err}`);
+        const backoff = EMBEDDING_INITIAL_BACKOFF_MS * Math.pow(2, attempt);
+        console.warn(
+          `Embedding API returned ${response.status} (attempt ${attempt + 1}/${EMBEDDING_MAX_RETRIES}), retrying in ${backoff}ms`,
+        );
+        await new Promise((r) => setTimeout(r, backoff));
+        continue;
+      }
+      const data = await response.json();
+      if (attempt > 0) console.info(`Embedding API succeeded on retry ${attempt}`);
+      return data.data[0].embedding;
+    } catch (err) {
+      if (err instanceof Error && err.message.startsWith("OpenAI embedding error")) throw err;
+      lastError = err instanceof Error ? err : new Error(String(err));
+      const backoff = EMBEDDING_INITIAL_BACKOFF_MS * Math.pow(2, attempt);
+      console.warn(
+        `Embedding API request failed: ${lastError.message} (attempt ${attempt + 1}/${EMBEDDING_MAX_RETRIES}), retrying in ${backoff}ms`,
+      );
+      await new Promise((r) => setTimeout(r, backoff));
+    }
+  }
+  throw lastError ?? new Error(`Embedding API failed after ${EMBEDDING_MAX_RETRIES} attempts`);
+}
+/**
+ * Per-API-call batch limit. Mirrors Python's `CloudEmbedder.BATCH_SIZE`
+ * (in `src/cerefox/embeddings/cloud.py`). OpenAI's `/v1/embeddings`
+ * accepts up to 2048 inputs per request, but 96 is the Python contract
+ * and matches what the existing corpus was embedded with.
+ *
+ * v0.7 (iter-25 / Part 25B) introduces this constant to TS — the v0.4
+ * `embedBatch` had no batching and would blow the API limit on bulk
+ * ingest of large documents.
+ */
+export const EMBEDDING_BATCH_SIZE = 96;
+/**
+ * Single API call to OpenAI's embeddings endpoint. Caller is responsible
+ * for staying within the API's per-request limit; in practice, use
+ * `embedBatch` which chunks calls at `EMBEDDING_BATCH_SIZE`.
+ */
+async function embedBatchSingleCall(
+  texts: string[],
+  apiKey: string,
+): Promise<number[][]> {
+  let lastError: Error | null = null;
+  for (let attempt = 0; attempt < EMBEDDING_MAX_RETRIES; attempt++) {
+    try {
+      const response = await fetch(OPENAI_EMBEDDING_URL, {
+        method: "POST",
+        headers: {
+          "Authorization": `Bearer ${apiKey}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          model: OPENAI_MODEL,
+          input: texts,
+          dimensions: EMBEDDING_DIMENSIONS,
+        }),
+      });
+      if (!response.ok) {
+        const err = await response.text();
+        if (response.status < 500) {
+          throw new Error(`OpenAI embedding error ${response.status}: ${err}`);
+        }
+        lastError = new Error(`OpenAI embedding error ${response.status}: ${err}`);
+        const backoff = EMBEDDING_INITIAL_BACKOFF_MS * Math.pow(2, attempt);
+        console.warn(
+          `Embedding API returned ${response.status} (attempt ${attempt + 1}/${EMBEDDING_MAX_RETRIES}), retrying in ${backoff}ms`,
+        );
+        await new Promise((r) => setTimeout(r, backoff));
+        continue;
+      }
+      const data = await response.json();
+      if (attempt > 0) console.info(`Embedding API succeeded on retry ${attempt}`);
+      const sorted = data.data.sort(
+        (a: { index: number }, b: { index: number }) => a.index - b.index,
+      );
+      return sorted.map((d: { embedding: number[] }) => d.embedding);
+    } catch (err) {
+      if (err instanceof Error && err.message.startsWith("OpenAI embedding error")) throw err;
+      lastError = err instanceof Error ? err : new Error(String(err));
+      const backoff = EMBEDDING_INITIAL_BACKOFF_MS * Math.pow(2, attempt);
+      console.warn(
+        `Embedding API request failed: ${lastError.message} (attempt ${attempt + 1}/${EMBEDDING_MAX_RETRIES}), retrying in ${backoff}ms`,
+      );
+      await new Promise((r) => setTimeout(r, backoff));
+    }
+  }
+  throw lastError ?? new Error(`Embedding API failed after ${EMBEDDING_MAX_RETRIES} attempts`);
+}
+/**
+ * Embed multiple strings, chunked into per-API-call batches of
+ * `batchSize` (default 96). Used by the v0.7 ingestion pipeline + the
+ * MCP-tools ingest handler.
+ *
+ * Results are returned in input order (each per-call response is sorted
+ * by `index` and the results concatenated in input order).
+ *
+ * Pre-v0.7 callers that used the old single-call `embedBatch` (no
+ * batching) continue to work — the signature is backward-compatible.
+ * The new `batchSize` param is opt-in; default 96 matches Python.
+ */
+export async function embedBatch(
+  texts: string[],
+  apiKey: string,
+  batchSize: number = EMBEDDING_BATCH_SIZE,
+): Promise<number[][]> {
+  if (texts.length === 0) return [];
+  if (texts.length <= batchSize) {
+    return embedBatchSingleCall(texts, apiKey);
+  }
+  const out: number[][] = [];
+  for (let start = 0; start < texts.length; start += batchSize) {
+    const slice = texts.slice(start, start + batchSize);
+    const vectors = await embedBatchSingleCall(slice, apiKey);
+    for (const v of vectors) out.push(v);
+  }
+  return out;
+}

package/dist/server-assets/_shared/mcp-tools/_chunker.ts ADDED Viewed

@@ -0,0 +1,187 @@
+/**
+ * Heading-aware markdown chunker.
+ *
+ * Mirrors:
+ * - `src/cerefox/chunking/markdown.py` (Python pipeline)
+ * - `supabase/functions/cerefox-ingest/index.ts` (standalone ingest EF)
+ *
+ * Greedy section accumulation: H1/H2/H3 sections are joined into a buffer
+ * until adding the next would exceed `MAX_CHUNK_CHARS`. Oversized sections
+ * are paragraph-split. Short documents collapse to a single chunk.
+ *
+ * The hash of the chunked output (via `_hash.ts:sha256hex(normalizeContent(...))`)
+ * must match the Python pipeline byte-for-byte so dedup works across access
+ * paths. Don't change chunk boundaries without updating both.
+ */
+export const MAX_CHUNK_CHARS = 4000;
+interface Section {
+  level: number;
+  headings: string[];
+  heading: string;
+  content: string;
+  body: string;
+}
+export interface Chunk {
+  heading_path: string[];
+  heading_level: number;
+  title: string;
+  content: string;
+  char_count: number;
+}
+function parseSections(text: string): Section[] {
+  const lines = text.split("\n");
+  const sections: Section[] = [];
+  let currentHeadings: string[] = [];
+  let currentLevel = 0;
+  let bodyLines: string[] = [];
+  function collectSection() {
+    const body = bodyLines.join("\n").trim();
+    bodyLines = [];
+    let content: string;
+    if (currentLevel > 0) {
+      const headerLine = "#".repeat(currentLevel) + " " +
+        (currentHeadings[currentHeadings.length - 1] ?? "");
+      content = body ? headerLine + "\n\n" + body : headerLine;
+    } else {
+      content = body;
+    }
+    if (!content.trim()) return;
+    sections.push({
+      level: currentLevel,
+      headings: [...currentHeadings],
+      heading: currentHeadings[currentHeadings.length - 1] ?? "",
+      content,
+      body,
+    });
+  }
+  for (const line of lines) {
+    const h1 = line.match(/^# (.+)/);
+    const h2 = line.match(/^## (.+)/);
+    const h3 = line.match(/^### (.+)/);
+    if (h1) {
+      collectSection();
+      currentHeadings = [h1[1].trim()];
+      currentLevel = 1;
+    } else if (h2) {
+      collectSection();
+      currentHeadings = [currentHeadings[0] ?? "", h2[1].trim()].filter(Boolean);
+      currentLevel = 2;
+    } else if (h3) {
+      collectSection();
+      currentHeadings = [
+        currentHeadings[0] ?? "",
+        currentHeadings[1] ?? "",
+        h3[1].trim(),
+      ].filter(Boolean);
+      currentLevel = 3;
+    } else {
+      bodyLines.push(line);
+    }
+  }
+  collectSection();
+  return sections;
+}
+function makeChunk(headings: string[], level: number, content: string): Chunk {
+  const title = headings[headings.length - 1] ?? "";
+  return {
+    heading_path: [...headings],
+    heading_level: level,
+    title,
+    content,
+    char_count: content.length,
+  };
+}
+export function chunkMarkdown(text: string): Chunk[] {
+  const trimmed = text.trim();
+  if (!trimmed) return [];
+  if (trimmed.length <= MAX_CHUNK_CHARS) {
+    return [makeChunk([], 0, trimmed)];
+  }
+  const sections = parseSections(trimmed);
+  const chunks: Chunk[] = [];
+  let bufParts: string[] = [];
+  let bufHeadings: string[] = [];
+  let bufLevel = 0;
+  let bufChars = 0;
+  function flushBuf() {
+    if (bufParts.length === 0) return;
+    chunks.push(makeChunk(bufHeadings, bufLevel, bufParts.join("\n\n")));
+    bufParts = [];
+    bufHeadings = [];
+    bufLevel = 0;
+    bufChars = 0;
+  }
+  for (const section of sections) {
+    const { level, headings, heading, content, body } = section;
+    if (content.length > MAX_CHUNK_CHARS) {
+      flushBuf();
+      const headerPrefix = level > 0 ? "#".repeat(level) + " " + heading + "\n\n" : "";
+      const bodyToSplit = body || content;
+      const paragraphs = bodyToSplit.split(/\n\n+/);
+      let sub = "";
+      let isFirst = true;
+      for (const para of paragraphs) {
+        const prefix = isFirst ? headerPrefix : "";
+        if (sub.length + prefix.length + para.length + 2 > MAX_CHUNK_CHARS && sub.length > 0) {
+          chunks.push(makeChunk(headings, level, sub.trim()));
+          sub = para;
+          isFirst = false;
+        } else {
+          sub = sub ? sub + "\n\n" + para : prefix + para;
+          isFirst = false;
+        }
+      }
+      if (sub.trim()) chunks.push(makeChunk(headings, level, sub.trim()));
+      continue;
+    }
+    const addition = content.length + (bufParts.length > 0 ? 2 : 0);
+    if (bufChars + addition <= MAX_CHUNK_CHARS) {
+      if (bufParts.length === 0) {
+        bufHeadings = headings;
+        bufLevel = level;
+      }
+      bufParts.push(content);
+      bufChars += addition;
+    } else {
+      flushBuf();
+      bufParts = [content];
+      bufHeadings = headings;
+      bufLevel = level;
+      bufChars = content.length;
+    }
+  }
+  flushBuf();
+  return chunks;
+}
+/** Content-hash normalization. Must match `pipeline.py::_normalize`
+ *  byte-for-byte so cross-runtime dedup works. */
+export function normalizeContent(text: string): string {
+  return text.trim().replace(/\r\n/g, "\n").replace(/\r/g, "\n").replace(/\n{3,}/g, "\n\n");
+}
+export async function sha256hex(text: string): Promise<string> {
+  const bytes = new TextEncoder().encode(text);
+  const hash = await crypto.subtle.digest("SHA-256", bytes);
+  return Array.from(new Uint8Array(hash))
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}

package/dist/server-assets/_shared/mcp-tools/_projects.ts ADDED Viewed

@@ -0,0 +1,121 @@
+/**
+ * Project-membership helpers shared by the `ingest` and
+ * `set-document-projects` tools.
+ *
+ * Two semantics are needed by callers:
+ *
+ * - **Non-destructive add** (`ensureDocumentInProject`): used when an ingest
+ *   call supplies a singular `project_name`. Resolves (or creates) the
+ *   project, then ensures the `(document, project)` row exists. Idempotent;
+ *   does NOT remove any existing memberships. Per issue #38: the v0.1.20
+ *   fix that stopped agent updates from silently wiping operator-curated
+ *   memberships.
+ *
+ * - **Destructive replace** (`setDocumentProjectsByName`): used when a call
+ *   supplies an explicit `project_names` list (or via the dedicated
+ *   `cerefox_set_document_projects` tool). DELETE-then-INSERT replaces the
+ *   document's memberships with exactly the given set.
+ *
+ * Both call sites need consistent name resolution (case-insensitive
+ * `ilike` match against `cerefox_projects.name`); centralising here
+ * prevents drift.
+ */
+import type { MCPSupabaseClient } from "./types.ts";
+/** Ensure `(documentId, project)` exists. Resolves project by name
+ *  (case-insensitive); creates the project if missing. Idempotent.
+ *  Returns the resolved project_id, or `null` if creation failed. */
+export async function ensureDocumentInProject(
+  supabase: MCPSupabaseClient,
+  documentId: string,
+  projectName: string,
+): Promise<string | null> {
+  let projectId: string | null = null;
+  const { data: proj } = await supabase
+    .from("cerefox_projects")
+    .select("id")
+    .ilike("name", projectName)
+    .limit(1);
+  if (proj?.length) {
+    projectId = proj[0].id;
+  } else {
+    const { data: newProj } = await supabase
+      .from("cerefox_projects")
+      .insert({ name: projectName })
+      .select("id");
+    projectId = newProj?.[0]?.id ?? null;
+  }
+  if (!projectId) return null;
+  const { data: existing } = await supabase
+    .from("cerefox_document_projects")
+    .select("document_id")
+    .eq("document_id", documentId)
+    .eq("project_id", projectId)
+    .limit(1);
+  if (existing?.length) return projectId;
+  const { error: insertErr } = await supabase
+    .from("cerefox_document_projects")
+    .insert({ document_id: documentId, project_id: projectId });
+  if (insertErr && !String(insertErr.message ?? "").includes("duplicate key")) {
+    console.warn("ensureDocumentInProject: insert failed", insertErr);
+  }
+  return projectId;
+}
+/** DELETE-then-INSERT replacement of a document's project memberships.
+ *  Resolves each name → project_id (creating if absent); preserves order.
+ *  Empty `projectNames` clears all memberships. Returns the resolved
+ *  project_ids in input order. */
+export async function setDocumentProjectsByName(
+  supabase: MCPSupabaseClient,
+  documentId: string,
+  projectNames: string[],
+): Promise<string[]> {
+  const projectIds: string[] = [];
+  for (const name of projectNames) {
+    if (!name) continue;
+    const { data: proj } = await supabase
+      .from("cerefox_projects")
+      .select("id")
+      .ilike("name", name)
+      .limit(1);
+    if (proj?.length) {
+      projectIds.push(proj[0].id);
+    } else {
+      const { data: newProj } = await supabase
+        .from("cerefox_projects")
+        .insert({ name })
+        .select("id");
+      if (newProj?.[0]?.id) projectIds.push(newProj[0].id);
+    }
+  }
+  await supabase
+    .from("cerefox_document_projects")
+    .delete()
+    .eq("document_id", documentId);
+  if (projectIds.length > 0) {
+    const rows = projectIds.map((pid) => ({ document_id: documentId, project_id: pid }));
+    await supabase.from("cerefox_document_projects").insert(rows);
+  }
+  return projectIds;
+}
+/** Resolve a project name → project_id (case-insensitive), or `null` if
+ *  not found. Does NOT create. Used by search / metadata-search to translate
+ *  `project_name` parameters to UUIDs. */
+export async function lookupProjectId(
+  supabase: MCPSupabaseClient,
+  projectName: string,
+): Promise<string | null> {
+  const { data, error } = await supabase
+    .from("cerefox_projects")
+    .select("id")
+    .ilike("name", projectName)
+    .limit(1);
+  if (error || !data?.length) return null;
+  return data[0].id;
+}

package/dist/server-assets/_shared/mcp-tools/_utils.ts ADDED Viewed

@@ -0,0 +1,73 @@
+/**
+ * Internal helpers shared by `_shared/mcp-tools/` handlers.
+ *
+ * - `applyByteBudget`: drop whole rows until the cumulative serialized size
+ *   fits within the budget. Used by `search` and `metadata-search`.
+ * - `logUsage`: fire-and-forget write to `cerefox_usage_log` via RPC.
+ *   Never blocks the tool response.
+ *
+ * Both helpers are mirrored from `supabase/functions/cerefox-mcp/shared.ts`
+ * for the v0.4.0 extraction — once `_shared/mcp-tools/` is the source of
+ * truth (after 22D refactors the EF to import from here), the EF's `shared.ts`
+ * removes its copies.
+ */
+import type { MCPSupabaseClient } from "./types.ts";
+/** Server-enforced response-size ceiling for MCP results. Agents can request
+ *  smaller budgets via `max_bytes`; values above this are capped. */
+export const MAX_RESPONSE_BYTES = 200_000;
+export function applyByteBudget(
+  rows: unknown[],
+  maxBytes: number,
+): { accepted: unknown[]; truncated: boolean; usedBytes: number } {
+  const accepted: unknown[] = [];
+  let usedBytes = 0;
+  let truncated = false;
+  for (const row of rows) {
+    const rowBytes = new TextEncoder().encode(JSON.stringify(row)).length;
+    if (usedBytes + rowBytes > maxBytes) {
+      truncated = true;
+      break;
+    }
+    accepted.push(row);
+    usedBytes += rowBytes;
+  }
+  return { accepted, truncated, usedBytes };
+}
+import type { AccessPath } from "./types.ts";
+export interface LogUsageParams {
+  operation: string;
+  accessPath: AccessPath;
+  query_text?: string | null;
+  document_id?: string | null;
+  project_id?: string | null;
+  result_count?: number | null;
+  requestor?: string | null;
+  extra?: Record<string, unknown>;
+}
+/** Fire-and-forget usage logging. Never throws, never blocks the response.
+ *  Failures are silently swallowed — usage logging is best-effort by design.
+ *  Differs from the EF's `logUsage` only in that `accessPath` is a required
+ *  parameter (was hardcoded to `"remote-mcp"` in the EF) so the local TS
+ *  MCP server can pass `"local-mcp"` for the same call site. */
+export function logUsage(supabase: MCPSupabaseClient, params: LogUsageParams): void {
+  Promise.resolve(
+    supabase.rpc("cerefox_log_usage", {
+      p_operation: params.operation,
+      p_access_path: params.accessPath,
+      p_requestor: params.requestor ?? "mcp-agent",
+      p_document_id: params.document_id ?? null,
+      p_project_id: params.project_id ?? null,
+      p_query_text: params.query_text ?? null,
+      p_result_count: params.result_count ?? null,
+      p_extra: params.extra ?? {},
+    }),
+  ).catch(() => {});
+}