@remnic/core 9.69.56 → 9.69.58

package/src/access-errors.ts

@@ -1,3 +1,16 @@
+/**
+ * Tool-surface error enrichment: nearest-tool suggestions and arg-shape hints.
+ *
+ * Each function is a pure message builder — it returns a better error string
+ * without changing semantics, status codes, or rejection behavior.
+ *
+ * @module access-errors
+ */
+
+import type { ZodError } from "zod";
+
+// ─── Existing error classes (restored from pre-#3042) ─────────────────────
+
 /** Authenticated caller lacks the required authorization (HTTP 403). */
 export class EngramAccessForbiddenError extends Error {}
 
@@ -15,9 +28,247 @@ export class NamespaceNotWritableError extends EngramAccessInputError {
   constructor(
     readonly attemptedNamespace: string,
     readonly principal: string | undefined,
-    message?: string
+    message?: string,
   ) {
     super(message ?? `namespace is not writable: ${attemptedNamespace}`);
     this.name = "NamespaceNotWritableError";
   }
 }
+
+// ─── Levenshtein distance ─────────────────────────────────────────────────
+
+/**
+ * Standard Levenshtein edit distance. O(n*m) over bounded inputs.
+ * Exported so the test can verify it without importing private helpers.
+ */
+export function levenshtein(a: string, b: string): number {
+  const an = a.length;
+  const bn = b.length;
+  // Fast paths for empty strings.
+  if (an === 0) return bn;
+  if (bn === 0) return an;
+
+  // Use two rows to keep memory O(min(n,m)).
+  let prev: number[] = [];
+  let curr: number[] = [];
+
+  // Align loops to the shorter string.
+  const [shorter, longer, sn, ln] =
+    an < bn ? [a, b, an, bn] : [b, a, bn, an];
+
+  for (let i = 0; i <= sn; i++) prev[i] = i;
+
+  for (let j = 1; j <= ln; j++) {
+    curr[0] = j;
+    for (let i = 1; i <= sn; i++) {
+      const cost = shorter[i - 1] === longer[j - 1] ? 0 : 1;
+      curr[i] = Math.min(
+        prev[i] + 1,       // deletion
+        curr[i - 1] + 1,   // insertion
+        prev[i - 1] + cost, // substitution
+      );
+    }
+    [prev, curr] = [curr, prev];
+  }
+  return prev[sn];
+}
+
+// ─── Similar-name helpers ─────────────────────────────────────────────────
+
+const SUGGESTION_DISTANCE_CAP = 3;
+/**
+ * Upper bound on the requested tool name. Anything longer is rejected before
+ * the O(n*m) Levenshtein pass (#3042 review, P2): a 128 KB request over ~30
+ * tools would otherwise run hundreds of millions of comparisons and block
+ * the server event loop. The repo documents 64 chars as the tool-name shape;
+ * this matches the limit enforced by every published surface.
+ */
+export const SUGGESTION_REQUEST_MAX_LEN = 64;
+
+export interface SuggestionCandidate {
+  name: string;
+  distance: number;
+}
+
+/**
+ * Find the nearest registered tool names by Levenshtein distance.
+ * Results are sorted by distance ascending then name ascending (deterministic).
+ * Only names with distance <= {@link SUGGESTION_DISTANCE_CAP} are returned;
+ * when no name is that close the caller falls back to listing the full set.
+ */
+export function nearestSuggestions(
+  requested: string,
+  registeredNames: readonly string[],
+): SuggestionCandidate[] {
+  // Defense in depth: the entry point already caps; this guards any direct
+  // caller of the helper from an unbounded Levenshtein pass (issue #3042).
+  if (requested.length > SUGGESTION_REQUEST_MAX_LEN) return [];
+  const candidates: SuggestionCandidate[] = [];
+  for (const name of registeredNames) {
+    const distance = levenshtein(requested.toLowerCase(), name.toLowerCase());
+    if (distance <= SUGGESTION_DISTANCE_CAP) {
+      candidates.push({ name, distance });
+    }
+  }
+  // Total comparator: distance asc, then name asc.
+  candidates.sort((a, b) => {
+    if (a.distance !== b.distance) return a.distance < b.distance ? -1 : 1;
+    return a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
+  });
+  return candidates;
+}
+
+/**
+ * Build a human-readable "did you mean?" suggestion string.
+ * When no close match is found, returns a fallback listing.
+ */
+function buildSuggestion(
+  requested: string,
+  registeredNames: readonly string[],
+): string {
+  const suggestions = nearestSuggestions(requested, registeredNames);
+  if (suggestions.length === 0) {
+    return `Registered tools: ${registeredNames.join(", ")}`;
+  }
+  return `Did you mean ${suggestions.map((s) => s.name).join(", ")}?`;
+}
+
+/**
+ * Read a Zod type tag without asserting a shape.
+ *
+ * Zod keeps its discriminant at `_def.typeName`. Both hops are narrowed with
+ * `in`/`typeof` rather than an inline cast, so a non-Zod object yields
+ * `undefined` instead of a fabricated read.
+ */
+function zodTypeName(schema: unknown): string | undefined {
+  if (typeof schema !== "object" || schema === null || !("_def" in schema)) return undefined;
+  const def = schema._def;
+  if (typeof def !== "object" || def === null || !("typeName" in def)) return undefined;
+  return typeof def.typeName === "string" ? def.typeName : undefined;
+}
+
+/** Read `_def.<key>` with the same narrowing discipline. */
+function zodDefField(schema: unknown, key: string): unknown {
+  if (typeof schema !== "object" || schema === null || !("_def" in schema)) return undefined;
+  const def = schema._def;
+  if (typeof def !== "object" || def === null) return undefined;
+  return Object.hasOwn(def, key) ? (def as Record<string, unknown>)[key] : undefined;
+}
+
+/**
+ * Reverse-engineer ONE synthetic example value from a Zod schema type.
+ * Returns a deterministic placeholder intended to round-trip through parse().
+ */
+function exampleFromSchema(schema: unknown): unknown {
+  switch (zodTypeName(schema)) {
+    case "ZodString":
+      return "<string>";
+    case "ZodNumber":
+      return 42;
+    case "ZodBoolean":
+      return true;
+    case "ZodNullable":
+      return null;
+    case "ZodArray":
+      return [];
+    case "ZodOptional":
+      // Optional fields are omitted from the example rather than sent as null.
+      return undefined;
+    case "ZodEnum": {
+      const values = zodDefField(schema, "values");
+      return Array.isArray(values) && values.length > 0 ? values[0] : "<value>";
+    }
+    case "ZodObject": {
+      const shapeFn = zodDefField(schema, "shape");
+      const shape = typeof shapeFn === "function" ? shapeFn() : undefined;
+      if (typeof shape !== "object" || shape === null) return {};
+      const result: Record<string, unknown> = {};
+      for (const key of Object.getOwnPropertyNames(shape)) {
+        if (!Object.hasOwn(shape, key)) continue;
+        const field = (shape as Record<string, unknown>)[key];
+        const value = exampleFromSchema(field);
+        if (value !== undefined) result[key] = value;
+      }
+      return result;
+    }
+    default:
+      return undefined;
+  }
+}
+/**
+ * Build an enriched "unknown tool" error message.
+ *
+ * @param requested - the tool name the caller used
+ * @param registeredNames - ALL registered tool names (including aliases)
+ */
+export function unknownToolError(
+  requested: string,
+  registeredNames: readonly string[],
+): string {
+  // Cap the request before the suggestion pass: a 128 KB name would otherwise
+  // pay O(n*m) per registered tool (issue #3042 review, P2). The cap matches
+  // the documented tool-name shape; an over-long request is rejected with a
+  // teaching message rather than a silent truncate.
+  if (requested.length > SUGGESTION_REQUEST_MAX_LEN) {
+    return `Unknown tool: name exceeds ${SUGGESTION_REQUEST_MAX_LEN} characters (got ${requested.length}).`;
+  }
+  const suggestion = buildSuggestion(requested, registeredNames);
+  return `Unknown tool: ${requested}. ${suggestion}`;
+}
+
+/**
+ * Build an enriched "invalid arguments" error message.
+ *
+ * The example is generated from the schema (never hand-written, so it cannot
+ * drift) and is shown ONLY when it round-trips through that same schema. It
+ * carries schema-derived fields only: injecting the tool name would add an
+ * unrecognized property and fail a `.strict()` object (#3035 review finding).
+ *
+ * @param tool - the tool name that received the invalid args
+ * @param zodError - the ZodError from parse()
+ * @param schema - the original Zod schema, used to generate the example
+ */
+export function invalidArgsError(
+  tool: string,
+  zodError: ZodError,
+  schema?: unknown,
+): string {
+  const issues = zodError.issues.map((issue) => {
+    const path = issue.path.length > 0 ? issue.path.join(".") : "(root)";
+    // `expected` exists only on the invalid_type / invalid_literal variants of
+    // ZodIssue, so it is read through a presence check rather than assumed.
+    const expected = "expected" in issue ? issue.expected : undefined;
+    return expected === undefined
+      ? `${path}: ${issue.message}`
+      : `${path}: ${issue.message} (expected ${String(expected)})`;
+  });
+  let message = `Invalid arguments for "${tool}": ${issues.join("; ")}`;
+  if (!schema) return message;
+
+  const example = exampleFromSchema(schema);
+  if (!example || typeof example !== "object" || Object.keys(example).length === 0) {
+    return message;
+  }
+
+  // Withhold an example that cannot parse against its own schema: a
+  // non-round-tripping example is misinformation, worse than none. Narrowed
+  // with `in`/`typeof` rather than an inline cast so the shape is checked.
+  let roundTrips = false;
+  if (typeof schema === "object" && "safeParse" in schema) {
+    const parser = schema.safeParse;
+    if (typeof parser === "function") {
+      try {
+        const parsed: unknown = parser.call(schema, example);
+        roundTrips =
+          typeof parsed === "object"
+          && parsed !== null
+          && "success" in parsed
+          && parsed.success === true;
+      } catch {
+        roundTrips = false;
+      }
+    }
+  }
+
+  return roundTrips ? `${message}. Example arguments: ${JSON.stringify(example)}` : message;
+}

package/src/access-http.ts

@@ -52,6 +52,10 @@ import { resolveQueryNamespaceWritablePreflight } from "./access-namespace-prefl
 import { respondAccessCapabilitiesHttp } from "./access-http-lcm-compaction.js";
 import { respondBriefingHttp } from "./access-http-briefing.js";
 import { handleWhoKnowsHttpQuery } from "./who-knows.js";
+import {
+  handleRecallWhyHttpQuery,
+  handleRecallXrayHttpQuery,
+} from "./access-recall-diagnostics.js";
 import {
   assertOperationAllowed,
   capabilityAllowsOp,
@@ -1503,111 +1507,40 @@ export class EngramAccessHttpServer extends ReviewDeckAccessHttpBase {
       return;
     }
 
-    // Recall X-ray (issue #570 PR 4): unified per-result attribution
-    // snapshot.  Requires bearer auth (same as every other endpoint
-    // here) and enforces namespace scope before the recall fires
-    // (CLAUDE.md rule 42).  Query comes from the `q` search param so
-    // GET stays cacheable; `namespace` / `session` / `budget` are
-    // optional.
+    // Recall diagnostics (issues #570, #3033). Bearer auth is enforced by
+    // the surrounding handler and namespace scope is enforced inside the
+    // service before the recall fires (rule 42). Both routes are thin: param
+    // parsing and 400 mapping live in access-recall-diagnostics.ts, which
+    // keeps them unit-testable without booting an HTTP server.
+    //
+    // `xray` explains the results a recall DID return; `why` explains the
+    // ones it did not. Query comes from `q` so GET stays cacheable.
     if (req.method === "GET" && pathname === "/engram/v1/recall/xray") {
       this.enforceTokenOp("recall_xray"); // boundary dispatch (issue #1525)
-      const queryParam = parsed.searchParams.get("q");
-      if (!queryParam || queryParam.trim().length === 0) {
-        this.respondJson(res, 400, {
-          error: "missing_query",
-          code: "missing_query",
-          message: "q search parameter is required and must be non-empty",
-        });
-        return;
-      }
-      const sessionParam = parsed.searchParams.get("session");
-      const sessionKey = sessionParam && sessionParam.length > 0
-        ? sessionParam
-        : undefined;
-      const namespaceParam = parsed.searchParams.get("namespace");
-      const namespace = this.resolveNamespace(
-        req,
-        namespaceParam && namespaceParam.length > 0
-          ? namespaceParam
-          : undefined,
-      );
-      const budgetParam = parsed.searchParams.get("budget");
-      // Reject invalid `budget` with 400 rather than silently
-      // defaulting (CLAUDE.md rules 14 + 51).
-      let budget: number | undefined;
-      if (budgetParam !== null && budgetParam !== "") {
-        const parsedBudget = Number(budgetParam);
-        if (
-          !Number.isFinite(parsedBudget)
-          || parsedBudget <= 0
-          || !Number.isInteger(parsedBudget)
-        ) {
-          this.respondJson(res, 400, {
-            error: "invalid_budget",
-            code: "invalid_budget",
-            message:
-              "budget expects a positive integer",
-          });
-          return;
-        }
-        budget = parsedBudget;
-      }
-      // Disclosure depth (issue #677 PR 3/4 telemetry plumbing).  When
-      // present, must match the chunk|section|raw allow-list; invalid
-      // values surface as a 400 (CLAUDE.md rule 51 — no silent
-      // fallback) rather than silently disabling the per-disclosure
-      // summary table.
-      const disclosureParam = parsed.searchParams.get("disclosure");
-      let disclosure: RecallDisclosure | undefined;
-      if (disclosureParam !== null && disclosureParam.length > 0) {
-        if (!isRecallDisclosure(disclosureParam)) {
-          this.respondJson(res, 400, {
-            error: "invalid_disclosure",
-            code: "invalid_disclosure",
-            message:
-              "disclosure must be one of: chunk, section, raw",
-          });
-          return;
-        }
-        disclosure = disclosureParam;
-      }
-      // Only translate validation errors (empty query, bad budget)
-      // into 400s.  Backend faults (timeouts, storage errors,
-      // unexpected orchestrator failures) must bubble to the global
-      // `handle()` error handler so they return 500 and get logged
-      // properly.  `service.recallXray` prefixes its validation
-      // errors with "recallXray:" so we key off that prefix rather
-      // than catching everything.
-      let payload: Awaited<ReturnType<typeof this.service.recallXray>>;
-      try {
-        payload = await this.service.recallXray({
-          query: queryParam,
-          sessionKey,
-          namespace,
-          budget,
-          authenticatedPrincipal: this.resolveRequestPrincipal(req),
-          sourceConnector: this.resolveConnector(req),
-          ...(disclosure !== undefined ? { disclosure } : {}),
-        });
-      } catch (err) {
-        // Only surface the message for the deliberately-prefixed recallXray
-        // input-validation errors, and only when it is a real Error.message —
-        // never String(err) of an arbitrary throw, which CodeQL flags as
-        // stack-trace exposure (js/stack-trace-exposure). Validation errors are
-        // always thrown as Error instances (see access-service.ts), so this is
-        // behavior-preserving; anything else is a server-side fault and is
-        // rethrown so the outer `handle()` catch returns 500 + logs it.
-        if (err instanceof Error && err.message.startsWith("recallXray:")) {
-          this.respondJson(res, 400, {
-            error: "invalid_request",
-            code: "invalid_request",
-            message: err.message,
-          });
-          return;
-        }
-        throw err;
-      }
-      this.respondJson(res, 200, payload);
+      const outcome = await handleRecallXrayHttpQuery({
+        getParam: (name) => parsed.searchParams.get(name),
+        resolveNamespace: (namespace) => this.resolveNamespace(req, namespace),
+        principal: this.resolveRequestPrincipal(req),
+        connector: this.resolveConnector(req),
+        run: (request) => this.service.recallXray(request),
+      });
+      this.respondJson(res, outcome.status, outcome.body);
+      return;
+    }
+
+    if (
+      req.method === "GET"
+      && (pathname === "/engram/v1/recall/why" || pathname === "/remnic/v1/recall/why")
+    ) {
+      this.enforceTokenOp("recall_why"); // boundary dispatch (issue #1525)
+      const outcome = await handleRecallWhyHttpQuery({
+        getParam: (name) => parsed.searchParams.get(name),
+        resolveNamespace: (namespace) => this.resolveNamespace(req, namespace),
+        principal: this.resolveRequestPrincipal(req),
+        connector: this.resolveConnector(req),
+        run: (request) => this.service.recallWhy(request),
+      });
+      this.respondJson(res, outcome.status, outcome.body);
       return;
     }
 

package/src/access-mcp-output-schemas.ts

@@ -111,6 +111,7 @@ const TOOL_OUTPUT_SCHEMAS: Readonly<Record<string, Record<string, unknown>>> = {
   }),
   recall_tier_explain: objectSchema({ snapshotFound: T_BOOLEAN, tierExplain: T_NULLABLE_OBJECT }),
   recall_xray: objectSchema({ snapshotFound: T_BOOLEAN, snapshot: T_OBJECT }),
+  recall_why: objectSchema({ reportFound: T_BOOLEAN, report: T_OBJECT, summary: T_STRING }),
   who_knows: objectSchema({ topic: T_STRING, results: T_ARRAY }),
   promotion_candidates: objectSchema({ namespace: T_STRING, targetNamespace: T_STRING, candidates: T_ARRAY }),
   set_coding_context: objectSchema({ ok: T_BOOLEAN }),

package/src/access-mcp.ts

@@ -23,6 +23,7 @@ import {
   validateRequest,
 } from "./access-schema.js";
 import { EngramAccessInputError, type EngramAccessRecallResponse, type EngramAccessService } from "./access-service.js";
+import { unknownToolError } from "./access-errors.js";
 import "./access-operations.js";
 import { validateBriefingFormat } from "./briefing.js";
 import { processChatMessage } from "./chat/chat-factory.js";
@@ -55,6 +56,7 @@ import { MCP_READ_ONLY_TOOL_SUFFIXES } from "./mcp-read-only-tools.js";
 import { MEETINGS_MCP_TOOLS } from "./meetings/mcp-tools.js"; import { DEEP_RECALL_MCP_TOOLS } from "./deep-recall-mcp-tools.js"; import { RECALL_NAVIGATION_MCP_TOOLS } from "./recall-navigation-mcp-tools.js"; import { MEMORY_BROWSE_MCP_TOOLS } from "./memory-browse-mcp-tools.js";
 import { WEARABLES_MCP_TOOLS } from "./wearables/mcp-tools.js";
 import { WHO_KNOWS_MCP_TOOLS } from "./who-knows.js"; import { LOCATION_MCP_TOOLS } from "./location/mcp-tools.js"; import { STANDUP_MCP_TOOLS } from "./standup/mcp-tools.js";
+import { RECALL_WHY_MCP_TOOLS } from "./access-recall-diagnostics.js";
 import { PROMOTION_CANDIDATES_MCP_TOOLS } from "./memory-subject.js";
 import { EXTERNAL_WIKI_MCP_TOOLS } from "./external-wiki-mcp-tools.js";
 import { abortError, isAbortError } from "./abort-error.js";
@@ -169,7 +171,7 @@ export const MCP_MIGRATED_OPERATIONS: Readonly<Record<string, OperationName>> =
   "engram.recall": "recall",
   "engram.recall_explain": "recall_explain",
   "engram.set_coding_context": "set_coding_context", "engram.recall_tier_explain": "recall_tier_explain",
-  "engram.recall_xray": "recall_xray", "engram.who_knows": "who_knows", "engram.promotion_candidates": "promotion_candidates",
+  "engram.recall_xray": "recall_xray", "engram.recall_why": "recall_why", "engram.who_knows": "who_knows", "engram.promotion_candidates": "promotion_candidates",
   "engram.wearables_status": "wearables_status", "engram.wearables_sync": "wearables_sync",
   "engram.location_status": "location_status", "engram.location_check": "location_check", "engram.location_sync": "location_sync",
   "engram.location_backfill": "location_backfill", "engram.location_day": "location_day",
@@ -689,6 +691,7 @@ export class EngramMcpServer {
         },
       },
       ...WEARABLES_MCP_TOOLS, ...MEETINGS_MCP_TOOLS, ...WHO_KNOWS_MCP_TOOLS, ...PROMOTION_CANDIDATES_MCP_TOOLS, ...LOCATION_MCP_TOOLS, ...STANDUP_MCP_TOOLS, ...DEEP_RECALL_MCP_TOOLS, ...(service.recallNavigationEnabled !== false ? RECALL_NAVIGATION_MCP_TOOLS : []), ...MEMORY_BROWSE_MCP_TOOLS,
+      ...RECALL_WHY_MCP_TOOLS,
       ...(service.supportPassportEnabled ? SUPPORT_PASSPORT_MCP_TOOLS : []),
       {
         name: "engram.action_confidence",
@@ -2589,7 +2592,23 @@ export class EngramMcpServer {
   ): Promise<unknown> {
     const migrated = MCP_MIGRATED_OPERATIONS[toLegacyToolName(name)];
     if (!migrated) {
-      throw new Error(`unknown tool: ${name}`);
+      // Teaching rejection (#3035): name the nearest registered tool instead
+      // of a bare "unknown tool". Semantics are unchanged — this still throws
+      // and never executes a guessed correction.
+      //
+      // Candidates are the SAME capability-filtered set `tools/list` shows
+      // (issue #1850 finding 3). Enumerating the global map here would let a
+      // scoped or deny-all token recover the full tool surface through the
+      // error path, re-opening the leak that fix closed.
+      const caps = tokenCapabilityStore.getStore();
+      const visible = this.tools
+        .filter(
+          (t) =>
+            caps?.ops === undefined
+            || capabilityAllowsOp(caps, MCP_MIGRATED_OPERATIONS[toLegacyToolName(t.name)] ?? ""),
+        )
+        .map((t) => t.name);
+      throw new Error(unknownToolError(name, visible));
     }
     const op = getOperation(migrated);
     if (!op) {

package/src/access-operations-batch.ts

@@ -152,6 +152,14 @@ defineOperation({ name: "recall_xray", description: "X-ray recall.", schema: str
     return { result: await ctx.service.recallXray({ query: defStr(input.query, ""), sessionKey: optStr(input.sessionKey), namespace: optStr(input.namespace), budget, authenticatedPrincipal: ctx.authenticatedPrincipal, sourceConnector: ctx.sourceConnector, ...(dr && dr !== "" ? { disclosure: dr as RecallDisclosure } : {}), ...(ctx.abortSignal ? { abortSignal: ctx.abortSignal } : {}) }) };
   },
 });
+defineOperation({ name: "recall_why", description: "Diagnose why a query did not recall an expected memory (#3033). Read-only.", schema: strictSchema({ query: S.str, expect: S.str, sessionKey: S.str, namespace: S.str }),
+  handler: async (input, ctx) => {
+    // A supplied-but-blank `expect` is a caller mistake: forward it so the
+    // service rejects it, matching the HTTP route's 400 (checklist #39).
+    const expect = optStr(input.expect);
+    return { result: await ctx.service.recallWhy({ query: defStr(input.query, ""), ...(expect !== undefined ? { expect } : {}), sessionKey: optStr(input.sessionKey), namespace: optStr(input.namespace), authenticatedPrincipal: ctx.authenticatedPrincipal, sourceConnector: ctx.sourceConnector, ...(ctx.abortSignal ? { abortSignal: ctx.abortSignal } : {}) }) };
+  },
+});
 defineOperation({ name: "who_knows", description: "Rank entities by demonstrated expertise for a topic (#2057).", schema: strictSchema({ topic: S.str, limit: S.flexNum, namespace: S.str }),
   handler: async (input, ctx) => {
     const topic = defStr(input.topic, "");