@rubytech/create-realagent 1.0.705 → 1.0.706

package/payload/platform/lib/graph-mcp/dist/schema-cypher-parser.js

@@ -0,0 +1,87 @@
+"use strict";
+/**
+ * Shared parser for `platform/neo4j/schema.cypher`.
+ *
+ * Two consumers today:
+ *   1. The admin SCHEMA prompt block (`platform/ui/app/lib/admin-schema-block.ts`,
+ *      Task 703) renders labels declared in schema.cypher into the agent's
+ *      system prompt.
+ *   2. The memory-plugin schema validator (Task 736) treats schema.cypher
+ *      declarations as the "promise" half of the recognised-label set —
+ *      labels that exist as constraints/indexes but may not yet have a node
+ *      in the graph (fresh-install bootstrap).
+ *
+ * The previous home was admin-schema-block.ts; that owner was wrong as
+ * soon as a second consumer arrived. Lifting here keeps a single source of
+ * truth and removes the cross-package shape coupling.
+ *
+ * Also exports a compact `levenshtein` for "did you mean?" suggestions on
+ * unknown labels — used by the memory-plugin validator. The graph-mcp
+ * cypher validator has its own copy in schema-cache.ts (private to the
+ * stale-miss heuristic); the duplication is intentional, since this
+ * exported one targets human-readable error UX, not refresh debouncing.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseLabelsFromSchemaCypher = parseLabelsFromSchemaCypher;
+exports.levenshtein = levenshtein;
+exports.nearestLabel = nearestLabel;
+const LABEL_PATTERN = /FOR\s*\(\s*\w+\s*:\s*(\w+)\s*\)/g;
+/**
+ * Extract every Neo4j label declared in a `schema.cypher` file by scanning
+ * `FOR (alias:Label)` constraint and index forms. Returns a sorted, de-duped
+ * list. Pure function — no I/O.
+ */
+function parseLabelsFromSchemaCypher(schemaCypher) {
+    const found = new Set();
+    for (const match of schemaCypher.matchAll(LABEL_PATTERN)) {
+        found.add(match[1]);
+    }
+    return [...found].sort();
+}
+/**
+ * Standard iterative-DP Levenshtein. Used to suggest a near-match when an
+ * agent submits an unknown label — small alphabets, short strings, runs in
+ * microseconds. Identical algorithm to the private copy in schema-cache.ts;
+ * exported here so callers outside graph-mcp don't have to roll their own.
+ */
+function levenshtein(a, b) {
+    if (a === b)
+        return 0;
+    if (a.length === 0)
+        return b.length;
+    if (b.length === 0)
+        return a.length;
+    let prev = new Array(b.length + 1);
+    let curr = new Array(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];
+}
+/**
+ * Find the closest label in `candidates` to `unknown` by edit distance.
+ * Returns null when the closest match is further than `maxDistance` (default
+ * 3) — beyond that a suggestion is more confusing than helpful.
+ */
+function nearestLabel(unknown, candidates, maxDistance = 3) {
+    let best = null;
+    let bestDist = Infinity;
+    for (const candidate of candidates) {
+        const d = levenshtein(unknown, candidate);
+        if (d < bestDist) {
+            bestDist = d;
+            best = candidate;
+        }
+    }
+    if (best === null || bestDist > maxDistance)
+        return null;
+    return best;
+}
+//# sourceMappingURL=schema-cypher-parser.js.map

package/payload/platform/lib/graph-mcp/dist/schema-cypher-parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-cypher-parser.js","sourceRoot":"","sources":["../src/schema-cypher-parser.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;;AASH,kEAMC;AAQD,kCAgBC;AAOD,oCAgBC;AA5DD,MAAM,aAAa,GAAG,kCAAkC,CAAC;AAEzD;;;;GAIG;AACH,SAAgB,2BAA2B,CAAC,YAAoB;IAC9D,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAChC,KAAK,MAAM,KAAK,IAAI,YAAY,CAAC,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC;QACzD,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACtB,CAAC;IACD,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC;AAC3B,CAAC;AAED;;;;;GAKG;AACH,SAAgB,WAAW,CAAC,CAAS,EAAE,CAAS;IAC9C,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IACtB,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC,MAAM,CAAC;IACpC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC,MAAM,CAAC;IACpC,IAAI,IAAI,GAAG,IAAI,KAAK,CAAS,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC3C,IAAI,IAAI,GAAG,IAAI,KAAK,CAAS,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC3C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE;QAAE,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAChD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACnC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QACZ,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACnC,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YAC3C,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;QACvE,CAAC;QACD,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC9B,CAAC;IACD,OAAO,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;AACxB,CAAC;AAED;;;;GAIG;AACH,SAAgB,YAAY,CAC1B,OAAe,EACf,UAA4B,EAC5B,WAAW,GAAG,CAAC;IAEf,IAAI,IAAI,GAAkB,IAAI,CAAC;IAC/B,IAAI,QAAQ,GAAG,QAAQ,CAAC;IACxB,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,MAAM,CAAC,GAAG,WAAW,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;QAC1C,IAAI,CAAC,GAAG,QAAQ,EAAE,CAAC;YACjB,QAAQ,GAAG,CAAC,CAAC;YACb,IAAI,GAAG,SAAS,CAAC;QACnB,CAAC;IACH,CAAC;IACD,IAAI,IAAI,KAAK,IAAI,IAAI,QAAQ,GAAG,WAAW;QAAE,OAAO,IAAI,CAAC;IACzD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/payload/platform/lib/graph-mcp/src/__tests__/schema-cypher-parser.test.ts

@@ -0,0 +1,99 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import {
+  parseLabelsFromSchemaCypher,
+  levenshtein,
+  nearestLabel,
+} from "../schema-cypher-parser.js";
+
+test("parseLabelsFromSchemaCypher: extracts labels from constraint and index forms", () => {
+  const text = `
+CREATE CONSTRAINT person_email IF NOT EXISTS
+FOR (p:Person) REQUIRE p.email IS UNIQUE;
+
+CREATE CONSTRAINT business_account IF NOT EXISTS
+FOR (b:LocalBusiness) REQUIRE b.accountId IS UNIQUE;
+
+CREATE INDEX admin_user_account IF NOT EXISTS
+FOR (au:AdminUser) ON (au.accountId);
+
+CREATE INDEX knowledge_doc IF NOT EXISTS
+FOR (k:KnowledgeDocument) ON (k.embedding) OPTIONS { ... };
+`;
+  const labels = parseLabelsFromSchemaCypher(text);
+  assert.deepEqual(labels, [
+    "AdminUser",
+    "KnowledgeDocument",
+    "LocalBusiness",
+    "Person",
+  ]);
+});
+
+test("parseLabelsFromSchemaCypher: deduplicates labels declared multiple times", () => {
+  const text = `
+FOR (p:Person) REQUIRE p.email IS UNIQUE;
+FOR (p:Person) REQUIRE p.telephone IS UNIQUE;
+FOR (p:Person) ON (p.status);
+`;
+  assert.deepEqual(parseLabelsFromSchemaCypher(text), ["Person"]);
+});
+
+test("parseLabelsFromSchemaCypher: returns sorted output", () => {
+  const text = `FOR (z:Zebra) ON (z.x); FOR (a:Aardvark) ON (a.x); FOR (m:Mongoose) ON (m.x);`;
+  assert.deepEqual(parseLabelsFromSchemaCypher(text), [
+    "Aardvark",
+    "Mongoose",
+    "Zebra",
+  ]);
+});
+
+test("parseLabelsFromSchemaCypher: ignores non-constraint cypher", () => {
+  const text = `
+MATCH (n:Person) RETURN n;
+CREATE (b:Business { name: 'X' });
+FOR (p:Person) REQUIRE p.email IS UNIQUE;
+`;
+  // MATCH/CREATE patterns don't include FOR, so they're ignored.
+  assert.deepEqual(parseLabelsFromSchemaCypher(text), ["Person"]);
+});
+
+test("parseLabelsFromSchemaCypher: empty input returns empty array", () => {
+  assert.deepEqual(parseLabelsFromSchemaCypher(""), []);
+});
+
+test("levenshtein: identical strings", () => {
+  assert.equal(levenshtein("Person", "Person"), 0);
+});
+
+test("levenshtein: substitution distance", () => {
+  // LocaIBusiness vs LocalBusiness — capital-I-as-l typo from the incident.
+  assert.equal(levenshtein("LocaIBusiness", "LocalBusiness"), 1);
+});
+
+test("levenshtein: insertion + deletion", () => {
+  assert.equal(levenshtein("Person", "Persons"), 1);
+  assert.equal(levenshtein("Persons", "Person"), 1);
+});
+
+test("levenshtein: handles empty strings", () => {
+  assert.equal(levenshtein("", "abc"), 3);
+  assert.equal(levenshtein("abc", ""), 3);
+  assert.equal(levenshtein("", ""), 0);
+});
+
+test("nearestLabel: finds the closest match", () => {
+  const candidates = ["Person", "LocalBusiness", "AdminUser"];
+  assert.equal(nearestLabel("LocaIBusiness", candidates), "LocalBusiness");
+  assert.equal(nearestLabel("AdminUsr", candidates), "AdminUser");
+});
+
+test("nearestLabel: returns null when no match within maxDistance", () => {
+  const candidates = ["Person", "LocalBusiness"];
+  assert.equal(nearestLabel("Quokka", candidates), null);
+  // Default maxDistance is 3; "abcde" is too far from any candidate.
+  assert.equal(nearestLabel("abcde", candidates, 1), null);
+});
+
+test("nearestLabel: empty candidates returns null", () => {
+  assert.equal(nearestLabel("Person", []), null);
+});

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

@@ -0,0 +1,84 @@
+/**
+ * Shared parser for `platform/neo4j/schema.cypher`.
+ *
+ * Two consumers today:
+ *   1. The admin SCHEMA prompt block (`platform/ui/app/lib/admin-schema-block.ts`,
+ *      Task 703) renders labels declared in schema.cypher into the agent's
+ *      system prompt.
+ *   2. The memory-plugin schema validator (Task 736) treats schema.cypher
+ *      declarations as the "promise" half of the recognised-label set —
+ *      labels that exist as constraints/indexes but may not yet have a node
+ *      in the graph (fresh-install bootstrap).
+ *
+ * The previous home was admin-schema-block.ts; that owner was wrong as
+ * soon as a second consumer arrived. Lifting here keeps a single source of
+ * truth and removes the cross-package shape coupling.
+ *
+ * Also exports a compact `levenshtein` for "did you mean?" suggestions on
+ * unknown labels — used by the memory-plugin validator. The graph-mcp
+ * cypher validator has its own copy in schema-cache.ts (private to the
+ * stale-miss heuristic); the duplication is intentional, since this
+ * exported one targets human-readable error UX, not refresh debouncing.
+ */
+
+const LABEL_PATTERN = /FOR\s*\(\s*\w+\s*:\s*(\w+)\s*\)/g;
+
+/**
+ * Extract every Neo4j label declared in a `schema.cypher` file by scanning
+ * `FOR (alias:Label)` constraint and index forms. Returns a sorted, de-duped
+ * list. Pure function — no I/O.
+ */
+export function parseLabelsFromSchemaCypher(schemaCypher: string): string[] {
+  const found = new Set<string>();
+  for (const match of schemaCypher.matchAll(LABEL_PATTERN)) {
+    found.add(match[1]);
+  }
+  return [...found].sort();
+}
+
+/**
+ * Standard iterative-DP Levenshtein. Used to suggest a near-match when an
+ * agent submits an unknown label — small alphabets, short strings, runs in
+ * microseconds. Identical algorithm to the private copy in schema-cache.ts;
+ * exported here so callers outside graph-mcp don't have to roll their own.
+ */
+export 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];
+}
+
+/**
+ * Find the closest label in `candidates` to `unknown` by edit distance.
+ * Returns null when the closest match is further than `maxDistance` (default
+ * 3) — beyond that a suggestion is more confusing than helpful.
+ */
+export function nearestLabel(
+  unknown: string,
+  candidates: Iterable<string>,
+  maxDistance = 3,
+): string | null {
+  let best: string | null = null;
+  let bestDist = Infinity;
+  for (const candidate of candidates) {
+    const d = levenshtein(unknown, candidate);
+    if (d < bestDist) {
+      bestDist = d;
+      best = candidate;
+    }
+  }
+  if (best === null || bestDist > maxDistance) return null;
+  return best;
+}

package/payload/platform/plugins/admin/PLUGIN.md

@@ -36,6 +36,7 @@ hidden:
   - api-key-verify
   - onboarding-get
   - onboarding-complete-step
+  - onboarding-step9-mode
   - qr-generate
   - wifi
   - review-digest-compose

package/payload/platform/plugins/admin/mcp/dist/index.js

@@ -1709,6 +1709,36 @@ server.tool("onboarding-complete-step", "Mark an onboarding step as completed. S
         };
     }
 });
+// Task 704: pin the operator's persona (personal/business-owner/employee) at
+// step 9 BEFORE any graph write happens. The agent calls this immediately on
+// the user's single-select submission. The tool's job is twofold:
+//   1. Emit a deterministic [onboarding-step9-mode] log line for the
+//      diagnostic-grep path on the Pi (matches [onboarding-step-complete]
+//      format — same accountId-prefix slicing, same surrounding code).
+//   2. Return the next-action prose so the agent's branching is anchored to
+//      the tool surface, not free-text inference.
+// No persistence — the graph state (LocalBusiness exists vs Person with
+// role=admin-personal exists) remains the source of truth for gate
+// satisfaction. Re-calling this tool with a different mode on the same
+// session is allowed; the most recent log line wins for diagnostic purposes.
+server.tool("onboarding-step9-mode", "Step 9 onboarding fork: record the operator's persona (personal, business-owner, " +
+    "or employee) before any graph write. Logs the choice for diagnostic grep and " +
+    "returns the deterministic next-action prose for the agent.", {
+    mode: z
+        .enum(["personal", "business-owner", "employee"])
+        .describe("The operator's persona: 'personal' for an individual user with no business, 'business-owner' for someone setting up Maxy as the operations agent for their company, or 'employee' for an employee whose employer is NOT being registered."),
+}, async ({ mode }) => {
+    console.log(`[onboarding-step9-mode] accountId=${ACCOUNT_ID.slice(0, 8)}… mode=${mode}`);
+    const nextAction = mode === "business-owner"
+        ? "Invoke the `business-profile` skill to create AdminUser + LocalBusiness and capture the business identity. Mark step 9 complete only after both nodes exist in the graph."
+        : "Ask the user for their email (one sentence). Use their name from `admin-identity` in the system prompt; split into givenName + familyName. Call `memory-write` to create the AdminUser node, then call `memory-write` to create a Person node with `role: \"admin-personal\"`, the givenName, familyName, email, and an OWNS edge from the AdminUser. Then call `onboarding-complete-step` with step 9. Do not invoke the `business-profile` skill — personal/employee mode does not register a LocalBusiness.";
+    return {
+        content: [{
+                type: "text",
+                text: JSON.stringify({ mode, nextAction }, null, 2),
+            }],
+    };
+});
 // ===================================================================
 // Utility tools
 // ===================================================================