@rubytech/create-realagent 1.0.806 → 1.0.807

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-realagent",
-  "version": "1.0.806",
+  "version": "1.0.807",
   "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

@@ -0,0 +1,247 @@
+/**
+ * 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.
+ *
+ * Run via the platform/ui standalone runtime so it picks up the same
+ * NEO4J_URI / accounts-directory resolution as the server:
+ *
+ *   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.
+ */
+
+import { existsSync, 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";
+
+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(
+  accountId: string,
+): Promise<HandledByStats> {
+  const session = getSession();
+  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(accountId: string): Promise<number> {
+  const session = getSession();
+  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();
+  }
+}
+
+async function main(): Promise<void> {
+  const start = Date.now();
+
+  if (!existsSync(ACCOUNTS_DIR)) {
+    console.error(
+      `[admin-agent-graph-backfill] ACCOUNTS_DIR missing at ${ACCOUNTS_DIR} — nothing to do`,
+    );
+    process.exit(0);
+  }
+
+  const accountEntries = readdirSync(ACCOUNTS_DIR, { withFileTypes: true })
+    .filter((e) => e.isDirectory());
+
+  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(ACCOUNTS_DIR, 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(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(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}`,
+  );
+
+  process.exit(totalFailed > 0 ? 1 : 0);
+}
+
+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

@@ -0,0 +1,134 @@
+/**
+ * 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 the
+ * `review-digest-compose` writer, which has since been removed in favour
+ * of a coming gbrain rewrite. With no live writer to fix, this is the
+ * surface that catches future writer drift before the next gbrain ships.
+ *
+ * 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/plugins/docs/references/graph.md

@@ -70,6 +70,48 @@ border, with their zoom-tier labels intact. The `N msgs` count excludes
 trashed Messages, so the detailed-tier label reflects only live turns in the
 conversation.
 
+## Filtering by channel and message kind
+
+When you select **AdminConversation** or **PublicConversation** in the
+filter popover, two extra rows appear underneath the chip list:
+
+- **Channel** — Web / WhatsApp. Select one to scope the canvas to
+  conversations that came in over that channel only. Selecting both is
+  the same as selecting neither (all channels). After the migration that
+  ships with this release, every conversation carries an explicit
+  channel value — pre-existing conversations are backfilled to "Web"
+  because only the WhatsApp and Telegram intake paths ever set non-Web
+  values.
+- **Message** — User / Assistant / WhatsApp. When you've also pivoted
+  into a conversation neighbourhood (or your search hits messages
+  directly), this row scopes the messages on canvas to the chosen kind.
+  WhatsApp messages persist with their own sublabel so you can isolate
+  the live-channel cohort from the agent-path cohort within the same
+  conversation.
+
+These sub-facets compose with the chip selection. Searching with the
+AdminConversation chip selected now also reaches the body text of every
+admin message — typing a rare word like "ATM" returns every conversation
+that mentions it, not just conversations with that word in the title.
+
+## Sidebar conversations list
+
+The Recents list above the chat sidebar carries a per-row marker:
+WhatsApp conversations show a small WhatsApp glyph next to the
+conversation name. The dropdown above the list filters Recents to a
+specific channel — flipping it to **WhatsApp** hides web-chat
+conversations and vice versa.
+
+## Agents in the graph
+
+Both admin and public agents appear as `:Agent` nodes in the graph. Open
+the **Agents** entry from the sidebar to see them all. Each agent
+carries a `:HANDLED_BY` edge from every conversation it has handled, so
+you can pivot from an agent to the conversations it ran. The admin
+agent's IDENTITY, SOUL, KNOWLEDGE, and KNOWLEDGE-SUMMARY documents
+appear as :KnowledgeDocument nodes connected via `HAS_*` edges, the same
+projection shape used for public agents.
+
 ## Agent-execution telemetry
 
 `ToolCall`, `StepResult`, `WorkflowStep`, and `WorkflowRun` nodes are

package/payload/platform/plugins/docs/references/internals.md

@@ -140,6 +140,8 @@ WHERE node.accountId = $accountId
 
 Multi-tenancy boundary. Every query is scoped to the requesting account. The `ACCOUNT_ID` environment variable is set at MCP server startup — it is not a tool parameter and cannot be overridden by the agent.
 
+The read filter alone is not sufficient — it correctly *hides* alien-account nodes from every UI but does not prevent them existing. A writer that misresolves `accountId` (literal, undefined, or inferred-from-the-wrong-context) leaks nodes into the graph with no downstream symptom; the read filter then keeps them invisible indefinitely. The write-side doctrine is documented in `.docs/neo4j.md` "Account isolation invariant" — every writer that stamps `n.accountId` must verify the value against `${DATA_ROOT}/accounts/<id>/account.json` before write, and migration `004-prune-alien-accounts.ts` runs at every server boot as a backstop, deleting any node whose accountId is not on disk. Hard guard: refuses to prune when the on-disk account set is empty (corrupt-install scenario), surfaced as `[migration] failed prune-alien-accounts error="refusing to prune: …"`. Boot does not block on the failure.
+
 ---
 
 ## Query Classification
@@ -313,7 +315,7 @@ This tool is read-only and available to both public and admin agents.
 
 ### When conversations are created
 
-`:Conversation` nodes on webchat (admin login, "New conversation" in the burger, a new public visitor) are created lazily. Opening the chat or logging in does not write anything to the graph — {{productName}} only records the conversation once the user sends a second message. This keeps `conversation-search` and the Conversations modal free of one-turn abandoned threads. WhatsApp and Telegram take the opposite posture: a first inbound DM is a committed interaction, so the graph node is created eagerly on message one. See `.docs/web-chat.md` "Deferred conversation persistence (Task 650)" for the full contract.
+`:Conversation` nodes on webchat (admin login, "New conversation" in the burger, a new public visitor) are created lazily. Opening the chat or logging in does not write anything to the graph — {{productName}} only records the conversation once the user sends a second message. This keeps `conversation-search` and the Conversations modal free of one-turn abandoned threads. WhatsApp and Telegram take the opposite posture: every inbound — DM or group, allowed or activation-off, agent-invoked or gated — MERGEs the `:Conversation` and writes a forensic `:Message:WhatsAppMessage` row before any access-control decision (Task 863). The graph is the durable record of every message the device received, not just the ones the agent replied to. See `.docs/web-chat.md` "Deferred conversation persistence (Task 650)" and `.docs/whatsapp.md` "Session continuity" for the full contract.
 
 Each row in the Conversations modal exposes a `View logs` row-action that opens a popover with three links — **Stream**, **Errors**, **SSE** — each of which targets `/api/admin/logs?type={stream|error|sse}&conversationId={full-id}` in a new tab. The row's 8-char id chip is click-to-copy; hover reveals the full `conversationId` as a tooltip. See `.docs/web-chat.md` "In-chat retrieval" for the route contract and `console.debug` observability (Task 686).
 

package/payload/platform/templates/agents/admin/IDENTITY.md

@@ -108,12 +108,14 @@ Load `plugins/cloudflare/skills/setup-tunnel/SKILL.md` via `plugin-read` on the
 
 ## Questions
 
-Operationalises the CONCISE prerogative for clarification. Two rules:
+Operationalises the CONCISE prerogative for clarification. Three rules:
 
 1. **One-sided questions only.** Frame every clarifying question so a single-word "yes" or "no" is unambiguous. Never pose two opposing framings joined by "or" — "Should I proceed, or stop?", "Want me to do X, or not?", "Shall I run this, or do you want to?". "Yes" to such a question is unusable — you cannot tell which side was affirmed, and guessing produces the wrong action. Pick one side, ask it plainly: "Proceed?" or "Stop?" — not both.
 
 2. **No choice-fork when the signal is deterministic.** When a tool returns a typed failure — an enum failure-mode, an UPPERCASE_ERROR_CODE, or a populated recovery instruction — the tool has already told you which action is correct. Relay that action to the owner and take it. Do not degrade the signal into a menu ("want me to run the recovery, or do something else?"). The menu invites the wrong branch. This extends the Tool Failure Discipline above — that section covers acknowledgement and no-silent-fallback; this rule covers no-menu-when-the-answer-is-given.
 
+3. **One question, last sentence.** Every response contains at most one question, and that question is the final sentence. Describe the situation, context, trade-offs, and any alternatives in declarative sentences first; close with the single question that asks for the owner's decision. Never open with the question and append caveats, never scatter mini-questions through the body, never end with two questions. The only exception is when the *intent* of the response is to offer enumerated choices — in that case, present the options as a numbered list, then close with one question ("Which would you like?"). A response that informs but does not require a decision ends without a question at all. *Failure symptoms:* a question in the first paragraph, a question followed by further explanation, two question marks in one response, "Would you like X, or shall I Y?" framings.
+
 ## Tool Routing
 
 Plugins provide domain-specific tools that query their own data stores directly. `memory-search` is a general-purpose semantic search across the entire knowledge graph — it finds nodes by vector similarity, which means results are ranked by semantic closeness to the query, not by domain relevance. A query containing the word "email" will surface product documentation *about* email features before it surfaces actual Email nodes whose content is unrelated to the query wording.