@rubytech/create-realagent 1.0.838 → 1.0.840

package/payload/platform/neo4j/migrations/004-project-admin-agent.ts

@@ -1,348 +0,0 @@
-/**
- * Migration 004 — Project the admin agent into the graph and clean up
- * Conversation channel data (Task 864). Numbered 004 because the 003
- * slot is held by `003-person-name-eradicate.cypher` (boot-time apply).
- *
- * Three idempotent passes:
- *
- *   1. For every account directory under data/accounts/<accountId>/agents/admin/
- *      that carries a config.json, call projectAgent(accountId, accountDir,
- *      'admin'). The projector is the same function migration 002 uses for
- *      public agents and is content-agnostic — it reads config.json plus any
- *      IDENTITY/SOUL/KNOWLEDGE/KNOWLEDGE-SUMMARY files present and MERGEs the
- *      :Agent node + four owned :KnowledgeDocument projections. Re-running
- *      this migration produces no duplicate nodes or edges.
- *
- *      Migration 002 explicitly SKIPS admin (line 60: `if (entry.name ===
- *      "admin") continue`); doing the projection here keeps that skip valid
- *      and isolates admin-specific concerns to one file.
- *
- *   2. For every existing :AdminConversation that does NOT yet have a
- *      :HANDLED_BY edge, MATCH the freshly-projected admin :Agent and MERGE
- *      the edge. Guarded with `WHERE NOT EXISTS((c)-[:HANDLED_BY]->(:Agent))`
- *      so re-runs short-circuit per conversation.
- *
- *   3. Backfill `c.channel = 'webchat'` for every Conversation node where
- *      channel IS NULL. Pre-Task-863 conversations were written without the
- *      property; channel='webchat' is the correct default — only WhatsApp
- *      and Telegram sessions ever set non-webchat values, and those have
- *      always come through sessionKeys prefixed `whatsapp:` or `telegram:`
- *      (see neo4j-store.ts:171). Idempotent: subsequent runs no-op because
- *      the WHERE clause matches zero rows.
- *
- * Boot-time entry point (Task 871): {@link applyAdminAgentBackfill}. The
- * neo4j-migrations runner calls it from `applyBootMigrations` AFTER
- * `pruneAlienAccounts` so we never project :Agent for an account that the
- * preceding pass would prune.
- *
- * Manual standalone entry point (legacy, retained for ad-hoc operator
- * runs):
- *
- *   cd platform/ui && \
- *     NEO4J_URI=bolt://… NEO4J_PASSWORD=… \
- *     npx tsx ../neo4j/migrations/004-project-admin-agent.ts
- *
- * Output: structured `[admin-agent-graph-backfill]` lines per account + a
- * final totals line. Both entry points emit identical log lines.
- */
-
-import { existsSync, readFileSync, readdirSync } from "node:fs";
-import { resolve } from "node:path";
-import { projectAgent, getSession } from "../../ui/app/lib/neo4j-store";
-import { ACCOUNTS_DIR } from "../../ui/app/lib/claude-agent/account";
-
-/**
- * Account-json filter (Task 900 sub-scope F) — admits only directories whose
- * `account.json` parses. Stub directories (e.g. `0dbf29ef-…/logs/` left
- * behind after install 1's `account.json` was lost) are SKIPPED with a
- * one-line `[platform] accounts-state STUB-DIR id=<dir>` log. Mirrors
- * `listValidAccounts()` in `account.ts`; copied here because this migration
- * runs at boot from a separate node_modules-resolution context (see the
- * structural-typing rationale at the top of `004-prune-alien-accounts.ts`).
- */
-function readValidAccountDirs(accountsDir: string): string[] {
-  const valid: string[] = [];
-  const entries = readdirSync(accountsDir, { withFileTypes: true })
-    .filter((e) => e.isDirectory())
-    .filter((e) => !e.name.startsWith("."));
-  for (const e of entries) {
-    const configPath = resolve(accountsDir, e.name, "account.json");
-    if (!existsSync(configPath)) {
-      console.error(
-        `[platform] accounts-state STUB-DIR id=${e.name} — onboarding leak; remove or repair`,
-      );
-      continue;
-    }
-    try {
-      JSON.parse(readFileSync(configPath, "utf-8"));
-      valid.push(e.name);
-    } catch {
-      console.error(
-        `[platform] accounts-state CORRUPT-JSON id=${e.name} — account.json failed to parse`,
-      );
-    }
-  }
-  return valid;
-}
-
-/**
- * Structural alias for the `Driver` instance the runner passes in. Same
- * rationale as `004-prune-alien-accounts.ts`: this file lives outside
- * `platform/ui/`, and depending on the workspace's dedupe state,
- * `neo4j-driver` resolves to a different node_modules copy here than at
- * the boot-loader site. Structural typing sidesteps the nominal-distinct-
- * types-from-different-paths trap.
- */
-type Neo4jDriverLike = {
-  session(): {
-    run(
-      cypher: string,
-      params?: Record<string, unknown>,
-    ): Promise<{ records: Array<{ get(key: string): unknown }> }>;
-    close(): Promise<void>;
-  };
-};
-
-interface PerAccountStats {
-  accountId: string;
-  projected: 0 | 1;
-  failed: 0 | 1;
-  handledByCandidates: number;
-  handledByEdges: number;
-  channelBackfilled: number;
-}
-
-async function projectAccountAdmin(
-  accountId: string,
-  accountDir: string,
-): Promise<{ projected: 0 | 1; failed: 0 | 1 }> {
-  const adminDir = resolve(accountDir, "agents", "admin");
-  const configPath = resolve(adminDir, "config.json");
-  if (!existsSync(adminDir) || !existsSync(configPath)) {
-    return { projected: 0, failed: 0 };
-  }
-  try {
-    await projectAgent(accountId, accountDir, "admin");
-    return { projected: 1, failed: 0 };
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    console.error(
-      `[admin-agent-graph-backfill] account=${accountId.slice(0, 8)} project FAILED error="${msg}"`,
-    );
-    return { projected: 0, failed: 1 };
-  }
-}
-
-interface HandledByStats {
-  candidates: number;
-  edges: number;
-}
-
-/**
- * Backfill HANDLED_BY edges from AdminConversation nodes to the admin Agent
- * node. Guarded with NOT EXISTS so re-runs of this migration don't redo work
- * — and so AdminConversations that already gained a HANDLED_BY edge through
- * the forward path are skipped.
- *
- * `candidates` counts AdminConversations that LACK a HANDLED_BY edge; `edges`
- * counts edges newly created. The admin :Agent must already exist (created
- * by pass 1); if it doesn't, the OPTIONAL MATCH falls through and zero edges
- * are written — surfaced through `candidates - edges`.
- */
-async function backfillAdminHandledBy(
-  driver: Neo4jDriverLike,
-  accountId: string,
-): Promise<HandledByStats> {
-  const session = driver.session();
-  try {
-    const result = await session.run(
-      `MATCH (c:AdminConversation {accountId: $accountId})
-       WHERE NOT EXISTS((c)-[:HANDLED_BY]->(:Agent))
-       OPTIONAL MATCH (a:Agent {accountId: $accountId, slug: 'admin'})
-       FOREACH (_ IN CASE WHEN a IS NULL THEN [] ELSE [1] END | MERGE (c)-[:HANDLED_BY]->(a))
-       RETURN
-         count(c) AS candidates,
-         sum(CASE WHEN a IS NULL THEN 0 ELSE 1 END) AS edges`,
-      { accountId },
-    );
-    const toNum = (v: unknown): number => {
-      if (typeof v === "number") return v;
-      if (v && typeof (v as { toNumber: () => number }).toNumber === "function") {
-        return (v as { toNumber: () => number }).toNumber();
-      }
-      return 0;
-    };
-    return {
-      candidates: toNum(result.records[0]?.get("candidates")),
-      edges: toNum(result.records[0]?.get("edges")),
-    };
-  } finally {
-    await session.close();
-  }
-}
-
-/**
- * Backfill `c.channel = 'webchat'` on Conversation nodes that lack the
- * property. Hits both AdminConversation and PublicConversation — the
- * predicate is `c.channel IS NULL`, label-agnostic.
- *
- * Why default to 'webchat': new writes set channel from sessionKey prefix
- * (neo4j-store.ts:171). Only `whatsapp:` and `telegram:` prefixes produce
- * non-webchat values, and those prefixes have always existed. So a NULL
- * channel can only mean "Conversation written before Task 863 added the
- * SET clause" — which by definition was a webchat session.
- *
- * Idempotent: WHERE clause matches zero rows on re-run.
- */
-async function backfillChannel(
-  driver: Neo4jDriverLike,
-  accountId: string,
-): Promise<number> {
-  const session = driver.session();
-  try {
-    const result = await session.run(
-      `MATCH (c:Conversation {accountId: $accountId})
-       WHERE c.channel IS NULL
-       SET c.channel = 'webchat'
-       RETURN count(c) AS backfilled`,
-      { accountId },
-    );
-    const raw = result.records[0]?.get("backfilled");
-    if (typeof raw === "number") return raw;
-    if (raw && typeof (raw as { toNumber: () => number }).toNumber === "function") {
-      return (raw as { toNumber: () => number }).toNumber();
-    }
-    return 0;
-  } finally {
-    await session.close();
-  }
-}
-
-/**
- * Boot-time entry point (Task 871). Idempotent across every pass; safe to
- * run on every server boot. Throws on fatal failure; per-account failures
- * are logged and counted but do not abort the run (subsequent accounts
- * still get processed). The neo4j-migrations runner wraps this in its own
- * try/catch so a throw here is logged as `[migration] failed
- * admin-agent-graph-backfill error="…"` and boot continues.
- *
- * Refusal posture: if `<platformRoot>/../data/accounts` does not exist,
- * logs and returns silently — nothing to do (matches pruneAlienAccounts).
- */
-export async function applyAdminAgentBackfill(
-  driver: Neo4jDriverLike,
-  platformRoot: string,
-): Promise<void> {
-  const accountsDir = resolve(platformRoot, "..", "data", "accounts");
-  const start = Date.now();
-
-  if (!existsSync(accountsDir)) {
-    console.error(
-      `[admin-agent-graph-backfill] accounts-dir missing at ${accountsDir} — nothing to do`,
-    );
-    return;
-  }
-
-  const accountEntries = readValidAccountDirs(accountsDir).map((name) => ({ name }));
-
-  console.error(
-    `[admin-agent-graph-backfill] start accounts=${accountEntries.length}`,
-  );
-
-  let totalProjected = 0;
-  let totalFailed = 0;
-  let totalHandledByCandidates = 0;
-  let totalHandledByEdges = 0;
-  let totalChannelBackfilled = 0;
-  const perAccount: PerAccountStats[] = [];
-
-  for (const entry of accountEntries) {
-    const accountDir = resolve(accountsDir, entry.name);
-    const accountId = entry.name;
-    const accountStart = Date.now();
-
-    const { projected, failed } = await projectAccountAdmin(
-      accountId,
-      accountDir,
-    );
-    totalProjected += projected;
-    totalFailed += failed;
-
-    let handledByStats: HandledByStats = { candidates: 0, edges: 0 };
-    let channelBackfilled = 0;
-
-    try {
-      handledByStats = await backfillAdminHandledBy(driver, accountId);
-      totalHandledByCandidates += handledByStats.candidates;
-      totalHandledByEdges += handledByStats.edges;
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      console.error(
-        `[admin-agent-graph-backfill] account=${accountId.slice(0, 8)} handled-by-backfill FAILED error="${msg}"`,
-      );
-    }
-
-    try {
-      channelBackfilled = await backfillChannel(driver, accountId);
-      totalChannelBackfilled += channelBackfilled;
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      console.error(
-        `[admin-agent-graph-backfill] account=${accountId.slice(0, 8)} channel-backfill FAILED error="${msg}"`,
-      );
-    }
-
-    perAccount.push({
-      accountId,
-      projected,
-      failed,
-      handledByCandidates: handledByStats.candidates,
-      handledByEdges: handledByStats.edges,
-      channelBackfilled,
-    });
-    const ms = Date.now() - accountStart;
-    console.error(
-      `[admin-agent-graph-backfill] account=${accountId.slice(0, 8)} projected=${projected} failed=${failed} handled-by-candidates=${handledByStats.candidates} handled-by-edges=${handledByStats.edges} channel-backfilled=${channelBackfilled} ms=${ms}`,
-    );
-  }
-
-  const ms = Date.now() - start;
-  console.error(
-    `[admin-agent-graph-backfill] done totals: projected=${totalProjected} failed=${totalFailed} handled-by-candidates=${totalHandledByCandidates} handled-by-edges=${totalHandledByEdges} channel-backfilled=${totalChannelBackfilled} ms=${ms}`,
-  );
-}
-
-/**
- * Standalone entry point — retained for manual `npx tsx` runs (Task 871
- * preserved this so an operator can re-run the backfill ad-hoc without a
- * full server boot). Wraps `applyAdminAgentBackfill` with a structural
- * driver-shape that delegates to the neo4j-store singleton's getSession,
- * so the env-var resolution (NEO4J_URI / NEO4J_PASSWORD / config file)
- * matches the boot path exactly.
- */
-async function main(): Promise<void> {
-  if (!existsSync(ACCOUNTS_DIR)) {
-    console.error(
-      `[admin-agent-graph-backfill] ACCOUNTS_DIR missing at ${ACCOUNTS_DIR} — nothing to do`,
-    );
-    process.exit(0);
-  }
-  const driverShim: Neo4jDriverLike = { session: () => getSession() };
-  const platformRoot = resolve(ACCOUNTS_DIR, "..", "..", "platform");
-  try {
-    await applyAdminAgentBackfill(driverShim, platformRoot);
-    process.exit(0);
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    console.error(`[admin-agent-graph-backfill] fatal error="${msg}"`);
-    process.exit(2);
-  }
-}
-
-if (process.argv[1]?.endsWith("004-project-admin-agent.ts")) {
-  main().catch((err) => {
-    const msg = err instanceof Error ? err.message : String(err);
-    console.error(`[admin-agent-graph-backfill] fatal error="${msg}"`);
-    process.exit(2);
-  });
-}

package/payload/platform/neo4j/migrations/004-prune-alien-accounts.ts

@@ -1,133 +0,0 @@
-/**
- * Migration 004 — Prune alien-account nodes (Task 847).
- *
- * Deletes every node whose `accountId` is not present on disk under
- * `${DATA_ROOT}/accounts/<uuid>/account.json`. Idempotent — silent when
- * the graph is already clean.
- *
- * Why a backstop, not a writer fix: the leaked nodes were written by a
- * since-removed writer. With no live writer to fix, this is the surface
- * that catches future writer drift.
- *
- * Hard guard: refuses to run when the on-disk account set is empty
- * (corrupt-install scenario). Refusing to wipe the graph is louder than
- * silently wiping it.
- *
- * Doctrine in `.docs/neo4j.md` "Account isolation invariant" requires
- * any writer that stamps `n.accountId` to verify the value against
- * `${DATA_ROOT}/accounts/<id>/account.json` before write. This migration
- * is a backstop, not a license.
- */
-
-import { readFileSync, readdirSync } from "node:fs";
-import { resolve } from "node:path";
-
-const UUID_RE =
-  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-
-/**
- * Structural alias for the `Driver` instance the runner passes in. We type
- * structurally rather than importing `Driver` from `neo4j-driver` because
- * this file lives outside `platform/ui/` — depending on the workspace's
- * dedupe state, `neo4j-driver` resolves to a different node_modules copy
- * here than at the runner site, and TS treats two same-shape types from
- * different paths as nominally distinct. Structural typing sidesteps that.
- */
-type Neo4jDriverLike = {
-  session(): {
-    run(
-      cypher: string,
-      params?: Record<string, unknown>,
-    ): Promise<{ records: Array<{ get(key: string): unknown }> }>;
-    close(): Promise<void>;
-  };
-};
-
-export async function pruneAlienAccounts(
-  driver: Neo4jDriverLike,
-  platformRoot: string,
-): Promise<void> {
-  const accountsDir = resolve(platformRoot, "..", "data", "accounts");
-  const validIds = enumerateValidAccountIds(accountsDir);
-
-  if (validIds.size === 0) {
-    throw new Error(
-      `refusing to prune: no valid accounts found under ${accountsDir} — corrupt install? not deleting anything to avoid wiping the entire graph.`,
-    );
-  }
-
-  const valid = Array.from(validIds);
-  const session = driver.session();
-  try {
-    // Two-step: first query collects the alien accountIds for the log
-    // line, second query deletes. Two cheap queries beat a single query
-    // that loses either the count or the id list under DELETE semantics.
-    const peek = await session.run(
-      `MATCH (n)
-       WHERE n.accountId IS NOT NULL AND NOT n.accountId IN $valid
-       RETURN DISTINCT n.accountId AS aid`,
-      { valid },
-    );
-    const alienIds: string[] = [];
-    for (const record of peek.records) {
-      const aid: unknown = record.get("aid");
-      if (typeof aid === "string") alienIds.push(aid);
-    }
-
-    if (alienIds.length === 0) return;
-
-    const result = await session.run(
-      `MATCH (n)
-       WHERE n.accountId IS NOT NULL AND NOT n.accountId IN $valid
-       DETACH DELETE n
-       RETURN count(n) AS pruned`,
-      { valid },
-    );
-    const prunedRaw = result.records[0]?.get("pruned");
-    const pruned =
-      typeof prunedRaw === "number"
-        ? prunedRaw
-        : (prunedRaw as { toNumber?: () => number })?.toNumber?.() ?? 0;
-    console.error(
-      `[graph-invariant] alien-accounts pruned=${pruned} accountIds=${alienIds.join(",")}`,
-    );
-  } finally {
-    await session.close();
-  }
-}
-
-/**
- * Enumerate accountIds with a parseable `account.json`. Directory name IS
- * the canonical accountId (matches the UUID_RE.test(name) predicate at
- * `platform/ui/server/routes/admin/files.ts`'s account-name resolver).
- *
- * Corruption discipline: a present-but-unparseable account.json is
- * EXCLUDED from the valid set and emits a skip log line. Better to
- * over-prune one suspect account than under-prune the leak it might
- * be hiding.
- */
-function enumerateValidAccountIds(accountsDir: string): Set<string> {
-  const valid = new Set<string>();
-  let names: string[];
-  try {
-    names = readdirSync(accountsDir);
-  } catch (err) {
-    if ((err as NodeJS.ErrnoException).code === "ENOENT") return valid;
-    throw err;
-  }
-  for (const name of names) {
-    if (!UUID_RE.test(name)) continue;
-    const configPath = resolve(accountsDir, name, "account.json");
-    try {
-      JSON.parse(readFileSync(configPath, "utf-8"));
-      valid.add(name);
-    } catch (err) {
-      const code = (err as NodeJS.ErrnoException).code ?? "parse-error";
-      if (code === "ENOENT") continue;
-      console.error(
-        `[graph-invariant] account-json-skip uuid=${name} reason=${code}`,
-      );
-    }
-  }
-  return valid;
-}

package/payload/platform/neo4j/migrations/005-removed-review-feature.ts

@@ -1,102 +0,0 @@
-/**
- * Migration 005 — Remove review-detector / review-digest feature artefacts (Task 884).
- *
- * The review-detector subsystem was wired into boot, MERGEd a daily `:Event`
- * with `actionTool="review-digest-compose"` on every start, and aggregated
- * `:ReviewAlert` nodes via rule matches. The feature is deleted entirely;
- * this migration is the boot-sweep that removes the residue from existing
- * installs. Idempotent — once the graph is clean, both queries DETACH DELETE
- * zero rows and the log line records `events=0 alerts=0`.
- *
- * Filesystem artefacts (`review.log`, `review-rules.json`, `review-state.json`,
- * `review-pending-alerts.jsonl`) are also removed best-effort — ENOENT is the
- * idempotent no-op; any other errno is logged and ignored so a sticky permission
- * problem does not block boot.
- *
- * Same structural-type pattern as 004-prune-alien-accounts.ts: the runner sits
- * outside `platform/ui/` so depending on the workspace dedupe state the
- * `neo4j-driver` import resolves to a different node_modules copy, and TS
- * treats two same-shape types from different paths as nominally distinct.
- */
-
-import { resolve } from "node:path";
-import { unlinkSync } from "node:fs";
-import { homedir } from "node:os";
-import { basename, dirname } from "node:path";
-
-type Neo4jDriverLike = {
-  session(): {
-    run(
-      cypher: string,
-      params?: Record<string, unknown>,
-    ): Promise<{ records: Array<{ get(key: string): unknown }> }>;
-    close(): Promise<void>;
-  };
-};
-
-export async function removeReviewFeature(
-  driver: Neo4jDriverLike,
-  platformRoot: string,
-): Promise<void> {
-  const session = driver.session();
-  let eventsDeleted = 0;
-  let alertsDeleted = 0;
-
-  try {
-    const eventResult = await session.run(
-      `MATCH (e:Event)
-       WHERE e.actionTool = "review-digest-compose"
-          OR e.eventId STARTS WITH "review-digest-"
-       DETACH DELETE e
-       RETURN count(e) AS deleted`,
-    );
-    eventsDeleted = toNumber(eventResult.records[0]?.get("deleted"));
-
-    const alertResult = await session.run(
-      `MATCH (a:ReviewAlert)
-       DETACH DELETE a
-       RETURN count(a) AS deleted`,
-    );
-    alertsDeleted = toNumber(alertResult.records[0]?.get("deleted"));
-  } finally {
-    await session.close();
-  }
-
-  // Best-effort filesystem cleanup. The configDir convention is
-  // `~/.<installDirName>` where installDir = dirname(platformRoot)
-  // (e.g. `~/maxy/platform` → `~/.maxy`).
-  const installDirName = basename(dirname(platformRoot));
-  const configDir = resolve(homedir(), `.${installDirName}`);
-  const artefacts = [
-    resolve(configDir, "logs", "review.log"),
-    resolve(configDir, "review-rules.json"),
-    resolve(configDir, "review-state.json"),
-    resolve(configDir, "review-pending-alerts.jsonl"),
-  ];
-  for (const path of artefacts) {
-    try {
-      unlinkSync(path);
-    } catch (err) {
-      const code = (err as NodeJS.ErrnoException).code;
-      if (code === "ENOENT") continue;
-      console.error(
-        `[migration] removed-review-feature unlink-skip path=${path} reason=${code ?? "unknown"}`,
-      );
-    }
-  }
-
-  console.error(
-    `[migration] removed-review-feature events=${eventsDeleted} alerts=${alertsDeleted}`,
-  );
-}
-
-function toNumber(v: unknown): number {
-  if (typeof v === "number") return v;
-  if (
-    v &&
-    typeof (v as { toNumber?: () => number }).toNumber === "function"
-  ) {
-    return (v as { toNumber: () => number }).toNumber();
-  }
-  return 0;
-}