@remnic/core 9.69.42 → 9.69.44

package/src/recall-navigation-http-glue.ts

@@ -0,0 +1,141 @@
+/**
+ * Recall-navigation HTTP glue (issue #1956) — route body lives here so
+ * access-http.ts stays at its structural ceiling (same seam as
+ * deep-recall-http-glue.ts).
+ *
+ * Input errors map to 400; everything else rethrows to the global 500
+ * handler. Config gating (`recallNavigation.enabled`) lives in the service
+ * and returns a typed `error: "disabled"` refusal — this module only
+ * translates transport shape. Namespace/sessionKey resolution flows through
+ * the caller-supplied `scopeFor` gate so a body-supplied namespace passes
+ * the SAME effective-namespace allow-list as the query string (issue #1850
+ * finding 2), and `authenticatedPrincipal` reaches the service so
+ * authorization derives from the presenting principal, never the
+ * client-supplied sessionKey.
+ */
+
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+import { EngramAccessInputError } from "./access-errors.js";
+import type { EngramAccessService } from "./access-service.js";
+import type { NavigationAction } from "./recall-navigation.js";
+
+type RespondJson = (res: ServerResponse, status: number, payload: unknown) => void;
+type ReadJsonBody = (req: IncomingMessage) => Promise<unknown>;
+
+type ScopeFor = (
+  bodyNamespace?: string,
+  bodySessionKey?: string,
+) => { namespace?: string; sessionKey?: string; authenticatedPrincipal?: string };
+
+const VALID_RELATIONS = [
+  "supports",
+  "contradicts",
+  "elaborates",
+  "causes",
+  "caused_by",
+  "supersedes",
+  "follows",
+  "references",
+  "related",
+] as const;
+
+function optStr(value: unknown): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}
+
+function optInt(value: unknown): number | undefined {
+  if (value === undefined || value === null || value === "") return undefined;
+  const parsed = typeof value === "string" ? Number(value) : value;
+  if (typeof parsed !== "number" || !Number.isInteger(parsed) || parsed < 1) {
+    throw new EngramAccessInputError("limit must be a positive integer");
+  }
+  return parsed;
+}
+
+async function respondNavigation(
+  req: IncomingMessage,
+  res: ServerResponse,
+  respondJson: RespondJson,
+  readJsonBody: ReadJsonBody,
+  service: EngramAccessService,
+  scopeFor: ScopeFor,
+  action: Extract<NavigationAction, "expand" | "traverse">,
+): Promise<void> {
+  const body = (await readJsonBody(req)) as Record<string, unknown>;
+  const memoryId = optStr(body.memoryId);
+  if (memoryId === undefined || memoryId.trim().length === 0) {
+    respondJson(res, 400, { error: "invalid_request", detail: "memoryId is required" });
+    return;
+  }
+  const sessionKey = optStr(body.sessionKey);
+  if (sessionKey === undefined || sessionKey.trim().length === 0) {
+    respondJson(res, 400, { error: "invalid_request", detail: "sessionKey is required" });
+    return;
+  }
+  let disclosure: "chunk" | "section" | "raw" | undefined;
+  let relation: string | undefined;
+  if (action === "expand") {
+    const raw = optStr(body.disclosure);
+    if (raw !== undefined && raw !== "chunk" && raw !== "section" && raw !== "raw") {
+      respondJson(res, 400, { error: "invalid_request", detail: "disclosure must be one of chunk, section, raw" });
+      return;
+    }
+    disclosure = raw;
+  } else {
+    relation = optStr(body.relation);
+    if (relation !== undefined && !(VALID_RELATIONS as readonly string[]).includes(relation)) {
+      respondJson(
+        res,
+        400,
+        { error: "invalid_request", detail: `relation must be one of ${VALID_RELATIONS.join(", ")}` },
+      );
+      return;
+    }
+  }
+  let limit: number | undefined;
+  try {
+    limit = optInt(body.limit);
+  } catch (err) {
+    respondJson(res, 400, { error: "invalid_request", detail: err instanceof Error ? err.message : String(err) });
+    return;
+  }
+  const scope = scopeFor(optStr(body.namespace), sessionKey);
+  const result = await service.recallNavigate({
+    action,
+    memoryId,
+    sessionKey: scope.sessionKey ?? sessionKey,
+    ...(disclosure !== undefined ? { disclosure } : {}),
+    ...(relation !== undefined ? { relation } : {}),
+    ...(limit !== undefined ? { limit } : {}),
+    namespace: scope.namespace,
+    authenticatedPrincipal: scope.authenticatedPrincipal,
+  });
+  const { rendered: _rendered, ...payload } = result;
+  respondJson(res, 200, payload);
+}
+
+export async function maybeRespondRecallNavigation(
+  req: IncomingMessage,
+  res: ServerResponse,
+  pathname: string,
+  method: string | undefined,
+  enforceTokenOp: (op: "memory_expand" | "memory_traverse") => void,
+  respondJson: RespondJson,
+  readJsonBody: ReadJsonBody,
+  service: EngramAccessService,
+  scopeFor: ScopeFor,
+): Promise<boolean> {
+  if (method === "POST" && (pathname === "/engram/v1/memory/expand" || pathname === "/remnic/v1/memory/expand")) {
+    enforceTokenOp("memory_expand");
+    await respondNavigation(req, res, respondJson, readJsonBody, service, scopeFor, "expand");
+    return true;
+  }
+  if (method === "POST" && (pathname === "/engram/v1/memory/traverse" || pathname === "/remnic/v1/memory/traverse")) {
+    enforceTokenOp("memory_traverse");
+    await respondNavigation(req, res, respondJson, readJsonBody, service, scopeFor, "traverse");
+    return true;
+  }
+  return false;
+}
+

package/src/recall-navigation-mcp-tools.ts

@@ -0,0 +1,60 @@
+/**
+ * Recall-navigation MCP tool definitions (issue #1956) — extracted from
+ * access-mcp.ts so the surface file stays at its structural ceiling (same
+ * seam as deep-recall-mcp-tools.ts). Spread back into `this.tools`
+ * (`...RECALL_NAVIGATION_MCP_TOOLS`); the migrated-operation mapping lives
+ * in access-mcp.ts's MCP_MIGRATED_OPERATIONS. The `remnic.` canonical alias
+ * is minted by withToolAliases at tools/list time.
+ *
+ * Gating: spread is conditional on `service.recallNavigationEnabled !== false`
+ * — the flag defaults TRUE, so the check treats an absent property (older
+ * service shape / test stub) as enabled and removes the tools from listing
+ * ONLY on an explicit false. Disabled config therefore yields tools absent
+ * from tools/list, not present-but-erroring.
+ */
+
+import type { McpTool } from "./access-mcp.js";
+
+export const RECALL_NAVIGATION_MCP_TOOLS: McpTool[] = [
+  {
+    name: "engram.memory_expand",
+    description:
+      "Re-render one memory a recall already served to this session at a deeper disclosure level (section or raw). Cheap follow-up — no fresh search. The id must come from this session's recent recall results.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        memoryId: { type: "string", description: "Memory id (or [m:xxxx] handle) served by a recent recall. Required." },
+        sessionKey: { type: "string", description: "Session key whose recent recalls authorize the id. Required." },
+        disclosure: {
+          type: "string",
+          enum: ["section", "raw"],
+          description: "Target depth; must be deeper than the chunk preview already served. Default raw.",
+        },
+        namespace: { type: "string", description: "Caller namespace to scope this operation to." },
+      },
+      required: ["memoryId", "sessionKey"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "engram.memory_traverse",
+    description:
+      "Follow typed links (supports/contradicts/elaborates/causes/caused_by/supersedes/follows/references/related) from a memory a recall already served to this session. Neighbors return as chunk-level summaries, optionally filtered by relation.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        memoryId: { type: "string", description: "Memory id (or [m:xxxx] handle) served by a recent recall. Required." },
+        sessionKey: { type: "string", description: "Session key whose recent recalls authorize the id. Required." },
+        relation: {
+          type: "string",
+          enum: ["supports", "contradicts", "elaborates", "causes", "caused_by", "supersedes", "follows", "references", "related"],
+          description: "Optional relation filter; omitted means every known relation.",
+        },
+        limit: { type: "integer", minimum: 1, description: "Optional cap on returned neighbors (ceiling: recallNavigation.maxNeighbors)." },
+        namespace: { type: "string", description: "Caller namespace to scope this operation to." },
+      },
+      required: ["memoryId", "sessionKey"],
+      additionalProperties: false,
+    },
+  },
+];

package/src/recall-navigation-operations.ts

@@ -0,0 +1,111 @@
+/**
+ * Recall-navigation boundary operations (issue #1956).
+ *
+ * `memory_expand` / `memory_traverse` route MCP, HTTP, and CLI dispatch
+ * through the shared validation + error-mapping layer (access-boundary.ts)
+ * to the single `EngramAccessService.recallNavigate` implementation.
+ * Sibling module so access-operations-batch.ts stays at its ceiling seam
+ * (same layout as deep-recall's extraction).
+ */
+
+import { z } from "zod";
+
+import { defineOperation } from "./access-boundary.js";
+import { EngramAccessInputError } from "./access-errors.js";
+
+function stripNulls(data: unknown): unknown {
+  if (data !== null && typeof data === "object" && !Array.isArray(data)) {
+    const obj = data as Record<string, unknown>;
+    const cleaned: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(obj)) {
+      if (value !== null) cleaned[key] = value;
+    }
+    return cleaned;
+  }
+  return data;
+}
+
+function strictSchema<T extends z.ZodRawShape>(shape: T): z.ZodType<Record<string, unknown>> {
+  return z.preprocess(stripNulls, z.object(shape).passthrough()) as unknown as z.ZodType<Record<string, unknown>>;
+}
+
+const str = z.string().optional();
+
+function optStr(value: unknown): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}
+
+function optInt(value: unknown): number | undefined {
+  if (typeof value === "number") return value;
+  if (typeof value === "string" && Number.isFinite(Number(value))) return Number(value);
+  return undefined;
+}
+
+function reqStr(value: unknown, field: string): string {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new EngramAccessInputError(`${field} is required`);
+  }
+  return value;
+}
+
+const baseShape = {
+  memoryId: z.string(),
+  sessionKey: z.string(),
+  namespace: str,
+};
+
+defineOperation({
+  name: "memory_expand",
+  description: "Re-render one already-served recall result at a deeper disclosure level (chunk → section → raw).",
+  schema: strictSchema({ ...baseShape, disclosure: z.enum(["chunk", "section", "raw"]).optional() }),
+  handler: async (input, ctx) => {
+    const disclosure = optStr(input.disclosure);
+    return {
+      result: await ctx.service.recallNavigate({
+        action: "expand",
+        memoryId: reqStr(input.memoryId, "memoryId"),
+        sessionKey: reqStr(input.sessionKey, "sessionKey"),
+        ...(disclosure === "chunk" || disclosure === "section" || disclosure === "raw" ? { disclosure } : {}),
+        namespace: optStr(input.namespace),
+        authenticatedPrincipal: ctx.authenticatedPrincipal,
+      }),
+    };
+  },
+});
+
+defineOperation({
+  name: "memory_traverse",
+  description:
+    "Follow typed frontmatter links from an already-served recall result; neighbors return as chunk-level summaries.",
+  schema: strictSchema({
+    ...baseShape,
+    relation: z
+      .enum([
+        "supports",
+        "contradicts",
+        "elaborates",
+        "causes",
+        "caused_by",
+        "supersedes",
+        "follows",
+        "references",
+        "related",
+      ])
+      .optional(),
+    limit: z.union([z.number(), z.string()]).optional(),
+  }),
+  handler: async (input, ctx) => {
+    const relation = optStr(input.relation);
+    return {
+      result: await ctx.service.recallNavigate({
+        action: "traverse",
+        memoryId: reqStr(input.memoryId, "memoryId"),
+        sessionKey: reqStr(input.sessionKey, "sessionKey"),
+        ...(relation !== undefined ? { relation } : {}),
+        limit: optInt(input.limit),
+        namespace: optStr(input.namespace),
+        authenticatedPrincipal: ctx.authenticatedPrincipal,
+      }),
+    };
+  },
+});

package/src/recall-navigation-renderer.ts

@@ -0,0 +1,49 @@
+/**
+ * Shared markdown renderer for recall navigation (issue #1956).
+ *
+ * Rule 22: CLI text output, MCP `rendered`, and HTTP human output all
+ * render through this one module — never forked per surface.
+ * Deterministic: items in result order, budget and disclosure spend last.
+ */
+
+import type { RecallNavigationResult } from "./recall-navigation.js";
+
+type NavigationRenderInput = RecallNavigationResult extends infer Result
+  ? Result extends { rendered: string }
+    ? Omit<Result, "rendered">
+    : never
+  : never;
+
+export function renderNavigationResult(result: NavigationRenderInput): string {
+  if (!result.ok) {
+    return ["# Memory navigation", "", `- error: ${result.error}`, `- ${result.message}`, ""].join("\n");
+  }
+  const lines = ["# Memory navigation", ""];
+  lines.push(`- action: ${result.action}`);
+  lines.push(`- memory: ${result.memoryId}`);
+  lines.push(`- namespace: ${result.namespace}`);
+  if (result.items.length === 0) {
+    lines.push("- neighbors: (none)");
+  } else {
+    lines.push("");
+    for (const [index, item] of result.items.entries()) {
+      const via = item.linkType !== undefined ? ` via ${item.linkType}` : "";
+      lines.push(`${index + 1}. **${item.memoryId}** (${item.disclosure}${via})`);
+      if (item.content !== undefined) {
+        lines.push(item.content);
+      } else {
+        lines.push(`   ${item.preview.replace(/\s+/g, " ").trim()}`);
+      }
+    }
+  }
+  lines.push("");
+  lines.push(
+    `- budget: ${result.budget.used}/${result.budget.chars} chars${result.truncated ? " (truncated)" : ""}`,
+  );
+  const spend = result.disclosureSpend;
+  lines.push(
+    `- disclosure spend: chunk=${spend.chunk.estimatedTokens}t, section=${spend.section.estimatedTokens}t, raw=${spend.raw.estimatedTokens}t`,
+  );
+  lines.push("");
+  return lines.join("\n");
+}