@rubytech/create-realagent 1.0.709 → 1.0.712

package/payload/platform/plugins/memory/mcp/dist/tools/memory-archive-write.js

@@ -0,0 +1,229 @@
+import { getSession } from "../lib/neo4j.js";
+/**
+ * memory-archive-write — deterministic bulk-archive write surface (Task 744).
+ *
+ * Writes a flat dataset (today: LinkedIn Connections.csv parsed into typed
+ * rows) into the graph as first-class entity nodes plus their natural edges.
+ * Distinct from memory-write (per-node, adjacency-required) and memory-ingest
+ * (narrative document → KnowledgeDocument + Section + HAS_SECTION + NEXT).
+ *
+ * Doctrine:
+ *   - The Cypher body for each archiveType is fixed inside this tool. The
+ *     agent never supplies Cypher; only parsed rows + the archiveType
+ *     discriminant. Determinism here means "the Cypher is not in the tool
+ *     input" — not "be careful with the Cypher".
+ *   - 500-row UNWIND batches per executeWrite transaction. Larger batches
+ *     risk Neo4j Community heap pressure on a Pi 5; smaller batches multiply
+ *     round-trip cost.
+ *   - Per-row provenance stamps (createdByAgent, createdBySession, source,
+ *     createdAt) come from this server, not the agent.
+ *   - Owner is matched by elementId so both AdminUser and external-Person
+ *     archive owners flow through one path.
+ *   - Counters come from result.summary.counters (nodesCreated /
+ *     relationshipsCreated) so we never invent stamp-based detection.
+ */
+const BATCH_SIZE = 500;
+const HANDLERS = {
+    "linkedin-connections": linkedinConnectionsHandler(),
+};
+export async function memoryArchiveWrite(params) {
+    const { archiveType, ownerNodeId, accountId, rows, sessionId } = params;
+    if (!accountId || !accountId.trim()) {
+        throw new Error("memory-archive-write: accountId is required.");
+    }
+    if (!ownerNodeId || !ownerNodeId.trim()) {
+        throw new Error("memory-archive-write: ownerNodeId is required.");
+    }
+    if (!Array.isArray(rows) || rows.length === 0) {
+        throw new Error("memory-archive-write: rows must be a non-empty array.");
+    }
+    const handler = HANDLERS[archiveType];
+    if (!handler) {
+        throw new Error(`memory-archive-write: unknown archiveType "${archiveType}". Known: ${Object.keys(HANDLERS).join(", ")}`);
+    }
+    const session = getSession();
+    const startedMs = Date.now();
+    const errors = [];
+    const totals = {
+        createdPersons: 0,
+        mergedPersons: 0,
+        createdOrganizations: 0,
+        mergedOrganizations: 0,
+        createdEdges: 0,
+    };
+    try {
+        await handler.verifyOwner(session, ownerNodeId, accountId);
+        for (let offset = 0; offset < rows.length; offset += BATCH_SIZE) {
+            const batch = rows.slice(offset, offset + BATCH_SIZE);
+            try {
+                const counters = await handler.writeBatch(session, {
+                    ownerNodeId,
+                    accountId,
+                    rows: batch,
+                    sessionId: sessionId?.trim() || null,
+                });
+                totals.createdPersons += counters.createdPersons;
+                totals.mergedPersons += counters.mergedPersons;
+                totals.createdOrganizations += counters.createdOrganizations;
+                totals.mergedOrganizations += counters.mergedOrganizations;
+                totals.createdEdges += counters.createdEdges;
+            }
+            catch (err) {
+                const reason = err instanceof Error ? err.message : String(err);
+                errors.push({ rowIndex: offset, reason: `batch starting at row ${offset}: ${reason}` });
+                process.stderr.write(`[memory-archive-write] batch-failed archiveType=${archiveType} offset=${offset} reason=${reason}\n`);
+            }
+        }
+    }
+    finally {
+        await session.close();
+    }
+    const elapsedMs = Date.now() - startedMs;
+    process.stderr.write(`[memory-archive-write] archiveType=${archiveType} rows=${rows.length} ` +
+        `createdPersons=${totals.createdPersons} mergedPersons=${totals.mergedPersons} ` +
+        `createdOrganizations=${totals.createdOrganizations} mergedOrganizations=${totals.mergedOrganizations} ` +
+        `createdEdges=${totals.createdEdges} errors=${errors.length} ms=${elapsedMs}\n`);
+    return {
+        archiveType,
+        processedRows: rows.length,
+        ...totals,
+        errors,
+    };
+}
+// ---------------------------------------------------------------------------
+// linkedin-connections handler
+// ---------------------------------------------------------------------------
+//
+// Owner anchor: AdminUser or Person (elementId match — operator-confirmed
+// during the linkedin-import skill's owner-confirmation flow).
+//
+// Per row the CSV expresses two relationships:
+//   1. (owner)-[:CONNECTED_ON_LINKEDIN {connectedOn}]->(:Person)
+//   2. (:Person)-[:WORKS_FOR {title, current=true}]->(:Organization) — when company present
+//
+// Natural keys:
+//   :Person       — linkedinUrl (indexed in platform/neo4j/schema.cypher)
+//   :Organization — (accountId, name)
+//
+// Provenance stamped on every node:
+//   createdByAgent='linkedin-import', createdBySource='linkedin-import',
+//   createdBySession=$sessionId (when provided), createdAt=datetime(),
+//   source='linkedin'
+//
+// We split each batch into two tx.run calls inside one executeWrite so each
+// statement's summary counters give a clean per-label breakdown.
+// ---------------------------------------------------------------------------
+const PERSON_AND_CONNECTED_EDGE_CYPHER = `
+MATCH (owner) WHERE elementId(owner) = $ownerNodeId
+WITH owner, $rows AS rows
+UNWIND rows AS row
+MERGE (p:Person {linkedinUrl: row.linkedinUrl})
+  ON CREATE SET
+    p.accountId        = $accountId,
+    p.source           = 'linkedin',
+    p.createdByAgent   = 'linkedin-import',
+    p.createdBySource  = 'linkedin-import',
+    p.createdBySession = $sessionId,
+    p.createdAt        = datetime(),
+    p.scope            = 'admin'
+SET
+    p.givenName = row.givenName,
+    p.familyName= row.familyName,
+    p.name      = trim(coalesce(row.givenName,'') + ' ' + coalesce(row.familyName,''))
+FOREACH (_ IN CASE WHEN row.email IS NOT NULL AND row.email <> '' THEN [1] ELSE [] END |
+  SET p.email = row.email
+)
+MERGE (owner)-[c:CONNECTED_ON_LINKEDIN]->(p)
+  ON CREATE SET
+    c.connectedOn = date(row.connectedOn),
+    c.source      = 'linkedin',
+    c.createdAt   = datetime()
+RETURN count(*) AS processed
+`;
+const ORG_AND_WORKS_FOR_CYPHER = `
+UNWIND $rows AS row
+WITH row WHERE row.company IS NOT NULL AND row.company <> ''
+MATCH (p:Person {linkedinUrl: row.linkedinUrl})
+MERGE (o:Organization {accountId: $accountId, name: row.company})
+  ON CREATE SET
+    o.source           = 'linkedin',
+    o.createdByAgent   = 'linkedin-import',
+    o.createdBySource  = 'linkedin-import',
+    o.createdBySession = $sessionId,
+    o.createdAt        = datetime(),
+    o.scope            = 'admin'
+MERGE (p)-[w:WORKS_FOR]->(o)
+  ON CREATE SET
+    w.title     = row.title,
+    w.source    = 'linkedin',
+    w.current   = true,
+    w.createdAt = datetime()
+  ON MATCH SET
+    w.title     = coalesce(row.title, w.title)
+RETURN count(*) AS processed
+`;
+function linkedinConnectionsHandler() {
+    return {
+        async verifyOwner(session, ownerNodeId, accountId) {
+            const result = await session.run(`MATCH (n) WHERE elementId(n) = $ownerNodeId
+         RETURN labels(n) AS labels, n.accountId AS accountId LIMIT 1`, { ownerNodeId });
+            if (result.records.length === 0) {
+                throw new Error(`ownerNodeId ${ownerNodeId} not found. Re-run the archive-owner confirmation flow before invoking memory-archive-write.`);
+            }
+            const labels = result.records[0].get("labels") ?? [];
+            const ownerAccountId = result.records[0].get("accountId");
+            const isAdminUser = labels.includes("AdminUser");
+            const isPerson = labels.includes("Person");
+            if (!isAdminUser && !isPerson) {
+                throw new Error(`ownerNodeId ${ownerNodeId} has labels [${labels.join(", ")}]; expected :AdminUser or :Person.`);
+            }
+            if (ownerAccountId && ownerAccountId !== accountId) {
+                throw new Error(`ownerNodeId ${ownerNodeId} belongs to account ${ownerAccountId}, not ${accountId}. Cross-account archive ingest refused.`);
+            }
+        },
+        async writeBatch(session, { ownerNodeId, accountId, rows, sessionId }) {
+            const params = {
+                ownerNodeId,
+                accountId,
+                sessionId,
+                rows: rows.map((r) => normaliseLinkedinRow(r)),
+            };
+            return await session.executeWrite(async (tx) => {
+                const personRes = await tx.run(PERSON_AND_CONNECTED_EDGE_CYPHER, params);
+                const personCounters = personRes.summary.counters.updates();
+                const orgRes = await tx.run(ORG_AND_WORKS_FOR_CYPHER, params);
+                const orgCounters = orgRes.summary.counters.updates();
+                const createdPersonNodes = personCounters.nodesCreated;
+                const createdOrgNodes = orgCounters.nodesCreated;
+                const personsTouched = params.rows.length;
+                const personsCreated = createdPersonNodes;
+                const personsMerged = personsTouched - personsCreated;
+                return {
+                    createdPersons: personsCreated,
+                    mergedPersons: personsMerged,
+                    createdOrganizations: createdOrgNodes,
+                    mergedOrganizations: 0,
+                    createdEdges: personCounters.relationshipsCreated + orgCounters.relationshipsCreated,
+                };
+            });
+        },
+    };
+}
+function normaliseLinkedinRow(row) {
+    if (!row.linkedinUrl || !row.linkedinUrl.trim()) {
+        throw new Error("linkedin-connections row missing linkedinUrl (natural key).");
+    }
+    if (!row.connectedOn || !/^\d{4}-\d{2}-\d{2}$/.test(row.connectedOn)) {
+        throw new Error(`linkedin-connections row connectedOn="${row.connectedOn}" is not ISO 8601 (YYYY-MM-DD). Parser must convert "23 Apr 2026" before calling.`);
+    }
+    return {
+        givenName: (row.givenName ?? "").trim(),
+        familyName: (row.familyName ?? "").trim(),
+        linkedinUrl: row.linkedinUrl.trim(),
+        email: row.email && row.email.trim() ? row.email.trim() : null,
+        company: row.company && row.company.trim() ? row.company.trim() : null,
+        title: row.title && row.title.trim() ? row.title.trim() : null,
+        connectedOn: row.connectedOn,
+    };
+}
+//# sourceMappingURL=memory-archive-write.js.map

package/payload/platform/plugins/memory/mcp/dist/tools/memory-archive-write.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-archive-write.js","sourceRoot":"","sources":["../../src/tools/memory-archive-write.ts"],"names":[],"mappings":"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"}

package/payload/platform/plugins/memory/mcp/package.json

@@ -6,7 +6,9 @@
   "main": "dist/index.js",
   "scripts": {
     "build": "tsc",
-    "start": "node dist/index.js"
+    "start": "node dist/index.js",
+    "smoke": "bash ./scripts/boot-smoke.sh",
+    "prepublish": "bash ./scripts/boot-smoke.sh"
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.81.0",

package/payload/platform/plugins/memory/mcp/scripts/boot-smoke.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+# Memory MCP boot-smoke gate (Task 743).
+#
+# Spawns dist/index.js with a stub env, holds stdin open via `tail -f /dev/null`
+# (the MCP SDK's StdioServerTransport exits on EOF — closing stdin would mask a
+# clean boot as a failure), sleeps 2s, then asserts the process is still alive.
+# A schema-loader throw, an import failure, or any other module-load fault
+# would have killed the child by now and `kill -0` would return non-zero.
+#
+# Wired to the memory MCP `prepublish` script in package.json so a regression
+# can never reach npm publish without the gate firing first. Local matrix:
+#
+#   $ ./scripts/boot-smoke.sh
+#   [boot-smoke] memory ok
+#
+#   $ # break the schema content, rebuild, retry
+#   $ ./scripts/boot-smoke.sh
+#   [boot-smoke] memory FAILED tail=<schema-loader throw>
+#   exit 1
+set -euo pipefail
+
+SCRIPT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+MCP_DIR=$(cd "$SCRIPT_DIR/.." && pwd)
+ENTRY="$MCP_DIR/dist/index.js"
+PLATFORM_ROOT=$(cd "$MCP_DIR/../../.." && pwd)
+
+if [ ! -f "$ENTRY" ]; then
+  echo "[boot-smoke] memory FAILED tail=\"dist/index.js missing — run npm run build first\"" >&2
+  exit 1
+fi
+
+LOG_DIR=$(mktemp -d -t mcp-boot-smoke.XXXXXX)
+trap 'rm -rf "$LOG_DIR"' EXIT
+
+# stdin from a `tail -f /dev/null` keeps the StdioServerTransport open. The
+# pipeline's left side is a tiny long-running process; the right side is the
+# MCP server we are smoke-testing. Both are killed below.
+# Disable pipefail for this block — when bash forks the pipeline, $! is the
+# PID of the LAST command (the node process), which is what we test below.
+set +o pipefail
+
+tail -f /dev/null | env \
+  ACCOUNT_ID=boot-smoke-test \
+  PLATFORM_ROOT="$PLATFORM_ROOT" \
+  LOG_DIR="$LOG_DIR" \
+  STREAM_LOG_PATH="$LOG_DIR/stream.log" \
+  NEO4J_URI=bolt://localhost:7687 \
+  SESSION_ID=boot-smoke \
+  node "$ENTRY" > /dev/null 2>"$LOG_DIR/stderr-direct.log" &
+
+NODE_PID=$!
+sleep 2
+
+if ! kill -0 "$NODE_PID" 2>/dev/null; then
+  TAIL=$(tail -n 5 "$LOG_DIR/stderr-direct.log" 2>/dev/null | tr '\n' ' ' | sed 's/"/\\"/g')
+  echo "[boot-smoke] memory FAILED tail=\"$TAIL\"" >&2
+  # Reap the tail process by killing its parent group (the pipeline subshell).
+  kill 0 2>/dev/null || true
+  exit 1
+fi
+
+echo "[boot-smoke] memory ok"
+kill "$NODE_PID" 2>/dev/null || true
+# Reap the still-running `tail -f /dev/null` so the script exits cleanly.
+# `disown` first so bash does not print a job-control "Terminated" line
+# when the pipeline subshell is killed by exit-trap.
+{ disown -a 2>/dev/null; pkill -P $$ -f "tail -f /dev/null"; } 2>/dev/null || true
+wait 2>/dev/null || true
+exit 0

package/payload/platform/plugins/memory/references/graph-primitives.md

@@ -38,6 +38,28 @@ deterministic path through the shim is the only supported way to read
 the graph, and any substitute path loses the read-only + namespace +
 token-limit discipline the upstream server enforces.
 
+## When the memory tools are absent
+
+If `mcp__memory__memory-write`, `mcp__memory__memory-search`,
+`mcp__memory__memory-rank`, `mcp__memory__memory-reindex`,
+`mcp__memory__session-compact`, `mcp__memory__session-compact-status`, or
+`mcp__memory__conversation-search` is missing from your tool list, the
+memory MCP server failed to start on this device. Reply once with
+exactly:
+
+> The memory MCP server failed to start on this device. Run the admin
+> system-status check to diagnose — do not retry by other routes.
+
+Then stop. Do not search for a similarly-named tool via `ToolSearch`, do
+not improvise via `maxy-graph-read_neo4j_cypher` (it is read-only — every
+write goes through the schema-aware memory tools), do not paraphrase.
+A missing memory tool is a deterministic failure of the per-account
+memory server: the platform's `[mcp-init-error] server=memory` line in
+the per-conversation stream log already names it; the user-facing reply
+exists so the operator knows the session cannot proceed without an
+operator-side fix (Task 743 propagates Task 560's loud-fail contract
+from graph to memory).
+
 ## Mutation intents
 
 The graph tools above are read-only. Every write intent has a schema-aware

package/payload/platform/plugins/memory/references/schema-base.md

@@ -165,7 +165,7 @@ The classifier returns `kind` strings from the closed enumeration above. `kind`
 | `CREATED` | `UserProfile` → `Project` | Standalone-node anchor. |
 | `UNDER` | `Project` → `Organization` | Optional Project context. |
 | `AT` | `Section:Position` → `Organization` | Position's employer. |
-| `PARTY` | `KnowledgeDocument` → `Person|Organization` | Contract Parties — written from `documentEdges`. |
+| `PARTY` | `KnowledgeDocument` → `Person` or `Organization` | Contract Parties — written from `documentEdges`. |
 | `DEFINES` | `Section:Definitions` → `DefinedTerm` | Contract definitions — written from per-section `related`. |
 
 **Ontology-growth review query.** When a document accumulates several `:Section:Other` nodes, the operator (or admin agent) can run the following Cypher to surface candidate ontology additions:

package/payload/platform/scripts/redact-install-logs.sh

@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+# Existing-pi install-log redaction (Task 744).
+#
+# Idempotent one-shot remediation for Pis that completed installation BEFORE
+# the install-log redaction landed at index.ts:152 / setup.sh:94. Scans every
+# `install-*.log` in the configured logs directory and replaces every literal
+# `set-initial-password ...<secret>` payload with `set-initial-password
+# [REDACTED]`. Re-running the script is safe — already-redacted lines do not
+# match the source pattern, so no further edits occur.
+#
+# Source patterns covered:
+#   1. TS installer (packages/create-maxy/src/index.ts:152) — "[ISO] > sudo
+#      neo4j-admin dbms set-initial-password -- <secret>" or any args after
+#      "set-initial-password" (positional or "--" delimited).
+#   2. Shell installer (platform/scripts/setup.sh, pre-fix variant) — "+ sudo
+#      neo4j-admin dbms set-initial-password <secret>" if bash -x had been on.
+#
+# A trailing marker line `[redact-install-logs] redacted=<n> file=<path>` is
+# appended to each modified log so subsequent reads can identify which logs
+# went through the remediation. Files with zero matches are left untouched.
+#
+# Default scan location: $HOME/.maxy/logs (the installer's LOG_DIR). Override
+# with --dir <path> for non-default deployments.
+
+set -euo pipefail
+
+LOG_DIR="${HOME}/.maxy/logs"
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --dir) LOG_DIR="$2"; shift 2 ;;
+    --help|-h)
+      cat <<USAGE
+Usage: redact-install-logs.sh [--dir <log-dir>]
+
+Redacts neo4j set-initial-password secrets from install-*.log files.
+Default --dir: \$HOME/.maxy/logs
+
+Idempotent — safe to re-run.
+USAGE
+      exit 0 ;;
+    *) echo "Unknown arg: $1" >&2; exit 2 ;;
+  esac
+done
+
+if [ ! -d "$LOG_DIR" ]; then
+  echo "[redact-install-logs] log dir not found: $LOG_DIR (nothing to do)"
+  exit 0
+fi
+
+shopt -s nullglob
+TOTAL_FILES=0
+TOTAL_REDACTIONS=0
+
+for f in "$LOG_DIR"/install-*.log; do
+  [ -f "$f" ] || continue
+  TOTAL_FILES=$((TOTAL_FILES + 1))
+
+  # Pattern: any "set-initial-password" line followed by one or more args.
+  # The replacement keeps the leading prefix (timestamp + cmd up through
+  # set-initial-password and an optional "--") and substitutes everything
+  # after with [REDACTED]. We anchor the replacement only when the remaining
+  # tail is non-empty AND not already "[REDACTED]" — making the script idempotent.
+  REDACTED_THIS_FILE=$(
+    perl -ne '
+      if (/set-initial-password(\s+--)?\s+(\S.*)$/ && $2 ne "[REDACTED]") {
+        print STDOUT "1\n";
+      }
+    ' "$f" | wc -l | tr -d ' '
+  )
+
+  if [ "$REDACTED_THIS_FILE" -gt 0 ]; then
+    perl -i -pe '
+      if (/set-initial-password(\s+--)?\s+(\S.*)$/ && $2 ne "[REDACTED]") {
+        s/set-initial-password(\s+--)?\s+\S.*$/set-initial-password${1} [REDACTED]/;
+      }
+    ' "$f"
+    printf "[redact-install-logs] redacted=%d file=%s\n" "$REDACTED_THIS_FILE" "$f" >> "$f"
+    echo "[redact-install-logs] redacted=$REDACTED_THIS_FILE file=$f"
+    TOTAL_REDACTIONS=$((TOTAL_REDACTIONS + REDACTED_THIS_FILE))
+  fi
+done
+
+echo "[redact-install-logs] summary files_scanned=$TOTAL_FILES total_redactions=$TOTAL_REDACTIONS"
+exit 0

package/payload/platform/scripts/setup.sh

@@ -86,12 +86,20 @@ else
   # Configure Neo4j for local use
   sudo sed -i 's/#server.default_listen_address=0.0.0.0/server.default_listen_address=127.0.0.1/' /etc/neo4j/neo4j.conf
 
-  # Generate a strong random password and store it
+  # Generate a strong random password and store it.
+  # Password handling block is set +x bracketed so even bash -x setup.sh
+  # cannot print the substituted secret. The password is written to
+  # platform/config/.neo4j-password (chmod 600) — the only readable source.
+  # set-initial-password reads the secret via $(cat ...) so the literal
+  # never appears on the parent shell's command line, and stdout is
+  # discarded so neo4j-admin's own echo cannot leak it either (Task 744).
+  { set +x; } 2>/dev/null
   NEO4J_GENERATED_PASSWORD=$(openssl rand -base64 32 | tr -d '/+=' | head -c 32)
   mkdir -p "$INSTALL_DIR/platform/config"
-  echo "$NEO4J_GENERATED_PASSWORD" > "$INSTALL_DIR/platform/config/.neo4j-password"
+  printf '%s' "$NEO4J_GENERATED_PASSWORD" > "$INSTALL_DIR/platform/config/.neo4j-password"
   chmod 600 "$INSTALL_DIR/platform/config/.neo4j-password"
-  sudo neo4j-admin dbms set-initial-password "$NEO4J_GENERATED_PASSWORD"
+  unset NEO4J_GENERATED_PASSWORD
+  sudo neo4j-admin dbms set-initial-password "$(cat "$INSTALL_DIR/platform/config/.neo4j-password")" >/dev/null 2>&1
 
   # Start and enable
   sudo systemctl enable neo4j
@@ -139,6 +147,15 @@ else
   cd "$INSTALL_DIR"
 fi
 
+# ------------------------------------------------------------------
+# 6.5. Redact install-log credential leaks (Task 744 — idempotent).
+# Pre-fix logs may contain plaintext neo4j passwords; this script scrubs
+# every install-*.log to "[REDACTED]". Safe on already-clean logs.
+# ------------------------------------------------------------------
+if [ -x "$INSTALL_DIR/platform/scripts/redact-install-logs.sh" ]; then
+  bash "$INSTALL_DIR/platform/scripts/redact-install-logs.sh" || true
+fi
+
 # ------------------------------------------------------------------
 # 7. Install dependencies and build
 # ------------------------------------------------------------------