@rubytech/create-realagent 1.0.811 → 1.0.813

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-realagent",
-  "version": "1.0.811",
+  "version": "1.0.813",
   "description": "Install Real Agent — Built for agents. By agents.",
   "bin": {
     "create-realagent": "./dist/index.js"

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

@@ -30,16 +30,20 @@
  *      (see neo4j-store.ts:171). Idempotent: subsequent runs no-op because
  *      the WHERE clause matches zero rows.
  *
- * Run via the platform/ui standalone runtime so it picks up the same
- * NEO4J_URI / accounts-directory resolution as the server:
+ * 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. Non-zero exit code on any per-account agent-projection
- * failure surfaces to the operator; subsequent accounts are still attempted.
+ * final totals line. Both entry points emit identical log lines.
  */
 
 import { existsSync, readdirSync } from "node:fs";
@@ -47,6 +51,24 @@ import { resolve } from "node:path";
 import { projectAgent, getSession } from "../../ui/app/lib/neo4j-store";
 import { ACCOUNTS_DIR } from "../../ui/app/lib/claude-agent/account";
 
+/**
+ * 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;
@@ -94,9 +116,10 @@ interface HandledByStats {
  * are written — surfaced through `candidates - edges`.
  */
 async function backfillAdminHandledBy(
+  driver: Neo4jDriverLike,
   accountId: string,
 ): Promise<HandledByStats> {
-  const session = getSession();
+  const session = driver.session();
   try {
     const result = await session.run(
       `MATCH (c:AdminConversation {accountId: $accountId})
@@ -137,8 +160,11 @@ async function backfillAdminHandledBy(
  *
  * Idempotent: WHERE clause matches zero rows on re-run.
  */
-async function backfillChannel(accountId: string): Promise<number> {
-  const session = getSession();
+async function backfillChannel(
+  driver: Neo4jDriverLike,
+  accountId: string,
+): Promise<number> {
+  const session = driver.session();
   try {
     const result = await session.run(
       `MATCH (c:Conversation {accountId: $accountId})
@@ -158,17 +184,32 @@ async function backfillChannel(accountId: string): Promise<number> {
   }
 }
 
-async function main(): Promise<void> {
+/**
+ * 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(ACCOUNTS_DIR)) {
+  if (!existsSync(accountsDir)) {
     console.error(
-      `[admin-agent-graph-backfill] ACCOUNTS_DIR missing at ${ACCOUNTS_DIR} — nothing to do`,
+      `[admin-agent-graph-backfill] accounts-dir missing at ${accountsDir} — nothing to do`,
     );
-    process.exit(0);
+    return;
   }
 
-  const accountEntries = readdirSync(ACCOUNTS_DIR, { withFileTypes: true })
+  const accountEntries = readdirSync(accountsDir, { withFileTypes: true })
     .filter((e) => e.isDirectory());
 
   console.error(
@@ -183,7 +224,7 @@ async function main(): Promise<void> {
   const perAccount: PerAccountStats[] = [];
 
   for (const entry of accountEntries) {
-    const accountDir = resolve(ACCOUNTS_DIR, entry.name);
+    const accountDir = resolve(accountsDir, entry.name);
     const accountId = entry.name;
     const accountStart = Date.now();
 
@@ -198,7 +239,7 @@ async function main(): Promise<void> {
     let channelBackfilled = 0;
 
     try {
-      handledByStats = await backfillAdminHandledBy(accountId);
+      handledByStats = await backfillAdminHandledBy(driver, accountId);
       totalHandledByCandidates += handledByStats.candidates;
       totalHandledByEdges += handledByStats.edges;
     } catch (err) {
@@ -209,7 +250,7 @@ async function main(): Promise<void> {
     }
 
     try {
-      channelBackfilled = await backfillChannel(accountId);
+      channelBackfilled = await backfillChannel(driver, accountId);
       totalChannelBackfilled += channelBackfilled;
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
@@ -236,12 +277,39 @@ async function main(): Promise<void> {
   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}`,
   );
+}
 
-  process.exit(totalFailed > 0 ? 1 : 0);
+/**
+ * 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);
+  }
 }
 
-main().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);
+  });
+}