@rubytech/create-realagent 1.0.651 → 1.0.653

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

@@ -0,0 +1,360 @@
+/**
+ * Soft-delete primitive for the knowledge graph.
+ *
+ * MCP-tool callers must NEVER `DETACH DELETE` user-domain nodes. Use
+ * `trashNode` to mark a node `:Trashed`; `restoreNode` removes the label;
+ * `emptyTrash` hard-deletes nodes whose `trashedAt < now - graceDays`. The
+ * 2026-04-20 incident wiped 19 nodes via a single autonomous `DETACH DELETE`
+ * — Neo4j Community has no PITR, so properties were unrecoverable. This
+ * primitive contains the blast radius for every caller.
+ *
+ * Unique-constraint handling: when the trashed node's labels carry single-
+ * key UNIQUE constraints (e.g. `OnboardingState.accountId`), the live values
+ * are snapshotted into `_trashedKeys` (JSON) and nulled on the node, so
+ * MERGE against the same key won't collide. `restoreNode` writes them back
+ * and fails loudly when an active node already occupies the slot.
+ */
+
+import type { Session } from "neo4j-driver";
+
+/**
+ * Single-key UNIQUE properties per label, mirroring `platform/neo4j/schema.cypher`.
+ *
+ * Composite UNIQUEs (UserProfile, Email composite, AccessGrant) are
+ * represented by a single nullable component — Neo4j enforces a composite
+ * constraint only when every component is non-null, so nulling one frees it.
+ */
+const UNIQUE_KEYS_BY_LABEL: Record<string, string[]> = {
+  Person: ["email", "telephone"],
+  Service: ["serviceId"],
+  LocalBusiness: ["accountId"],
+  Task: ["taskId"],
+  Event: ["eventId"],
+  KnowledgeDocument: ["attachmentId"],
+  DigitalDocument: ["attachmentId"],
+  Conversation: ["conversationId", "sessionKey"],
+  Message: ["messageId"],
+  OnboardingState: ["accountId"],
+  Workflow: ["workflowId"],
+  WorkflowStep: ["stepId"],
+  WorkflowRun: ["runId"],
+  Preference: ["preferenceId"],
+  Email: ["emailId", "messageId"],
+  AdminUser: ["userId"],
+  ToolCall: ["callId"],
+  // Composite component nulls — frees the composite constraint:
+  AccessGrant: ["contactValue"],     // composite (contactValue, agentSlug, accountId)
+  UserProfile: ["userId"],           // composite (accountId, userId)
+};
+
+const TRASH_PROP_NAMES = [
+  "trashedAt",
+  "trashedBy",
+  "trashReason",
+  "_trashedKeys",
+] as const;
+
+export interface TrashParams {
+  session: Session;
+  accountId: string;
+  elementId: string;
+  /** Provenance marker — appears verbatim in `trashedBy` and `[trash:marked] by=`. */
+  by: string;
+  reason?: string;
+}
+
+export interface TrashResult {
+  trashed: boolean;
+  alreadyTrashed: boolean;
+  nodeId: string;
+  /** Labels excluding `:Trashed`. */
+  labels: string[];
+  trashedAt: string;
+  originalKeys: Record<string, unknown>;
+}
+
+export async function trashNode(params: TrashParams): Promise<TrashResult> {
+  const { session, accountId, elementId, by, reason } = params;
+
+  const lookup = await session.run(
+    `MATCH (n) WHERE elementId(n) = $eid AND n.accountId = $accountId
+     RETURN labels(n) AS labels, properties(n) AS props`,
+    { eid: elementId, accountId },
+  );
+  if (lookup.records.length === 0) {
+    throw new Error(
+      `trashNode: node not found (elementId=${elementId} accountId=${accountId.slice(0, 8)}…)`,
+    );
+  }
+
+  const allLabels = lookup.records[0].get("labels") as string[];
+  const props = lookup.records[0].get("props") as Record<string, unknown>;
+  const baseLabels = allLabels.filter((l) => l !== "Trashed");
+
+  if (allLabels.includes("Trashed")) {
+    return {
+      trashed: false,
+      alreadyTrashed: true,
+      nodeId: elementId,
+      labels: baseLabels,
+      trashedAt: String(props.trashedAt ?? ""),
+      originalKeys: {},
+    };
+  }
+
+  const uniqueKeys = new Set<string>();
+  for (const label of baseLabels) {
+    for (const key of UNIQUE_KEYS_BY_LABEL[label] ?? []) uniqueKeys.add(key);
+  }
+
+  const originalKeys: Record<string, unknown> = {};
+  for (const k of uniqueKeys) {
+    if (props[k] !== undefined && props[k] !== null) originalKeys[k] = props[k];
+  }
+
+  const setNullClauses = Object.keys(originalKeys)
+    .map((k) => `n.\`${k}\` = null`)
+    .join(", ");
+  const setNullSuffix = setNullClauses ? `, ${setNullClauses}` : "";
+
+  const trashedAt = new Date().toISOString();
+  await session.run(
+    `MATCH (n) WHERE elementId(n) = $eid
+     SET n:Trashed,
+         n.trashedAt = datetime($trashedAt),
+         n.trashedBy = $by,
+         n.trashReason = $reason,
+         n._trashedKeys = $trashedKeysJson${setNullSuffix}`,
+    {
+      eid: elementId,
+      trashedAt,
+      by,
+      reason: reason ?? null,
+      trashedKeysJson: JSON.stringify(originalKeys),
+    },
+  );
+
+  process.stderr.write(
+    `[trash:marked] accountId=${accountId} elementId=${elementId} labels=${baseLabels.join(",")} by=${by} reason=${reason ?? "null"}\n`,
+  );
+
+  return {
+    trashed: true,
+    alreadyTrashed: false,
+    nodeId: elementId,
+    labels: baseLabels,
+    trashedAt,
+    originalKeys,
+  };
+}
+
+export interface RestoreParams {
+  session: Session;
+  accountId: string;
+  elementId: string;
+}
+
+export interface RestoreResult {
+  restored: boolean;
+  nodeId: string;
+  labels: string[];
+  restoredKeys: Record<string, unknown>;
+}
+
+export async function restoreNode(params: RestoreParams): Promise<RestoreResult> {
+  const { session, accountId, elementId } = params;
+
+  const lookup = await session.run(
+    `MATCH (n:Trashed) WHERE elementId(n) = $eid
+     RETURN labels(n) AS labels, n._trashedKeys AS keysJson`,
+    { eid: elementId },
+  );
+  if (lookup.records.length === 0) {
+    throw new Error(
+      `restoreNode: trashed node not found (elementId=${elementId})`,
+    );
+  }
+
+  const allLabels = lookup.records[0].get("labels") as string[];
+  const baseLabels = allLabels.filter((l) => l !== "Trashed");
+  const keysJson = lookup.records[0].get("keysJson") as string | null;
+  const originalKeys: Record<string, unknown> = keysJson ? JSON.parse(keysJson) : {};
+
+  // Conflict check: an active node already holds the unique slot we want back?
+  for (const label of baseLabels) {
+    const uniqueKeys = UNIQUE_KEYS_BY_LABEL[label] ?? [];
+    for (const k of uniqueKeys) {
+      const v = originalKeys[k];
+      if (v === undefined || v === null) continue;
+      const conflict = await session.run(
+        `MATCH (other:\`${label}\`)
+         WHERE elementId(other) <> $eid
+           AND NOT other:Trashed
+           AND other.\`${k}\` = $val
+         RETURN elementId(other) AS otherId LIMIT 1`,
+        { eid: elementId, val: v },
+      );
+      if (conflict.records.length > 0) {
+        const otherId = conflict.records[0].get("otherId") as string;
+        throw new Error(
+          `restoreNode: cannot restore ${label} elementId=${elementId} — active node elementId=${otherId} already holds ${k}=${JSON.stringify(v)}`,
+        );
+      }
+    }
+  }
+
+  const setClauses = Object.keys(originalKeys)
+    .map((k) => `n.\`${k}\` = $val_${k}`)
+    .join(", ");
+  const setSuffix = setClauses ? `, ${setClauses}` : "";
+  const setParams: Record<string, unknown> = { eid: elementId };
+  for (const [k, v] of Object.entries(originalKeys)) setParams[`val_${k}`] = v;
+
+  await session.run(
+    `MATCH (n:Trashed) WHERE elementId(n) = $eid
+     REMOVE n:Trashed, n.trashedAt, n.trashedBy, n.trashReason, n._trashedKeys
+     SET n.restoredAt = datetime()${setSuffix}`,
+    setParams,
+  );
+
+  process.stderr.write(
+    `[trash:restored] accountId=${accountId} elementId=${elementId} labels=${baseLabels.join(",")}\n`,
+  );
+
+  return {
+    restored: true,
+    nodeId: elementId,
+    labels: baseLabels,
+    restoredKeys: originalKeys,
+  };
+}
+
+export interface EmptyTrashParams {
+  session: Session;
+  accountId: string;
+  /** Default 30. */
+  graceDays?: number;
+  dryRun?: boolean;
+  /** Optional label whitelist — only nodes carrying any of these labels are eligible. */
+  labels?: string[];
+  /** Side-effect callback invoked per emptied node, e.g. to clean disk attachments. */
+  onEmpty?: (node: TrashCandidate) => Promise<void>;
+}
+
+export interface TrashCandidate {
+  elementId: string;
+  labels: string[];
+  trashedAt: string;
+  trashedBy: string | null;
+  /** Original unique-key snapshot — useful for KnowledgeDocument disk cleanup. */
+  trashedKeys: Record<string, unknown>;
+}
+
+export interface EmptyTrashResult {
+  graceDays: number;
+  dryRun: boolean;
+  candidates: TrashCandidate[];
+  emptied: number;
+}
+
+export async function emptyTrash(params: EmptyTrashParams): Promise<EmptyTrashResult> {
+  const t0 = Date.now();
+  const { session, accountId, graceDays = 30, dryRun = false, labels: labelFilter, onEmpty } = params;
+
+  const cutoff = new Date(Date.now() - graceDays * 24 * 60 * 60 * 1000).toISOString();
+
+  const labelClause = labelFilter && labelFilter.length > 0
+    ? `AND ANY(l IN labels(n) WHERE l IN $labelFilter)`
+    : "";
+
+  const candidatesResult = await session.run(
+    `MATCH (n:Trashed)
+     WHERE n.trashedAt < datetime($cutoff)
+     ${labelClause}
+     RETURN elementId(n) AS eid,
+            labels(n) AS labels,
+            toString(n.trashedAt) AS trashedAt,
+            n.trashedBy AS trashedBy,
+            n._trashedKeys AS keysJson
+     ORDER BY n.trashedAt ASC`,
+    { cutoff, ...(labelFilter ? { labelFilter } : {}) },
+  );
+
+  const candidates: TrashCandidate[] = candidatesResult.records.map((r) => {
+    const keysJson = r.get("keysJson") as string | null;
+    return {
+      elementId: r.get("eid") as string,
+      labels: (r.get("labels") as string[]).filter((l) => l !== "Trashed"),
+      trashedAt: String(r.get("trashedAt")),
+      trashedBy: (r.get("trashedBy") as string | null) ?? null,
+      trashedKeys: keysJson ? JSON.parse(keysJson) : {},
+    };
+  });
+
+  process.stderr.write(
+    `[trash:empty-run] accountId=${accountId} graceDays=${graceDays} dryRun=${dryRun} candidates=${candidates.length}\n`,
+  );
+
+  if (dryRun || candidates.length === 0) {
+    process.stderr.write(
+      `[graph:trash:summary] accountId=${accountId} trashedNow=0 emptiedThisRun=0 graceDays=${graceDays} dryRun=${dryRun} elapsedMs=${Date.now() - t0}\n`,
+    );
+    return { graceDays, dryRun, candidates, emptied: 0 };
+  }
+
+  let emptied = 0;
+  for (const c of candidates) {
+    if (onEmpty) {
+      try {
+        await onEmpty(c);
+      } catch (err) {
+        process.stderr.write(
+          `[trash:empty-run] onEmpty side-effect failed for elementId=${c.elementId}: ${err instanceof Error ? err.message : String(err)}\n`,
+        );
+      }
+    }
+
+    await session.run(
+      `MATCH (n) WHERE elementId(n) = $eid DETACH DELETE n`,
+      { eid: c.elementId },
+    );
+
+    const ageDays = Math.floor((Date.now() - new Date(c.trashedAt).getTime()) / (24 * 60 * 60 * 1000));
+    process.stderr.write(
+      `[trash:emptied] accountId=${accountId} elementId=${c.elementId} labels=${c.labels.join(",")} trashedAt=${c.trashedAt} ageDays=${ageDays}\n`,
+    );
+    emptied++;
+  }
+
+  process.stderr.write(
+    `[graph:trash:summary] accountId=${accountId} trashedNow=0 emptiedThisRun=${emptied} graceDays=${graceDays} dryRun=${dryRun} elapsedMs=${Date.now() - t0}\n`,
+  );
+
+  return { graceDays, dryRun, candidates, emptied };
+}
+
+/**
+ * Read-filter clause excluding trashed nodes for the given Cypher alias.
+ *
+ * Filters both the `:Trashed` label (Task 576 primitive) and the legacy
+ * `deletedAt` property (KnowledgeDocument soft-delete pre-Task 576). The
+ * `deletedAt` arm is a transitional belt-and-braces — production graphs may
+ * still hold pre-migration soft-deletes — and stays until those are confirmed
+ * empty, then is dropped.
+ *
+ *   notTrashed("node")    → "(NOT node:Trashed AND node.deletedAt IS NULL)"
+ *   notTrashed("related") → "(NOT related:Trashed AND related.deletedAt IS NULL)"
+ */
+export function notTrashed(alias: string): string {
+  return `(NOT \`${alias}\`:Trashed AND \`${alias}\`.deletedAt IS NULL)`;
+}
+
+/** Runtime accessor for the static unique-keys map (for tests + sibling tooling). */
+export function uniqueKeysForLabels(labels: string[]): string[] {
+  const out = new Set<string>();
+  for (const l of labels) for (const k of UNIQUE_KEYS_BY_LABEL[l] ?? []) out.add(k);
+  return [...out];
+}
+
+/** Property names trashNode writes — exposed so callers can re-MERGE without colliding. */
+export const TRASH_METADATA_PROPS: readonly string[] = TRASH_PROP_NAMES;

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

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

package/payload/platform/neo4j/schema.cypher

@@ -613,3 +613,22 @@ FOR (tc:ToolCall) REQUIRE tc.callId IS UNIQUE;
 
 CREATE INDEX tool_call_account_started IF NOT EXISTS
 FOR (tc:ToolCall) ON (tc.accountId, tc.startedAt);
+
+// ----------------------------------------------------------
+// :Trashed — Task 576 soft-delete primitive.
+//
+// Any node soft-deleted via memory-delete / contact-delete carries this
+// label plus trashedAt / trashedBy / trashReason / _trashedKeys properties.
+// memory-empty-trash hard-deletes by `MATCH (n:Trashed) WHERE n.trashedAt < cutoff`,
+// and the trash-census + read-filter probes in memory-search hit the same
+// label. The accountId index supports per-tenant census reads — accountId-as-
+// unique-key labels (LocalBusiness, OnboardingState) have their accountId
+// nulled on trash and are missed by accountId-scoped reads, but those are
+// 1-per-account labels and rare in trash.
+// ----------------------------------------------------------
+
+CREATE INDEX trashed_account IF NOT EXISTS
+FOR (n:Trashed) ON (n.accountId);
+
+CREATE INDEX trashed_at IF NOT EXISTS
+FOR (n:Trashed) ON (n.trashedAt);

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/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/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/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: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/cloudflare/scripts/_stream-log.sh

@@ -6,13 +6,28 @@
 # helpers to emit phase lines and tee subprocess output into the same
 # per-conversation file the chat UI's server-side tailer reads.
 #
-# Contract (read by platform/ui/app/api/admin/chat/route.ts tailer and
+# Contract (read by platform/ui/app/lib/script-stream-tailer.ts tailer and
 # .docs/platform.md):
 #   [<ISO-ts>] [<scope>] <kv …>
 #   [<ISO-ts>] [<scope>:<subprocess-tag>] <raw line>
-# where <scope> ∈ {setup-tunnel, reset-tunnel}. The tailer regex is
-#   ^\[[^]]+\] \[(setup-tunnel|reset-tunnel)(:[^]]+)?\]
-# so any prefix change must be made on both sides atomically.
+# Canonical regex — SCRIPT_STREAM_RE at platform/ui/app/lib/script-stream-tailer.ts:51:
+#   ^\[([^\]]+)\] \[([a-z][a-z0-9-]*)((?::[a-z0-9:_-]+)?)\] (.*)$
+# <scope> is any `[a-z][a-z0-9-]*` token (Task 592 generalised from the
+# pre-592 enum `setup-tunnel|reset-tunnel`, which silently filtered out the
+# `[list-cf-domains]` lines Task 589 emitted). <subprocess-tag> may contain
+# lowercase, digits, `-`, `_`, `:`. Adding a new <scope> requires no edit to
+# the regex — the shape is the only contract. Any prefix-shape change must
+# be made on both sides (this helper + script-stream-tailer.ts) atomically.
+#
+# Inner layers (e.g. a node/python helper a .sh wrapper spawns — Task 598's
+# `list-cf-domains.sh` → `list-cf-domains.ts` pattern) must write phase lines
+# directly to STREAM_LOG_PATH with the same prefix shape: stderr alone is
+# silently discarded by runFormSpawn on exit 0. The build-gate
+# `platform/ui/scripts/check-stream-log-contract.mjs` (Task 600) enforces this
+# by rejecting any .sh under `platform/plugins/*/scripts/` that sources this
+# helper and invokes an interpreter subprocess whose target does not pair a
+# STREAM_LOG_PATH env read with an append/write call. Opt out per invocation
+# with `# stream-log-contract: stderr-only (reason: <prose>)`.
 
 # Exit 1 loudly with the variable name and the invoking scope so direct-SSH
 # invocations fail fast and the operator reads exactly what to set. No