@cerefox/memory 1.14.2 → 1.14.3

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

@@ -18,7 +18,7 @@
  * doesn't touch `supabase/functions/` leaves it alone).
  */
 
-export const EF_VERSION = "1.14.2";
+export const EF_VERSION = "1.14.3";
 
 /**
  * The Cerefox RELEASE version — what `cerefox --version` reports and what npm
@@ -36,7 +36,7 @@ export const EF_VERSION = "1.14.2";
  * is imported by the Deno Edge Functions, which cannot reach into the npm
  * package.
  */
-export const CEREFOX_VERSION = "1.14.2";
+export const CEREFOX_VERSION = "1.14.3";
 
 /**
  * The most recent version whose EF-side SOURCE actually changed (#127).
@@ -46,7 +46,7 @@ export const CEREFOX_VERSION = "1.14.2";
  * `cut_release.ts` ONLY when EF source changed since the last tag; doctor
  * uses it to stay silent on label-only drift.
  */
-export const EF_LAST_CHANGED = "1.14.2";
+export const EF_LAST_CHANGED = "1.14.3";
 
 /**
  * The 8 peer EFs the cerefox-mcp aggregator probes (excludes cerefox-mcp

package/dist/server-assets/_shared/mcp-tools/metadata-search.ts

@@ -22,7 +22,11 @@ async function handler(
   const project_name = args.project_name as string | undefined;
   const updated_since = args.updated_since as string | undefined;
   const created_since = args.created_since as string | undefined;
-  const limit = (args.limit as number | undefined) ?? 10;
+  // Sanitised and clamped, like `match_count` on the search tool: the local
+  // stdio server passes tool arguments through unvalidated, so a caller could
+  // ask for a million rows (#267). 500 matches the largest listing the web
+  // API serves, so no legitimate enumeration is cut short.
+  const limit = Math.min(Math.max(1, Math.floor(Number(args.limit)) || 10), 500);
   const include_content = (args.include_content as boolean | undefined) ?? false;
   const requested_max_bytes = args.max_bytes as number | undefined;
 
@@ -47,10 +51,20 @@ async function handler(
     if (!projectId) throw new Error(`Project not found: ${project_name}`);
   }
 
-  // Enforce byte ceiling for content mode
+  // Enforce byte ceiling for content mode.
+  //
+  // Sanitised first: a non-numeric `max_bytes` became `NaN`, which reaches the
+  // RPC as JSON null, and `p_max_bytes NULL` means NO limit — so one word
+  // instead of a number returned every matching document's full content, with
+  // the in-process guard below disabled too (#267). Same hole as the search
+  // tool's, in the sibling that shares its transport.
   const ceiling = getMaxResponseBytes();
+  const requestedBytes = Math.floor(Number(requested_max_bytes));
   const max_bytes = include_content
-    ? Math.min(requested_max_bytes ?? ceiling, ceiling)
+    ? Math.min(
+        Number.isFinite(requestedBytes) ? Math.max(requestedBytes, 1) : ceiling,
+        ceiling,
+      )
     : null;
 
   const params: Record<string, unknown> = {
@@ -84,14 +98,20 @@ async function handler(
     content: string | null;
   }>;
 
-  logUsage(supabase, {
-    operation: "metadata_search",
-    accessPath: ctx.accessPath,
-    requestor: callerIdentity(args),
-    query_text: JSON.stringify(metadata_filter ?? {}),
-    project_id: projectId,
-    result_count: rows.length,
-  });
+  // Logged once, AFTER the degraded branch below may have found the real
+  // count: firing here unconditionally wrote a `result_count: 0` row for
+  // every budget-wiped search, and adding a second row in the branch made
+  // analytics double-count them (#259).
+  const log = (result_count: number, extra?: Record<string, unknown>) =>
+    logUsage(supabase, {
+      operation: "metadata_search",
+      accessPath: ctx.accessPath,
+      requestor: callerIdentity(args),
+      query_text: JSON.stringify(metadata_filter ?? {}),
+      project_id: projectId,
+      result_count,
+      ...(extra ? { extra } : {}),
+    });
 
   if (rows.length === 0) {
     // The RPC applies the byte budget server-side by stopping at the first row
@@ -100,24 +120,53 @@ async function handler(
     // without content before reporting nothing: an agent that is told "no
     // documents" stops looking, and here that would be false.
     if (include_content && max_bytes !== null) {
-      const { data: headers } = await supabase.rpc("cerefox_metadata_search", {
-        ...params,
-        p_include_content: false,
-        p_max_bytes: null,
-      });
+      // supabase-js RESOLVES with `{ data: null, error }` for PostgREST
+      // failures and for network errors; it does not throw. A try/catch here
+      // was dead code, and worse: `headers` came back null, the branch below
+      // was skipped, and the handler answered "No documents match the given
+      // criteria" — the exact false-empty this branch exists to prevent
+      // (#261). Read the error, and say what is actually known.
+      const { data: headers, error: probeError } = await supabase.rpc(
+        "cerefox_metadata_search",
+        { ...params, p_include_content: false, p_max_bytes: null },
+      );
+      if (probeError) {
+        log(0, { degraded_probe_failed: true });
+        return (
+          `⚠ Nothing fit max_bytes=${max_bytes} with include_content, and the ` +
+          `follow-up query that lists what matched failed: ${probeError.message}. ` +
+          `This is NOT a confirmed empty result — retry with a larger max_bytes, ` +
+          `or with include_content: false.`
+        );
+      }
       const headerRows = (headers ?? []) as Array<{ document_id: string; title: string }>;
       if (headerRows.length > 0) {
-        return (
+        // The caller asked for a budget; honour it in the answer that explains
+        // the budget. `limit` is caller-supplied, so an uncapped list could be
+        // tens of KB in reply to a 2 KB request (#257).
+        const lead =
           `⚠ ${headerRows.length} document(s) match, but none fit max_bytes=${max_bytes} ` +
           `with include_content. This is NOT an empty result. Listing them without ` +
           `content — raise max_bytes, or read one with cerefox_get_document ` +
-          `(outline: true for structure).\n\n` +
-          headerRows.map((r) => `## ${r.title} [id: ${r.document_id}]`).join("\n")
-        );
+          `(outline: true for structure).`;
+        const lines: string[] = [];
+        let used = new TextEncoder().encode(lead).length;
+        for (const r of headerRows) {
+          const line = `## ${r.title} [id: ${r.document_id}]`;
+          const size = new TextEncoder().encode(line).length + 1;
+          if (used + size > max_bytes) break;
+          lines.push(line);
+          used += size;
+        }
+        // What matched, not what the budget allowed through (#257).
+        log(headerRows.length, { returned: lines.length, degraded: true });
+        return lines.length > 0 ? `${lead}\n${lines.join("\n")}` : lead;
       }
     }
+    log(0);
     return "No documents match the given criteria.";
   }
+  log(rows.length);
 
   // The review status is a column of a feature that may be off (#241); when
   // it is, an agent should not see "approved" and wonder what it means.

package/dist/server-assets/_shared/mcp-tools/search.ts

@@ -18,7 +18,7 @@
 import type { MCPSupabaseClient } from "./types.ts";
 
 import { getEmbedding, resolveEmbedderKind } from "../embeddings/index.ts";
-import { applyByteBudget, getConfiguredMinSearchScore, getConfiguredSearchAlpha,
+import { getConfiguredMinSearchScore, getConfiguredSearchAlpha,
   getMaxResponseBytes, getMinTermCoverage, logUsage } from "./_utils.ts";
 import { lookupProjectId } from "./_projects.ts";
 import { McpInvalidParams, type ToolContext, type ToolDefinition } from "./types.ts";
@@ -27,7 +27,16 @@ import { AUTHOR_PARAM_READ, callerIdentity } from "./identity.ts";
 interface SearchRow {
   document_id?: string;
   doc_title?: string;
+  /** Document-level modes (`docs`) return this… */
   full_content?: string;
+  /** …while `hybrid` and `fts` return the chunk text under this name. */
+  content?: string;
+  /** Chunk-mode identity: the RPCs return several chunks OF THE SAME document. */
+  chunk_id?: string;
+  chunk_index?: number;
+  /** The chunk's own heading, and its full path from the document root. */
+  title?: string;
+  heading_path?: string[];
   best_score?: number;
   score?: number;
   is_partial?: boolean;
@@ -37,15 +46,86 @@ interface SearchRow {
   below_confidence?: boolean;
 }
 
+/** The row's text, under whichever column name this search mode returns. */
+export function rowContent(row: SearchRow): string {
+  return row.full_content ?? row.content ?? "";
+}
+
+/**
+ * `Document Title › Section` for a chunk row, `Document Title` for a document
+ * row, plus the ids that identify it.
+ *
+ * The chunk RPCs return several chunks OF THE SAME document, so without the
+ * section and the index those results are indistinguishable (#261). Shared by
+ * the rendered path and the degraded one, where identical headings would be
+ * the entire answer.
+ */
+function rowHeading(row: SearchRow): string {
+  const doc = row.doc_title ?? "Untitled";
+  // `heading_path` normally opens with the document's own H1, so the FIRST
+  // element is dropped when it repeats the title. Only the first: a section
+  // legitimately named after the document must still appear (#261).
+  const path = [...(row.heading_path ?? [])];
+  if (path.length > 0 && path[0] === doc) path.shift();
+  const section = path.length
+    ? path.filter(Boolean).join(" › ")
+    : row.title && row.title !== doc
+      ? row.title
+      : "";
+  const docId = row.document_id ? ` [id: ${row.document_id}]` : "";
+  const chunk = row.chunk_index != null ? ` (chunk ${row.chunk_index})` : "";
+  return `${doc}${section ? ` › ${section}` : ""}${docId}${chunk}`;
+}
+
+/**
+ * A short label for a row in the truncation footer: the leaf section, the
+ * chunk index, and the document id.
+ *
+ * Shorter than the rendered heading, which carries the whole breadcrumb — the
+ * footer names up to five rows, and full headings pushed the reply over the
+ * budget it was reporting on (#263). The id stays, because chunk modes span
+ * documents too and two documents sharing a title and a section name are
+ * otherwise indistinguishable, with no way to fetch either (#265). The footer
+ * is inside the budget and drops names it cannot afford, so it is accounted
+ * for either way.
+ */
+function shortLabel(row: SearchRow): string {
+  const doc = row.doc_title ?? "Untitled";
+  const path = [...(row.heading_path ?? [])];
+  if (path.length > 0 && path[0] === doc) path.shift();
+  const leaf = path.filter(Boolean).at(-1) ?? (row.title && row.title !== doc ? row.title : "");
+  const chunk = row.chunk_index != null ? ` (chunk ${row.chunk_index})` : "";
+  // Always the id. Chunk modes are not single-document either, so two
+  // documents sharing a title and a section name would otherwise produce
+  // byte-identical entries with no way to fetch either (#265). The footer is
+  // inside the budget now and drops names it cannot afford, so carrying the
+  // id costs nothing that is not accounted for.
+  const id = row.document_id ? ` [id: ${row.document_id}]` : "";
+  return `${leaf ? `${doc} › ${leaf}` : doc}${chunk}${id}`;
+}
+
+/** One rendered result: heading, score, then the row's text. */
+function renderRow(row: SearchRow): string {
+  const raw = row.best_score ?? row.score;
+  const score = raw != null ? ` (score: ${raw.toFixed(3)})` : "";
+  const partial = row.is_partial
+    ? ` -- partial (${row.chunk_count} of ${(row.total_chars ?? 0).toLocaleString()} chars)`
+    : "";
+  // content_hash = the concurrency token for cerefox_ingest updates (iter-32).
+  const hash = row.content_hash ? `\nhash: ${row.content_hash}` : "";
+  // Whichever column this mode returns (#259): `cerefox_search_docs` gives
+  // `full_content`, the chunk RPCs give `content`, and reading only the first
+  // rendered every hybrid/fts result as a title with an empty body.
+  return `## ${rowHeading(row)}${score}${partial}${hash}\n\n${rowContent(row)}`;
+}
+
 /** `## Title [id: …] (score: …) -- 20,297 chars` — everything but the content. */
 function headerLine(row: SearchRow): string {
-  const title = row.doc_title ?? "Untitled";
-  const docId = row.document_id ? ` [id: ${row.document_id}]` : "";
   const raw = row.best_score ?? row.score;
   const score = raw != null ? ` (score: ${raw.toFixed(3)})` : "";
   const size = row.total_chars != null ? ` -- ${row.total_chars.toLocaleString()} chars` : "";
   const hash = row.content_hash ? `\nhash: ${row.content_hash}` : "";
-  return `## ${title}${docId}${score}${size}${hash}`;
+  return `## ${rowHeading(row)}${score}${size}${hash}`;
 }
 
 /**
@@ -56,15 +136,30 @@ function headerLine(row: SearchRow): string {
  * still honours the limit the caller asked for; if even one header does not
  * fit, the count and the remedy alone still beat silence.
  */
-function degradedToHeaders(matched: SearchRow[], maxBytes: number): string {
-  const biggest = Math.max(
-    ...matched.map((r) => new TextEncoder().encode(JSON.stringify(r)).length),
-  );
+function degradedToHeaders(
+  matched: SearchRow[],
+  rendered: string[],
+  maxBytes: number,
+  belowConfidence: boolean,
+): string {
+  // Rendered bytes, not JSON: the fit decision that reaches here is made in
+  // rendered bytes, and quoting a JSON size produced messages saying the
+  // largest result was 490 bytes and did not fit a 600-byte budget (#265).
+  // Sizes come from the render the caller already paid for — re-rendering
+  // whole documents here just to measure them tripled peak memory.
+  const biggest = Math.max(...rendered.map((t) => new TextEncoder().encode(t).length));
+  // A degraded response must not silently promote 28I's weak-signal
+  // candidates into real matches: an agent told "N result(s) matched" about
+  // rows that cleared no threshold would trust them.
+  const confidence = belowConfidence
+    ? "None of these cleared the confidence threshold — they are the closest " +
+      "candidates, so judge relevance from the scores. "
+    : "";
   const lead =
     `⚠ ${matched.length} result(s) matched, but none fit max_bytes=${maxBytes} ` +
-    `(the largest is ${biggest.toLocaleString()} bytes). This is NOT an empty ` +
-    `knowledge base. Listing what matched, without content — raise max_bytes to ` +
-    `read it, or read one document with cerefox_get_document (outline: true for ` +
+    `(the largest is ${biggest.toLocaleString()} bytes). ${confidence}This is NOT an ` +
+    `empty knowledge base. Listing what matched, without content — raise max_bytes ` +
+    `to read it, or read one document with cerefox_get_document (outline: true for ` +
     `structure, or section: "## Heading" for one part).`;
 
   const lines: string[] = [];
@@ -86,7 +181,12 @@ async function handler(
 ): Promise<string> {
   const query = args.query as string;
   const project_name = args.project_name as string | undefined;
-  const match_count = (args.match_count as number | undefined) ?? 5;
+  // Sanitised, then clamped, exactly as the Edge Function does it. Clamping
+  // alone left `NaN` for a non-numeric value, which serialises to JSON null,
+  // and `LIMIT NULL` in Postgres means NO limit — the unbounded work the
+  // clamp exists to prevent, reachable because the local MCP server passes
+  // tool arguments through unvalidated (#265).
+  const match_count = Math.min(Math.max(1, Math.floor(Number(args.match_count)) || 5), 200);
   const mode = (args.mode as string | undefined) ?? "docs";
   // #133: omit unconfigured tunables so the server resolves them from
   // cerefox_config (one setting governs every access path).
@@ -107,7 +207,18 @@ async function handler(
   const requested_max_bytes = args.max_bytes as number | undefined;
 
   const ceiling = getMaxResponseBytes();
-  const max_bytes = Math.min(requested_max_bytes ?? ceiling, ceiling);
+  // Sanitised before clamping, for the reason `match_count` is: `NaN` makes
+  // every `> max_bytes` comparison below false, so a non-numeric value emitted
+  // every row unbounded — the ceiling bypassed by passing it a word (#266).
+  // A NUMBER of 0 or less still means "almost no budget", as it always did:
+  // falling back to the ceiling there would hand a caller whose remaining
+  // allowance ran out the largest possible reply (#267). Only a missing or
+  // non-numeric value defaults to the ceiling.
+  const requestedBytes = Math.floor(Number(requested_max_bytes));
+  const max_bytes = Math.min(
+    Number.isFinite(requestedBytes) ? Math.max(requestedBytes, 1) : ceiling,
+    ceiling,
+  );
 
   if (
     metadata_filter !== null &&
@@ -187,7 +298,137 @@ async function handler(
   if (error) throw new Error(`RPC error: ${error.message}`);
 
   const matched = (data ?? []) as SearchRow[];
-  const { accepted, dropped, truncated, usedBytes } = applyByteBudget(matched, max_bytes);
+
+  // 28I: nothing cleared the relevance threshold, so the server returned its
+  // best-effort candidates flagged below_confidence rather than an empty set
+  // (which agents misread as "this knowledge does not exist"). The flag is
+  // all-or-nothing per response, so it is read from what MATCHED.
+  const belowConfidence = matched.length > 0 && matched.every((r) => r.below_confidence === true);
+
+  if (matched.length === 0) {
+    logUsage(supabase, {
+      operation: "search",
+      accessPath: ctx.accessPath,
+      requestor: callerIdentity(args),
+      query_text: query,
+      project_id: projectId,
+      result_count: 0,
+    });
+    return "No results found.";
+  }
+
+  // ── Fit the reply to max_bytes, in the units the caller receives ──────────
+  //
+  // The budget is spent on RENDERED text, not on the JSON the RPC returned:
+  // `applyByteBudget` measures `JSON.stringify(row)`, which is the right unit
+  // for the Edge Function (it ships JSON) and the wrong one here (this returns
+  // markdown). Reserving rendered bytes out of a JSON-measured budget
+  // guaranteed nothing, and neither the below-confidence preamble (~185 bytes)
+  // nor the footer was counted by anything (#265).
+  //
+  // So: render, then take as many rows as the whole assembled reply can carry.
+  // Assembling and measuring is the only way to be sure, because the preamble
+  // and the footer both depend on how many rows were kept.
+  const rendered = matched.map(renderRow);
+  const size = (t: string) => new TextEncoder().encode(t).length;
+  const SEP = "\n\n---\n\n";
+
+  // The 28I advisory, long and short. It is charged to the budget like
+  // everything else, but it must never displace the answer it is advising
+  // about: a ~190-byte banner that pushes the only result out of a small reply
+  // leaves the caller with a warning and no content (#265). The short form is
+  // the floor — the contract is that weak candidates are never presented as
+  // confident ones, and that survives in six words.
+  const banner = (take: number, short: boolean) =>
+    !belowConfidence
+      ? ""
+      : short
+        ? `⚠ Below the confidence threshold — judge relevance from the scores.\n\n`
+        : `⚠ No results cleared the confidence threshold. Showing the closest ${take} ` +
+          `candidate(s) with scores — judge relevance yourself; a low score means weak ` +
+          `signal, not necessarily absent knowledge.\n\n`;
+
+  /**
+   * The whole reply for a set of kept rows.
+   *
+   * Everything but the results is optional, in this order: the long advisory
+   * gives way first, then the named list of what was dropped, then the bare
+   * footer. What is NOT optional is saying that results were dropped — a
+   * reply that quietly returns 1 of 5 hits leaves the caller believing they
+   * saw everything, which is the failure this whole file is about (#266).
+   */
+  const assemble = (keptCount: number, short: boolean): string => {
+    const kept = keptIdx.slice(0, keptCount);
+    const body = banner(keptCount, short) + kept.map((i) => rendered[i]!).join(SEP);
+    if (kept.length === matched.length) return body;
+
+    const droppedRows = matched.filter((_, i) => !kept.includes(i));
+    const room = max_bytes - size(body);
+    const footer = (named: number) => {
+      const labels = droppedRows.slice(0, named).map(shortLabel);
+      const rest = droppedRows.length - labels.length;
+      const naming = labels.length
+        ? `: ${labels.join(", ")}${rest > 0 ? ` and ${rest} more` : ""}`
+        : "";
+      return (
+        `\n\n[${kept.length} of ${matched.length} result(s) shown; ${droppedRows.length} did ` +
+        `not fit max_bytes=${max_bytes}${naming}. Raise max_bytes, narrow the query, or ` +
+        `lower match_count.]`
+      );
+    };
+    for (let named = Math.min(5, droppedRows.length); named >= 1; named--) {
+      const candidate = footer(named);
+      if (size(candidate) <= room) return body + candidate;
+    }
+    const bare = footer(0);
+    if (size(bare) <= room) return body + bare;
+    // The floor, ~25 bytes, never dropped: the caller must know there is more.
+    return body + `\n\n[${kept.length} of ${matched.length} shown; raise max_bytes]`;
+  };
+
+  // Which rows the budget can carry, in rank order. Rows that do not fit are
+  // SKIPPED rather than ending the scan: one oversized top hit used to suppress
+  // every smaller result behind it, and the reply then claimed nothing fit when
+  // rows two and three would have fitted comfortably (#266).
+  const sepBytes = size(SEP);
+  const keptIdx: number[] = [];
+  let acc = 0;
+  for (let i = 0; i < rendered.length; i++) {
+    const add = size(rendered[i]!) + (keptIdx.length > 0 ? sepBytes : 0);
+    if (acc + add > max_bytes) continue;
+    acc += add;
+    keptIdx.push(i);
+  }
+
+  // Not one result fits (#254) — the only case that answers with no content,
+  // and now the only case that can truthfully say so.
+  if (keptIdx.length === 0) {
+    logUsage(supabase, {
+      operation: "search",
+      accessPath: ctx.accessPath,
+      requestor: callerIdentity(args),
+      query_text: query,
+      project_id: projectId,
+      result_count: matched.length,
+      extra: { returned: 0, truncated: true, degraded: true },
+    });
+    return degradedToHeaders(matched, rendered, max_bytes, belowConfidence);
+  }
+
+  // Give up the framing before the content, but never the fact of truncation:
+  // long advisory, then a result, and the "N of M shown" notice always stays.
+  let keptCount = keptIdx.length;
+  let short = false;
+  let output = assemble(keptCount, short);
+  while (size(output) > max_bytes) {
+    if (belowConfidence && !short) short = true;
+    else if (keptCount > 1) {
+      keptCount -= 1;
+      short = belowConfidence;
+    } else break; // one result plus the shortest possible framing: the floor
+    output = assemble(keptCount, short);
+  }
+  const take = keptCount;
 
   logUsage(supabase, {
     operation: "search",
@@ -195,59 +436,12 @@ async function handler(
     requestor: callerIdentity(args),
     query_text: query,
     project_id: projectId,
-    // What the QUERY matched, not what survived the byte budget. The two
-    // differ only when rows were dropped, and recording 0 there made a
-    // budget-wiped search look like an empty knowledge base in analytics too.
+    // What the QUERY matched, not what survived the budget: recording the
+    // latter made a budget-wiped search look like an empty store in analytics.
     result_count: matched.length,
-    ...(truncated ? { extra: { returned: accepted.length, truncated: true } } : {}),
+    ...(take < matched.length ? { extra: { returned: take, truncated: true } } : {}),
   });
 
-  // Nothing matched: the honest empty answer.
-  if (matched.length === 0) return "No results found.";
-
-  // Something matched but none of it fit the budget (#254). Reporting "no
-  // results" here is the most damaging answer the tool can give: an agent
-  // stops looking and often recreates the document it failed to find. Show
-  // the headers instead — a few hundred bytes that name what exists and how
-  // to read it.
-  if (accepted.length === 0) {
-    return degradedToHeaders(matched, max_bytes);
-  }
-
-  const rows = accepted as SearchRow[];
-
-  // 28I: nothing cleared the relevance threshold, so the server returned its
-  // best-effort top candidates flagged below_confidence instead of an empty
-  // set (which agents misread as "this knowledge does not exist").
-  const belowConfidence = rows.length > 0 && rows.every((r) => r.below_confidence === true);
-
-  const parts: string[] = rows.map((row) => {
-    const title = row.doc_title ?? "Untitled";
-    const docId = row.document_id ? ` [id: ${row.document_id}]` : "";
-    const rawScore = row.best_score ?? row.score;
-    const score = rawScore != null ? ` (score: ${rawScore.toFixed(3)})` : "";
-    const partial = row.is_partial
-      ? ` -- partial (${row.chunk_count} of ${(row.total_chars ?? 0).toLocaleString()} chars)`
-      : "";
-    // content_hash = the concurrency token for cerefox_ingest updates (iter-32).
-    const hash = row.content_hash ? `\nhash: ${row.content_hash}` : "";
-    return `## ${title}${docId}${score}${partial}${hash}\n\n${row.full_content ?? ""}`;
-  });
-
-  let output = parts.join("\n\n---\n\n");
-  if (belowConfidence) {
-    output =
-      `⚠ No results cleared the confidence threshold. Showing the closest ${rows.length} ` +
-      `candidate(s) with scores — judge relevance yourself; a low score means weak signal, ` +
-      `not necessarily absent knowledge.\n\n` + output;
-  }
-  if (truncated) {
-    output +=
-      `\n\n[${accepted.length} of ${matched.length} result(s) shown; truncated at ` +
-      `${usedBytes} bytes. ${dropped.length} did not fit: ` +
-      `${dropped.map((r) => (r as SearchRow).doc_title ?? "Untitled").join(", ")}. ` +
-      `Raise max_bytes, narrow the query, or lower match_count.]`;
-  }
   return output;
 }
 
@@ -269,7 +463,7 @@ export const searchTool: ToolDefinition = {
       query: { type: "string", description: "Natural-language search query" },
       match_count: {
         type: "integer",
-        description: "Maximum number of documents to return (default: 5)",
+        description: "Maximum number of documents to return (default: 5, maximum: 200)",
       },
       project_name: {
         type: "string",

package/dist/server-assets/supabase/functions/cerefox-search/index.ts

@@ -36,7 +36,16 @@ import { applyByteBudget } from "../../../_shared/mcp-tools/_utils.ts";
  *                                      `truncated` flag when results were dropped.
  *
  * Response: { results: [...], query, mode, match_count, project_name?,
- *             truncated: boolean, response_bytes: number }
+ *             truncated: boolean, response_bytes: number,
+ *             matched: number, degraded: boolean, note?: string }
+ *
+ * `matched` is how many results the query found, before the byte budget.
+ * `degraded` is true when everything that matched was larger than max_bytes:
+ * the items then carry NO content, they name what exists so the caller can
+ * re-ask with a larger budget. That header list is capped to max_bytes and so
+ * may be a SUBSET of `matched`, except that one item is always returned even
+ * if it exceeds the budget — an empty `results` would read as "nothing was
+ * found", which is `matched: 0` and nothing else (#254, #257, #261).
  *
  * Example agent prompt:
  *   "Invoke the cerefox-search edge function with query='knowledge management'
@@ -150,14 +159,6 @@ async function lookupProjectId(
   return data[0].id;
 }
 
-/**
- * Apply a byte budget to an array of result rows.
- *
- * Each row is serialised to JSON to measure its size. Rows are included in
- * order until the next row would push the running total over `maxBytes`.
- * Rows are always kept or dropped whole — content is never truncated
- * mid-document. Returns the accepted rows and a `truncated` flag.
- */
 const headers = {
   "Content-Type": "application/json",
   "Access-Control-Allow-Origin": "*",
@@ -214,7 +215,15 @@ Deno.serve(async (req: Request) => {
   } = body;
 
   // Enforce ceiling: agents may request less but never more than MAX_BYTES.
-  const max_bytes = Math.min(requested_max_bytes ?? MAX_BYTES, MAX_BYTES);
+  // Sanitised before clamping: `NaN` compares false against every budget
+  // check, so a non-numeric value bypassed the ceiling entirely (#266).
+  // A number of 0 or less still means "almost no budget"; only a missing or
+  // non-numeric value falls back to the ceiling (#267).
+  const requestedBytes = Math.floor(Number(requested_max_bytes));
+  const max_bytes = Math.min(
+    Number.isFinite(requestedBytes) ? Math.max(requestedBytes, 1) : MAX_BYTES,
+    MAX_BYTES,
+  );
   // Clamp match_count to [1, MAX_MATCH_COUNT] (bounds query work; see MAX_MATCH_COUNT).
   const match_count = Math.min(Math.max(1, Math.floor(Number(raw_match_count)) || 5), MAX_MATCH_COUNT);
 
@@ -362,10 +371,33 @@ Deno.serve(async (req: Request) => {
   // knowledge does not exist" to whatever is on the other end, so send the
   // rows WITHOUT their content instead: the caller learns what matched, how
   // big it is, and can re-ask with a larger budget or fetch one document.
+  //
+  // Both content columns have to go: `cerefox_search_docs` (mode "docs")
+  // returns `full_content`, while `cerefox_hybrid_search` and the FTS RPC
+  // return `content`. Stripping one of them shipped in v1.14.2 and returned
+  // 83 KB of chunk text against a 3 KB budget while the response claimed the
+  // content had been omitted (#257).
   const degraded = accepted.length === 0 && matched.length > 0;
-  const results = degraded
-    ? matched.map(({ full_content: _omitted, ...header }) => header)
-    : accepted;
+  // And the headers themselves are held to the budget the caller asked for:
+  // a `match_count` of 200 makes even a content-free list large. At least one
+  // survives regardless: an empty `results` is the "nothing was found" shape
+  // #254 exists to prevent, and a header row can exceed a very small budget
+  // on its own (#259).
+  const listed = degraded
+    ? (() => {
+        const headerRows = matched.map(
+          ({ full_content: _full, content: _chunk, ...header }) => header,
+        );
+        const fitted = applyByteBudget(headerRows, max_bytes).accepted;
+        return fitted.length > 0 ? fitted : headerRows.slice(0, 1);
+      })()
+    : [];
+  const results = degraded ? listed : accepted;
+  // What is actually being returned, which on a degraded response is the
+  // header list rather than the (empty) content-bearing set.
+  const responseBytes = degraded
+    ? new TextEncoder().encode(JSON.stringify(results)).length
+    : usedBytes;
 
   // Fire-and-forget usage logging (never blocks the response)
   Promise.resolve(supabase.rpc("cerefox_log_usage", {
@@ -388,14 +420,20 @@ Deno.serve(async (req: Request) => {
       project_name: project_name ?? null,
       metadata_filter: metadata_filter ?? null,
       truncated,
-      response_bytes: usedBytes,
+      response_bytes: responseBytes,
       matched: matched.length,
       degraded,
       ...(degraded
         ? {
             note:
               `${matched.length} result(s) matched but none fit max_bytes=${max_bytes}; ` +
-              `content omitted. Raise max_bytes, or fetch one document with cerefox-get-document.`,
+              `content omitted${
+                listed.length < matched.length
+                  ? `, and only ${listed.length} of them are listed here` +
+                    " (the rest did not fit either)"
+                  : ""
+              }. This is NOT an empty result. Raise max_bytes, or fetch one ` +
+              `document with cerefox-get-document.`,
           }
         : {}),
     }),