@rubytech/create-realagent 1.0.678 → 1.0.681

package/payload/platform/lib/graph-mcp/src/cypher-validate.ts

@@ -0,0 +1,157 @@
+/**
+ * Cypher schema validation for the graph-mcp proxy (Task 654).
+ *
+ * Tokenises a cypher string for labels (`:Label`) and relationship types
+ * (`[:REL_TYPE]`, including `[r:TYPE]`, `[:TYPE*1..5]`, `[:A|B]`) and checks
+ * each against a schema snapshot. Unknown tokens are returned with the
+ * Levenshtein-nearest known tokens of the same kind as suggestions.
+ *
+ * Design posture:
+ *   - Defence layer, not a cypher correctness gate. Pass-through on any
+ *     unparseable pattern — Neo4j remains the syntax authority.
+ *   - Empty schema snapshot (cache not ready, or Neo4j unreachable at boot)
+ *     fails OPEN: ok=true, no rejections. The boot-race treatment is a
+ *     deliberate choice — refusing all cypher would wedge the admin agent
+ *     harder than the typo class this layer prevents. The caller emits
+ *     `validated=false` on the existing [graph-query] line so operators
+ *     still see the bypass.
+ *   - String literals are stripped before tokenisation to avoid matching
+ *     `:Foo` inside quoted content (e.g. `WHERE n.note CONTAINS ':Foo'`).
+ */
+
+export interface SchemaSnapshot {
+  readonly labels: ReadonlySet<string>;
+  readonly relationshipTypes: ReadonlySet<string>;
+}
+
+export interface UnknownToken {
+  token: string;
+  kind: "label" | "relationship";
+  nearest: string[];
+  hint: string;
+}
+
+export interface ValidationResult {
+  ok: boolean;
+  unknown: UnknownToken[];
+  labelTokens: string[];
+  edgeTokens: string[];
+}
+
+// Bracket content containing a type reference. Examples this matches:
+//   [:PART_OF]
+//   [r:PART_OF]
+//   [:PART_OF*1..5]
+//   [r:PART_OF*]
+//   [:A|B]
+// The captured group is the TYPE(|TYPE)* alternation; the consumer splits it.
+const EDGE_PATTERN = /\[[^\]]*?:([A-Z_][A-Za-z0-9_]*(?:\|[A-Z_][A-Za-z0-9_]*)*)[^\]]*?\]/g;
+
+// Label reference in a node pattern. Applied to a remainder string that has
+// already had edge-bracket substrings stripped, so there is no overlap with
+// the edge pattern. The [A-Z] anchor excludes lowercase map keys.
+const LABEL_PATTERN = /:([A-Z][A-Za-z0-9_]*)/g;
+
+function stripStringLiterals(cypher: string): string {
+  // Replace single- and double-quoted literals with empty quotes. Preserves
+  // positional structure without retaining content that could match the
+  // label regex (e.g. ':SomeLabel' inside a string).
+  return cypher.replace(/'[^']*'|"[^"]*"/g, '""');
+}
+
+function extractTokens(cypher: string): { labels: Set<string>; edges: Set<string> } {
+  const cleaned = stripStringLiterals(cypher);
+  const edges = new Set<string>();
+  let match: RegExpExecArray | null;
+  const edgePattern = new RegExp(EDGE_PATTERN.source, EDGE_PATTERN.flags);
+  while ((match = edgePattern.exec(cleaned)) !== null) {
+    for (const type of match[1].split("|")) {
+      const clean = type.trim();
+      if (clean) edges.add(clean);
+    }
+  }
+  const remainder = cleaned.replace(edgePattern, "");
+  const labels = new Set<string>();
+  const labelPattern = new RegExp(LABEL_PATTERN.source, LABEL_PATTERN.flags);
+  while ((match = labelPattern.exec(remainder)) !== null) {
+    labels.add(match[1]);
+  }
+  return { labels, edges };
+}
+
+function levenshtein(a: string, b: string): number {
+  if (a === b) return 0;
+  if (a.length === 0) return b.length;
+  if (b.length === 0) return a.length;
+  let prev = new Array<number>(b.length + 1);
+  let curr = new Array<number>(b.length + 1);
+  for (let j = 0; j <= b.length; j++) prev[j] = j;
+  for (let i = 1; i <= a.length; i++) {
+    curr[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[j] = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
+    }
+    [prev, curr] = [curr, prev];
+  }
+  return prev[b.length];
+}
+
+function nearestMatches(
+  token: string,
+  known: ReadonlySet<string>,
+  limit = 3,
+): string[] {
+  if (known.size === 0) return [];
+  const scored: Array<[string, number]> = [];
+  for (const k of known) scored.push([k, levenshtein(token, k)]);
+  scored.sort((a, b) => a[1] - b[1] || a[0].localeCompare(b[0]));
+  return scored.slice(0, limit).map(([k]) => k);
+}
+
+function hintFor(
+  token: string,
+  kind: "label" | "relationship",
+  nearest: string[],
+): string {
+  const didYouMean = nearest.length > 0 ? `Did you mean :${nearest[0]}? ` : "";
+  return `${didYouMean}Unknown ${kind} '${token}' — not in the current Neo4j schema. See .docs/neo4j.md for the canonical taxonomy.`;
+}
+
+export function validate(
+  cypher: string,
+  snapshot: SchemaSnapshot,
+): ValidationResult {
+  const { labels, edges } = extractTokens(cypher);
+  // Fail-open when the snapshot is empty. An empty snapshot means "schema
+  // cache not loaded" (boot race, Neo4j unreachable). Rejecting every token
+  // would wedge the admin agent; letting it through preserves the observable
+  // `validated=false` signal on the existing [graph-query] line.
+  if (snapshot.labels.size === 0 && snapshot.relationshipTypes.size === 0) {
+    return {
+      ok: true,
+      unknown: [],
+      labelTokens: [...labels],
+      edgeTokens: [...edges],
+    };
+  }
+  const unknown: UnknownToken[] = [];
+  for (const token of labels) {
+    if (!snapshot.labels.has(token)) {
+      const nearest = nearestMatches(token, snapshot.labels);
+      unknown.push({ token, kind: "label", nearest, hint: hintFor(token, "label", nearest) });
+    }
+  }
+  for (const token of edges) {
+    if (!snapshot.relationshipTypes.has(token)) {
+      const nearest = nearestMatches(token, snapshot.relationshipTypes);
+      unknown.push({ token, kind: "relationship", nearest, hint: hintFor(token, "relationship", nearest) });
+    }
+  }
+  return {
+    ok: unknown.length === 0,
+    unknown,
+    labelTokens: [...labels],
+    edgeTokens: [...edges],
+  };
+}

package/payload/platform/lib/graph-mcp/src/index.ts

@@ -28,6 +28,8 @@ import { accessSync, appendFileSync, constants, mkdirSync, readFileSync, statSyn
 import { resolve } from "node:path";
 import { StringDecoder } from "node:string_decoder";
 import { initStderrTee } from "../../mcp-stderr-tee/dist/index.js";
+import { validate as validateCypher, type UnknownToken } from "./cypher-validate.js";
+import { SchemaCache, neo4jSchemaFetcher } from "./schema-cache.js";
 
 const SERVER_NAME = "graph";
 const UPSTREAM_PACKAGE = "mcp-neo4j-cypher@0.6.0";
@@ -179,6 +181,38 @@ console.error(
     `namespace=${namespace} readOnly=${readOnly} tokenLimit=${responseTokenLimit}`,
 );
 
+// Task 654 — async schema cache. The validator fails OPEN until the first
+// refresh resolves; all cypher calls during that window are forwarded
+// unvalidated and the existing [graph-query] line gains `validated=false`
+// so operators see the bypass. One Neo4j driver is shared across refreshes;
+// loaded lazily so test harnesses can exercise SchemaCache without pulling
+// neo4j-driver into the module graph.
+// neo4jUri is narrowed to `string` by the guard throw above, but the narrow
+// doesn't flow into the closure below. Pin it to a local const whose type
+// is `string` by construction.
+const resolvedNeo4jUri: string = neo4jUri;
+let schemaFetcherReady: Promise<Awaited<ReturnType<typeof neo4jSchemaFetcher>>> | null = null;
+function getSchemaFetcher(): Promise<Awaited<ReturnType<typeof neo4jSchemaFetcher>>> {
+  if (!schemaFetcherReady) {
+    schemaFetcherReady = neo4jSchemaFetcher(resolvedNeo4jUri, neo4jUser, neo4jPassword);
+  }
+  return schemaFetcherReady;
+}
+const schemaCache = new SchemaCache({
+  async labels() {
+    const f = await getSchemaFetcher();
+    return f.labels();
+  },
+  async relationshipTypes() {
+    const f = await getSchemaFetcher();
+    return f.relationshipTypes();
+  },
+});
+void schemaCache.start().catch((err) => {
+  const msg = err instanceof Error ? err.message : String(err);
+  console.error(`[schema-cache] start failed error="${msg.replace(/"/g, "'")}"`);
+});
+
 const uvx = resolveUvxPath();
 if (!uvx.path) {
   syncEmit(
@@ -216,12 +250,18 @@ child.stderr.on("data", (chunk: Buffer) => {
   process.stderr.write(chunk);
 });
 
-// --- JSON-RPC call correlation ---
-// tools/call is the only method we time; initialize and tools/list are noise.
+// --- JSON-RPC call correlation + validation (Task 654) ---
+// tools/call is the only method we time or validate. For read/write cypher
+// calls, the line is validated against the schema cache before forwarding.
+// Write-path rejection: synthesised MCP tool-error response on stdout, NOT
+// forwarded. Read-path rejection: forwarded, with warnings appendix prepended
+// to response.content[0].text.
 interface PendingCall {
   method: string;
   cypherPrefix: string | null;
   startMs: number;
+  validated: boolean;
+  readWarnings: UnknownToken[];
 }
 const pending = new Map<string | number, PendingCall>();
 
@@ -235,18 +275,29 @@ function stripNamespace(toolName: string | undefined): string {
   return toolName.startsWith(prefix) ? toolName.slice(prefix.length) : toolName;
 }
 
+const READ_CYPHER_TOOL = "read_neo4j_cypher";
+const WRITE_CYPHER_TOOL = "write_neo4j_cypher";
+
 type JsonRpcMessage = {
+  jsonrpc?: string;
   id?: string | number;
   method?: string;
   params?: { name?: string; arguments?: Record<string, unknown> };
-  result?: { content?: Array<{ text?: string; type?: string }> };
+  result?: {
+    content?: Array<{ text?: string; type?: string }>;
+    isError?: boolean;
+  };
   error?: { message?: string; code?: number };
 };
 
-function extractCypher(args: Record<string, unknown> | undefined): string | null {
+function extractCypherFull(args: Record<string, unknown> | undefined): string | null {
   if (!args) return null;
   const q = args["query"] ?? args["cypher"];
-  return typeof q === "string" ? truncate(q.replace(/\s+/g, " ").trim(), 80) : null;
+  return typeof q === "string" ? q : null;
+}
+
+function truncateForLog(cypher: string): string {
+  return truncate(cypher.replace(/\s+/g, " ").trim(), 80);
 }
 
 function countRows(result: JsonRpcMessage["result"]): string {
@@ -257,72 +308,221 @@ function countRows(result: JsonRpcMessage["result"]): string {
   return String(result.content.length);
 }
 
-function onRequestLine(line: string): void {
+/**
+ * Render the admin-facing rejection or warnings text. Plain prose so the
+ * agent's Tool Failure Discipline reads it the same way it reads any tool
+ * error — no special-case structured JSON parser required.
+ */
+function renderUnknownTokens(
+  unknown: UnknownToken[],
+  mode: "rejected" | "warning",
+): string {
+  const heading = mode === "rejected"
+    ? "schema-validation rejected — cypher NOT executed"
+    : "schema-validation warning — cypher executed but referenced unknown tokens";
+  const lines = unknown.map((u) => {
+    const nearest = u.nearest.length > 0 ? ` nearest=[${u.nearest.join(", ")}]` : "";
+    return `  - ${u.kind} '${u.token}':${nearest} — ${u.hint}`;
+  });
+  return `${heading}\n${lines.join("\n")}`;
+}
+
+function synthesiseRejection(id: string | number, unknown: UnknownToken[]): string {
+  const text = `${renderUnknownTokens(unknown, "rejected")}\n\nFix the token names, or if the schema has just changed, invoke ${namespace}_get_neo4j_schema to refresh your view.`;
+  const envelope = {
+    jsonrpc: "2.0",
+    id,
+    result: {
+      content: [{ type: "text", text }],
+      isError: true,
+    },
+  };
+  return JSON.stringify(envelope);
+}
+
+function wrapReadWarnings(msg: JsonRpcMessage, warnings: UnknownToken[]): string {
+  const warningText = `${renderUnknownTokens(warnings, "warning")}\n\n--- results below (executed despite unknown tokens) ---\n`;
+  const original = msg.result?.content ?? [];
+  const wrapped: JsonRpcMessage = {
+    ...msg,
+    result: {
+      ...(msg.result ?? {}),
+      content: [{ type: "text", text: warningText }, ...original],
+    },
+  };
+  return JSON.stringify(wrapped);
+}
+
+type RequestDecision = "forward" | "intercepted";
+
+function handleRequestLine(line: string): RequestDecision {
+  let msg: JsonRpcMessage;
   try {
-    const msg = JSON.parse(line) as JsonRpcMessage;
-    if (msg.method === "tools/call" && msg.id !== undefined) {
-      pending.set(msg.id, {
-        method: stripNamespace(msg.params?.name),
-        cypherPrefix: extractCypher(msg.params?.arguments),
-        startMs: Date.now(),
-      });
-    }
+    msg = JSON.parse(line) as JsonRpcMessage;
   } catch {
-    // Non-JSON / partial line — forward untouched, don't log.
+    return "forward";
+  }
+  if (msg.method !== "tools/call" || msg.id === undefined) return "forward";
+
+  const methodName = stripNamespace(msg.params?.name);
+  const cypherFull = extractCypherFull(msg.params?.arguments);
+  const cypherPrefix = cypherFull ? truncateForLog(cypherFull) : null;
+  const isCypherCall =
+    methodName === READ_CYPHER_TOOL || methodName === WRITE_CYPHER_TOOL;
+
+  const entry: PendingCall = {
+    method: methodName,
+    cypherPrefix,
+    startMs: Date.now(),
+    validated: false,
+    readWarnings: [],
+  };
+
+  if (!isCypherCall || !cypherFull) {
+    pending.set(msg.id, entry);
+    return "forward";
   }
+
+  const isWrite = methodName === WRITE_CYPHER_TOOL;
+  const snapshot = schemaCache.snapshot();
+  const cacheReady = schemaCache.ready();
+
+  if (!cacheReady) {
+    console.error(
+      `[cypher-validate] tool=${isWrite ? "write" : "read"} outcome=skipped reason=cache-not-ready cypher="${(cypherPrefix ?? "").replace(/"/g, "'")}"`,
+    );
+    pending.set(msg.id, entry);
+    return "forward";
+  }
+
+  const result = validateCypher(cypherFull, snapshot);
+  entry.validated = true;
+
+  if (result.ok) {
+    console.error(
+      `[cypher-validate] tool=${isWrite ? "write" : "read"} outcome=accepted labels=${result.labelTokens.length} relationships=${result.edgeTokens.length}`,
+    );
+    pending.set(msg.id, entry);
+    return "forward";
+  }
+
+  void schemaCache.maybeRebuildOnStaleMiss(result.unknown);
+  const tokenSummary = result.unknown
+    .map((u) => `${u.kind}:${u.token}`)
+    .join(",");
+
+  if (isWrite) {
+    console.error(
+      `[cypher-validate] tool=write outcome=rejected unknown=${tokenSummary} cypher="${(cypherPrefix ?? "").replace(/"/g, "'")}"`,
+    );
+    const response = synthesiseRejection(msg.id, result.unknown);
+    process.stdout.write(`${response}\n`);
+    console.error(
+      `[graph-query] op=${methodName} brand=${brand} port=${neo4jPort} cypher="${(cypherPrefix ?? "").replace(/"/g, "'")}" rejected=true validated=true ms=${Date.now() - entry.startMs}`,
+    );
+    return "intercepted";
+  }
+
+  entry.readWarnings = result.unknown;
+  console.error(
+    `[cypher-validate] tool=read outcome=warned unknown=${tokenSummary} cypher="${(cypherPrefix ?? "").replace(/"/g, "'")}"`,
+  );
+  pending.set(msg.id, entry);
+  return "forward";
 }
 
-function onResponseLine(line: string): void {
+function handleResponseLine(line: string): string | null {
+  let msg: JsonRpcMessage;
   try {
-    const msg = JSON.parse(line) as JsonRpcMessage;
-    if (msg.id === undefined || !pending.has(msg.id)) return;
-    const p = pending.get(msg.id)!;
-    pending.delete(msg.id);
-    const elapsed = Date.now() - p.startMs;
-    const cypherField = p.cypherPrefix ? `cypher="${p.cypherPrefix.replace(/"/g, "'")}"` : "";
-    if (msg.error) {
-      const errText = (msg.error.message ?? JSON.stringify(msg.error)).replace(/"/g, "'");
-      console.error(
-        `[graph-query] op=${p.method} brand=${brand} port=${neo4jPort} ${cypherField} error="${errText}" ms=${elapsed}`,
-      );
-    } else {
-      const rows = countRows(msg.result);
+    msg = JSON.parse(line) as JsonRpcMessage;
+  } catch {
+    return null;
+  }
+  if (msg.id === undefined || !pending.has(msg.id)) return null;
+  const p = pending.get(msg.id)!;
+  pending.delete(msg.id);
+  const elapsed = Date.now() - p.startMs;
+  const cypherField = p.cypherPrefix ? `cypher="${p.cypherPrefix.replace(/"/g, "'")}"` : "";
+  const validatedField = `validated=${p.validated}`;
+  if (msg.error) {
+    const errText = (msg.error.message ?? JSON.stringify(msg.error)).replace(/"/g, "'");
+    console.error(
+      `[graph-query] op=${p.method} brand=${brand} port=${neo4jPort} ${cypherField} error="${errText}" ${validatedField} ms=${elapsed}`,
+    );
+    return null;
+  }
+  const rows = countRows(msg.result);
+  const warnedField = p.readWarnings.length > 0 ? ` warned=${p.readWarnings.length}` : "";
+  console.error(
+    `[graph-query] op=${p.method} brand=${brand} port=${neo4jPort} ${cypherField} rows=${rows} ${validatedField}${warnedField} ms=${elapsed}`,
+  );
+  if (p.readWarnings.length > 0) {
+    try {
+      return wrapReadWarnings(msg, p.readWarnings);
+    } catch (err) {
+      const errMsg = err instanceof Error ? err.message : String(err);
       console.error(
-        `[graph-query] op=${p.method} brand=${brand} port=${neo4jPort} ${cypherField} rows=${rows} ms=${elapsed}`,
+        `[cypher-validate] warning-wrap failed op=${p.method} error="${errMsg.replace(/"/g, "'")}" — forwarding response unwrapped`,
       );
+      return null;
     }
-  } catch {
-    // Non-JSON — forward untouched.
   }
+  return null;
 }
 
-function makeLineSplitter(onLine: (line: string) => void): (chunk: Buffer) => void {
+/**
+ * Per-stream buffering splitter. Yields complete lines (without trailing \n)
+ * as they accumulate; leaves any partial tail in the buffer until more bytes
+ * arrive. Unlike the pre-Task-652 splitter, this one lets the caller decide
+ * per-line whether to forward or intercept — the original splitter was
+ * fire-and-forget and the raw chunk was forwarded unconditionally alongside,
+ * which ruled out interception.
+ */
+function makeLineBuffer(): { push: (chunk: Buffer) => string[] } {
   const decoder = new StringDecoder("utf8");
   let buf = "";
-  return (chunk: Buffer) => {
-    buf += decoder.write(chunk);
-    let idx: number;
-    while ((idx = buf.indexOf("\n")) !== -1) {
-      const line = buf.slice(0, idx);
-      buf = buf.slice(idx + 1);
-      if (line.length > 0) onLine(line);
-    }
+  return {
+    push(chunk: Buffer): string[] {
+      buf += decoder.write(chunk);
+      const out: string[] = [];
+      let idx: number;
+      while ((idx = buf.indexOf("\n")) !== -1) {
+        out.push(buf.slice(0, idx));
+        buf = buf.slice(idx + 1);
+      }
+      return out;
+    },
   };
 }
 
-const splitRequest = makeLineSplitter(onRequestLine);
+const requestBuffer = makeLineBuffer();
 process.stdin.on("data", (chunk: Buffer) => {
-  splitRequest(chunk);
-  child.stdin.write(chunk);
+  for (const line of requestBuffer.push(chunk)) {
+    if (line.length === 0) {
+      child.stdin.write("\n");
+      continue;
+    }
+    const decision = handleRequestLine(line);
+    if (decision === "forward") {
+      child.stdin.write(`${line}\n`);
+    }
+    // "intercepted" — synthesised response already written to stdout.
+  }
 });
 process.stdin.on("end", () => {
   child.stdin.end();
 });
 
-const splitResponse = makeLineSplitter(onResponseLine);
+const responseBuffer = makeLineBuffer();
 child.stdout.on("data", (chunk: Buffer) => {
-  splitResponse(chunk);
-  process.stdout.write(chunk);
+  for (const line of responseBuffer.push(chunk)) {
+    if (line.length === 0) {
+      process.stdout.write("\n");
+      continue;
+    }
+    const rewritten = handleResponseLine(line);
+    process.stdout.write(`${rewritten ?? line}\n`);
+  }
 });
 child.stdout.on("end", () => {
   process.stdout.end();