@rubytech/create-realagent 1.0.693 → 1.0.695

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

@@ -0,0 +1,167 @@
+/**
+ * Write doctrine (Task 673): a node without at least one adjacency is noise,
+ * not knowledge. `writeNodeWithEdges` is the single primitive every graph
+ * writer should call; it rejects zero-relationship writes, verifies every
+ * relationship target resolves before the node is created, and commits the
+ * node + all edges in one managed transaction. Provenance is stamped on the
+ * node as flattened `createdBy*` properties (Neo4j does not persist nested
+ * maps, and flat props are queryable — `MATCH (n) WHERE n.createdBySession
+ * = $id RETURN n` is the forensic entry point).
+ *
+ * Rejection paths (every one emits a stderr log the admin server pipes to
+ * server.log, so orphan pressure is visible per-write not just in the
+ * hourly [graph-health] signal):
+ *   - zero relationships      → `[graph-write] reject reason=zero-relationships`
+ *   - unresolved target id    → `[graph-write] reject reason=unresolved-target`
+ *
+ * The `createdBy.agent` field is advisory, not authoritative — it is sourced
+ * from the MCP server's AGENT_SLUG env var, which is set by the trusted
+ * spawning code (admin server / workflow runner). A misconfigured spawner
+ * will write "unknown"; that's the signal something is wrong. Do not use
+ * this field for access control — it is forensic, not a security boundary.
+ */
+
+import type { Session } from "neo4j-driver";
+
+export interface GraphRelationship {
+  type: string;
+  direction: "outgoing" | "incoming";
+  targetNodeId: string;
+}
+
+export interface CreatedBy {
+  /** Agent slug (e.g. "maxy-admin", "whatsapp-public") for LLM-tool writes. */
+  agent?: string;
+  /** Session correlation id — same string across every node written in a conversation turn. */
+  session?: string;
+  /** MCP tool name ("memory-write", "contact-create", ...) for LLM-tool writes. */
+  tool?: string;
+  /** Subsystem name ("workflow-execute", "persist-tool-call", ...) for system writes. */
+  source?: string;
+}
+
+export interface WriteNodeWithEdgesParams {
+  session: Session;
+  labels: string[];
+  props: Record<string, unknown>;
+  /** At least one relationship is required — zero-rel writes are rejected. */
+  relationships: GraphRelationship[];
+  createdBy: CreatedBy;
+}
+
+export interface WriteNodeResult {
+  nodeId: string;
+  labels: string[];
+  edgesCreated: number;
+}
+
+/** Stamp flattened provenance into node properties. */
+export function stampCreatedBy(
+  props: Record<string, unknown>,
+  createdBy: CreatedBy
+): Record<string, unknown> {
+  return {
+    ...props,
+    createdByAgent: createdBy.agent ?? "unknown",
+    createdBySession: createdBy.session ?? "unknown",
+    createdByTool: createdBy.tool ?? null,
+    createdBySource: createdBy.source ?? null,
+  };
+}
+
+/**
+ * Enforce the write doctrine: node + ≥1 edge, transactional, provenance stamped.
+ * The label and relationship type strings are interpolated into Cypher — the
+ * caller must constrain them via Zod/schema before calling. Backticks are
+ * stripped to defeat the only Cypher escape char.
+ */
+export async function writeNodeWithEdges(
+  params: WriteNodeWithEdgesParams
+): Promise<WriteNodeResult> {
+  const { session, labels, props, relationships, createdBy } = params;
+
+  const agentLabel = createdBy.agent ?? createdBy.source ?? "unknown";
+  const labelCsv = labels.join(",");
+
+  if (!relationships || relationships.length < 1) {
+    process.stderr.write(
+      `[graph-write] reject reason=zero-relationships labels=${labelCsv} agent=${agentLabel}\n`
+    );
+    throw new Error(
+      "Write doctrine violated: a node must be created with at least one relationship. See .docs/neo4j.md (Write doctrine)."
+    );
+  }
+
+  const labelStr = labels.map((l) => `\`${l.replace(/`/g, "")}\``).join(":");
+  const nodeProps = stampCreatedBy(props, createdBy);
+
+  return await session.executeWrite(async (tx) => {
+    const targetIds = relationships.map((r) => r.targetNodeId);
+    const check = await tx.run(
+      `UNWIND $ids AS id MATCH (t) WHERE elementId(t) = id RETURN count(DISTINCT t) AS found`,
+      { ids: targetIds }
+    );
+    const found = check.records[0].get("found").toNumber();
+    const uniqueRequested = new Set(targetIds).size;
+    if (found !== uniqueRequested) {
+      process.stderr.write(
+        `[graph-write] reject reason=unresolved-target labels=${labelCsv} agent=${agentLabel} requested=${uniqueRequested} found=${found}\n`
+      );
+      throw new Error(
+        `Write doctrine violated: ${uniqueRequested - found} of ${uniqueRequested} relationship target(s) did not resolve (elementId mismatch). No node created.`
+      );
+    }
+
+    const nodeRes = await tx.run(
+      `CREATE (n:${labelStr} $props) RETURN elementId(n) AS nodeId, labels(n) AS nodeLabels`,
+      { props: nodeProps }
+    );
+    const nodeId = nodeRes.records[0].get("nodeId") as string;
+    const nodeLabels = nodeRes.records[0].get("nodeLabels") as string[];
+
+    // Neo4j Community's default isolation is read-committed (not snapshot)
+    // — a target elementId that resolved during the pre-check can be
+    // deleted by a concurrent transaction before the per-edge CREATE below
+    // runs. If that happens, `MATCH (a), (b)` returns 0 rows and the CREATE
+    // quietly produces no edge. Per-edge counter inspection catches the
+    // race: any zero-result CREATE throws inside the transaction callback,
+    // so `executeWrite` rolls the node back — no silent-orphan path.
+    let edgesCreated = 0;
+    for (const rel of relationships) {
+      const type = rel.type.replace(/`/g, "");
+      const q =
+        rel.direction === "outgoing"
+          ? `MATCH (a), (b) WHERE elementId(a) = $from AND elementId(b) = $to CREATE (a)-[:\`${type}\`]->(b)`
+          : `MATCH (a), (b) WHERE elementId(a) = $from AND elementId(b) = $to CREATE (b)-[:\`${type}\`]->(a)`;
+      const r = await tx.run(q, { from: nodeId, to: rel.targetNodeId });
+      const created = r.summary.counters.updates().relationshipsCreated;
+      if (created === 0) {
+        process.stderr.write(
+          `[graph-write] reject reason=unresolved-target-on-create labels=${labelCsv} agent=${agentLabel} relType=${rel.type} targetId=${rel.targetNodeId}\n`
+        );
+        throw new Error(
+          `Write doctrine violated: relationship CREATE to target ${rel.targetNodeId} produced 0 edges (target likely deleted concurrently after pre-check). Transaction rolled back.`
+        );
+      }
+      edgesCreated += created;
+    }
+
+    if (edgesCreated !== relationships.length) {
+      // Defensive: should be unreachable given the per-edge check above.
+      // The rollback throws loudly so regression shows rather than a
+      // silent commit with edgesCreated < requested.
+      process.stderr.write(
+        `[graph-write] reject reason=edge-count-mismatch labels=${labelCsv} agent=${agentLabel} requested=${relationships.length} created=${edgesCreated}\n`
+      );
+      throw new Error(
+        `Write doctrine violated: expected ${relationships.length} edges, created ${edgesCreated}. Transaction rolled back.`
+      );
+    }
+
+    process.stderr.write(
+      `[graph-write] accepted labels=${labelCsv} edges=${edgesCreated} createdByAgent=${createdBy.agent ?? "unknown"} createdByTool=${createdBy.tool ?? createdBy.source ?? "unknown"}\n`
+    );
+
+    return { nodeId, labels: nodeLabels, edgesCreated };
+  });
+}

package/payload/platform/lib/graph-write/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}

package/payload/platform/package.json

@@ -6,8 +6,8 @@
     "plugins/*/mcp"
   ],
   "scripts": {
-    "build": "tsc -p lib/models/tsconfig.json && tsc -p lib/anthropic-key/tsconfig.json && tsc -p lib/mcp-stderr-tee/tsconfig.json && tsc -p lib/graph-mcp/tsconfig.json && tsc -p lib/graph-trash/tsconfig.json && tsc -p lib/screening-patterns/tsconfig.json && tsc -p lib/device-url/tsconfig.json && NODE_OPTIONS='--max-old-space-size=8192' tsc -b plugins/*/mcp/tsconfig.json",
-    "build:lib": "tsc -p lib/models/tsconfig.json && tsc -p lib/anthropic-key/tsconfig.json && tsc -p lib/mcp-stderr-tee/tsconfig.json && tsc -p lib/graph-mcp/tsconfig.json && tsc -p lib/graph-trash/tsconfig.json && tsc -p lib/screening-patterns/tsconfig.json && tsc -p lib/device-url/tsconfig.json",
+    "build": "tsc -p lib/models/tsconfig.json && tsc -p lib/anthropic-key/tsconfig.json && tsc -p lib/mcp-stderr-tee/tsconfig.json && tsc -p lib/graph-mcp/tsconfig.json && tsc -p lib/graph-trash/tsconfig.json && tsc -p lib/graph-search/tsconfig.json && tsc -p lib/graph-write/tsconfig.json && tsc -p lib/screening-patterns/tsconfig.json && tsc -p lib/device-url/tsconfig.json && NODE_OPTIONS='--max-old-space-size=8192' tsc -b plugins/*/mcp/tsconfig.json",
+    "build:lib": "tsc -p lib/models/tsconfig.json && tsc -p lib/anthropic-key/tsconfig.json && tsc -p lib/mcp-stderr-tee/tsconfig.json && tsc -p lib/graph-mcp/tsconfig.json && tsc -p lib/graph-trash/tsconfig.json && tsc -p lib/graph-search/tsconfig.json && tsc -p lib/graph-write/tsconfig.json && tsc -p lib/screening-patterns/tsconfig.json && tsc -p lib/device-url/tsconfig.json",
     "build:memory": "tsc -p plugins/memory/mcp/tsconfig.json",
     "build:contacts": "tsc -p plugins/contacts/mcp/tsconfig.json",
     "build:telegram": "tsc -p plugins/telegram/mcp/tsconfig.json",

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

@@ -2494,17 +2494,22 @@ function cleanupPendingAction(actionId) {
     }
 }
 async function persistApprovalToolCall(opts) {
+    // Write doctrine (Task 673): a ToolCall without its owning Conversation is
+    // noise — every admin tool call belongs to a chat. When conversationId is
+    // missing or its Conversation cannot be matched, we log and skip the
+    // persist rather than create an orphan ToolCall node. The legacy
+    // OPTIONAL-MATCH + FOREACH pattern created orphans silently.
+    if (!opts.conversationId) {
+        console.error(`[approval] ToolCall skipped (no conversationId): tool=${opts.toolName} state=${opts.approvalState}`);
+        return;
+    }
     const session = getSession();
     try {
         const optionalFields = [
             opts.originalInput != null ? ", originalInput: $originalInput" : "",
-            opts.conversationId != null ? ", conversationId: $conversationId" : "",
         ].join("");
-        // Link to Conversation node when conversationId is available
-        const conversationLink = opts.conversationId
-            ? `\nWITH tc\nOPTIONAL MATCH (c:Conversation {conversationId: $conversationId})\nFOREACH (_ IN CASE WHEN c IS NOT NULL THEN [1] ELSE [] END | CREATE (c)-[:HAS_TOOL_CALL]->(tc))`
-            : "";
-        await session.run(`CREATE (tc:ToolCall {
+        const res = await session.run(`MATCH (c:Conversation {conversationId: $conversationId})
+       CREATE (c)-[:HAS_TOOL_CALL]->(tc:ToolCall {
          callId: $callId,
          toolName: $toolName,
          pluginName: $pluginName,
@@ -2514,10 +2519,12 @@ async function persistApprovalToolCall(opts) {
          agentType: 'admin',
          accountId: $accountId,
          approvalState: $approvalState,
+         conversationId: $conversationId,
+         createdBySource: 'admin-approval',
          startedAt: datetime($startedAt),
          completedAt: datetime($completedAt)
          ${optionalFields}
-       })${conversationLink}`, {
+       })`, {
             callId: randomUUID(),
             toolName: opts.toolName,
             pluginName: opts.pluginName,
@@ -2526,11 +2533,15 @@ async function persistApprovalToolCall(opts) {
             isError: opts.isError,
             accountId: ACCOUNT_ID,
             approvalState: opts.approvalState,
+            conversationId: opts.conversationId,
             startedAt: new Date().toISOString(),
             completedAt: new Date().toISOString(),
             ...(opts.originalInput != null ? { originalInput: opts.originalInput.slice(0, 300) } : {}),
-            ...(opts.conversationId != null ? { conversationId: opts.conversationId } : {}),
         });
+        if (res.summary.counters.updates().nodesCreated === 0) {
+            console.error(`[approval] ToolCall skipped (conversation ${opts.conversationId} not found): tool=${opts.toolName}`);
+            return;
+        }
         console.error(`[approval] ToolCall persisted: ${opts.toolName} state=${opts.approvalState}`);
     }
     catch (err) {