@rubytech/create-realagent-code 0.1.125 → 0.1.127

package/payload/premium-plugins/real-agent/plugins/buyers/mcp/src/lib/visitor-token.ts

@@ -0,0 +1,79 @@
+// Visitor-token minting — admin-side surface (Task 362).
+//
+// Mirrors the mint half of platform/ui/app/lib/visitor-token.ts. Verification
+// still lives in the UI server (the only verifier; mxy_v cookie + /v/event +
+// /listings/:slug/click consume tokens). Both processes share one secret file
+// under <MAXY_DIR>/credentials/visitor-token-secret via the wx-create pattern,
+// so whichever process reads first mints; the other reads the same bytes.
+//
+// MAXY_DIR is resolved from process.env.LOG_DIR's parent — the buyers MCP is
+// spawned with LOG_DIR=<MAXY_DIR>/logs (see buyers/PLUGIN.md env block), so
+// dirname(LOG_DIR) is the brand-scoped config dir whether the brand is maxy,
+// realagent, or any future brand.
+
+import { createHmac, randomBytes } from "node:crypto";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+
+const TOKEN_PREFIX = "v1.";
+const SECRET_BYTES = 32;
+const DEFAULT_TTL_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
+
+interface TokenPayload {
+  p: string;
+  e: number;
+}
+
+let cachedSecret: Buffer | null = null;
+
+function secretFilePath(): string {
+  const logDir = process.env.LOG_DIR;
+  if (!logDir) {
+    throw new Error("[buyers] LOG_DIR unset — cannot resolve visitor-token secret path");
+  }
+  return resolve(dirname(logDir), "credentials", "visitor-token-secret");
+}
+
+function getSecret(): Buffer {
+  if (cachedSecret) return cachedSecret;
+  const path = secretFilePath();
+  try {
+    const hex = readFileSync(path, "utf-8").trim();
+    if (hex.length === SECRET_BYTES * 2) {
+      cachedSecret = Buffer.from(hex, "hex");
+      return cachedSecret;
+    }
+  } catch {
+    /* fall through to mint */
+  }
+  const fresh = randomBytes(SECRET_BYTES).toString("hex");
+  try {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    writeFileSync(path, fresh, { mode: 0o600, flag: "wx" });
+    console.error(`[buyers] visitor-token secret minted path=${path}`);
+  } catch {
+    // Race with the UI server (or a peer reader) between read and write;
+    // the second read below picks up their value.
+  }
+  const hex = readFileSync(path, "utf-8").trim();
+  cachedSecret = Buffer.from(hex, "hex");
+  return cachedSecret;
+}
+
+function base64urlEncode(buf: Buffer): string {
+  return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+export interface MintOpts {
+  personId: string;
+  expiryMs?: number;
+}
+
+export function mintVisitorToken(opts: MintOpts): { token: string; expiryMs: number } {
+  const expiryMs = opts.expiryMs ?? Date.now() + DEFAULT_TTL_MS;
+  const payload: TokenPayload = { p: opts.personId, e: expiryMs };
+  const payloadJson = JSON.stringify(payload);
+  const payloadB64 = base64urlEncode(Buffer.from(payloadJson, "utf-8"));
+  const sig = base64urlEncode(createHmac("sha256", getSecret()).update(payloadJson).digest());
+  return { token: `${TOKEN_PREFIX}${payloadB64}.${sig}`, expiryMs };
+}

package/payload/premium-plugins/real-agent/plugins/buyers/mcp/src/tools/mint-visitor-token.ts

@@ -0,0 +1,35 @@
+// mint-visitor-token — admin-side mint of a signed visitor token bound to
+// a known :Person elementId. The agent appends `&v=<token>` to listing-click
+// URLs in outbound marketing surfaces (morning-round, lead-nurturing,
+// vendor-updates). Verification stays in the UI server; this tool only mints.
+
+import { mintVisitorToken } from "../lib/visitor-token.js";
+
+export interface MintParams {
+  accountId: string;
+  personId: string;
+  ttlDays?: number;
+}
+
+export interface MintResult {
+  token: string;
+  expiryMs: number;
+  expiresAt: string;
+}
+
+const DEFAULT_TTL_DAYS = 30;
+const MAX_TTL_DAYS = 365;
+
+export async function mintVisitorTokenTool(p: MintParams): Promise<MintResult> {
+  if (!p.personId || typeof p.personId !== "string") {
+    throw new Error("personId required");
+  }
+  const ttlDays = Math.max(1, Math.min(p.ttlDays ?? DEFAULT_TTL_DAYS, MAX_TTL_DAYS));
+  const expiryMs = Date.now() + ttlDays * 24 * 60 * 60 * 1000;
+  const minted = mintVisitorToken({ personId: p.personId, expiryMs });
+  return {
+    token: minted.token,
+    expiryMs: minted.expiryMs,
+    expiresAt: new Date(minted.expiryMs).toISOString(),
+  };
+}

package/payload/premium-plugins/real-agent/plugins/buyers/mcp/src/tools/visitor-backfill-from-logs.ts

@@ -12,15 +12,15 @@
 //     -> MATCH/MERGE Session, CREATE Click {label:'card', listingSlug}
 //        MERGE Session-[:HAS_EVENT]->Click
 //
-// Parity check after backfill: graph counts vs log-scan counts for the
-// same window. parityCheck is 'ok' iff both deltas are zero, otherwise
-// 'mismatch' with the delta surfaced for diagnosis.
+// Recovery path: used when a live POST /v/event write was lost (process
+// restart, dropped connection) or for ad-hoc forensics. The graph is
+// the canonical surface — these log lines are the join key, not the
+// aggregation path.
 //
 // Idempotency: re-running over the same log window does not duplicate
 // Recommendation nodes (MERGE on the exact sessionKey + slug + ts tuple).
 // Click nodes are immutable event records by design; if you re-run on a
-// window already processed you get duplicates. Operator runs once per
-// cutover.
+// window already processed you get duplicates.
 
 import { readFileSync } from "node:fs";
 import { getSession } from "../lib/neo4j.js";
@@ -42,8 +42,6 @@ export interface BackfillResult {
   clickedParsed: number;
   clickedWritten: number;
   unparseable: number;
-  parityCheck: "ok" | "mismatch";
-  parityDelta: { recommended: number; clicked: number };
 }
 
 interface RecLine { kind: "rec"; sessionKey: string; listingSlug: string; ts: string }
@@ -144,31 +142,8 @@ export async function visitorBackfillFromLogs(p: BackfillParams): Promise<Backfi
       clickedWritten += Number(row?.get("written") ?? 0);
     }
 
-    const parityRes = await session.run(
-      `MATCH (rec:Recommendation {accountId: $accountId})
-       WHERE rec.recommendedAt >= datetime($since) AND rec.recommendedAt < datetime($until)
-       WITH count(DISTINCT rec) AS recCount
-       OPTIONAL MATCH (cl:Click {accountId: $accountId, label: 'card'})
-       WHERE cl.occurredAt >= datetime($since) AND cl.occurredAt < datetime($until)
-         AND cl.backfilled = true
-       RETURN recCount, count(DISTINCT cl) AS clickCount`,
-      {
-        accountId: p.accountId,
-        since: windowStart ?? new Date(0).toISOString(),
-        until: windowEnd ? new Date(Date.parse(windowEnd) + 1).toISOString() : new Date().toISOString(),
-      },
-    );
-    const head = parityRes.records[0];
-    const recGraph = Number(head?.get("recCount") ?? 0);
-    const clickGraph = Number(head?.get("clickCount") ?? 0);
-    const parityDelta = {
-      recommended: recGraph - rec.length,
-      clicked: clickGraph - click.length,
-    };
-    const parityCheck: "ok" | "mismatch" = parityDelta.recommended === 0 && parityDelta.clicked === 0 ? "ok" : "mismatch";
-
     console.error(
-      `[visitor-backfill] done parityCheck=${parityCheck} recParsed=${rec.length} recWritten=${recommendedWritten} clickParsed=${click.length} clickWritten=${clickedWritten} unparseable=${unparseable}`,
+      `[visitor-backfill] done recParsed=${rec.length} recWritten=${recommendedWritten} clickParsed=${click.length} clickWritten=${clickedWritten} unparseable=${unparseable}`,
     );
 
     return {
@@ -180,8 +155,6 @@ export async function visitorBackfillFromLogs(p: BackfillParams): Promise<Backfi
       clickedParsed: click.length,
       clickedWritten,
       unparseable,
-      parityCheck,
-      parityDelta,
     };
   } finally {
     await session.close();

package/payload/premium-plugins/real-agent/plugins/buyers/skills/property-recommender/SKILL.md

@@ -104,16 +104,7 @@ The Hono route at `/listings/:slug/click` emits the companion line on each card-
 [property-card-click] sessionKey=<sk> listingSlug=<slug> ts=<iso>
 ```
 
-The two log lines share key names (`sessionKey`, `listingSlug`) so a grep + awk over `server.log` joins them per session. Per-session click-through rate:
-
-```bash
-# cards emitted per session
-awk -F'sessionKey=' '/\[property-recommended\]/{split($2,a," "); print a[1]}' server.log | sort | uniq -c
-# cards clicked per session
-awk -F'sessionKey=' '/\[property-card-click\]/{split($2,a," "); print a[1]}' server.log | sort | uniq -c
-```
-
-Sessions appearing in the first count but not the second never clicked through. A high uniform zero is the load-bearing alarm — the recommendation is not earning the click. Sessions where `sessionKey=invalid` appears on the click line indicate a malformed `session` query param on the redirect URL (skill template defect); the click still landed but cannot be joined to its fire log.
+CTR is read from the graph via the `visitor-recommendation-ctr` MCP tool, which joins `:Recommendation` and `:Click` nodes by `sessionKey` + `listingSlug` over the requested window. The log lines remain the join key for `visitor-backfill-from-logs` (one-shot importer for late-arriving sessions) and for ad-hoc forensics; they are not the aggregation surface. Sessions where `sessionKey=invalid` appears on the click line indicate a malformed `session` query param on the redirect URL (skill template defect); the click still landed but cannot be joined to its fire log.
 
 ## Visitor-graph integration (Task 357)
 

package/payload/premium-plugins/real-agent/plugins/leads/skills/lead-nurturing/SKILL.md

@@ -140,7 +140,7 @@ Encourage the user to capture:
 
 Call `visitor-engagement-score` with the default 30-day window to rank `:Person` contacts by engagement: visit count × recency × scroll depth × dwell time. The output is the nurture queue. Top of the queue gets outreach today; bottom decays into low-touch.
 
-When composing outbound messages that include a listing URL, append `&v=<token>` to the click URL. The token is minted server-side against the recipient's `:Person` elementId; the agent receives it as a sentinel in the system prompt for that outreach. Without the token the recipient's click is anonymous, defeating the point of the nurture loop.
+When composing outbound messages that include a listing URL, mint a token via the `mint-visitor-token` tool against the recipient's `:Person` elementId (`mint-visitor-token({ personId })`) and append the returned `token` as `&v=<token>` to the click URL. Without the token the recipient's click is anonymous, defeating the point of the nurture loop. Mint a fresh token per outbound message — TTL defaults to 30 days.
 
 The signal that says "this person stopped engaging": their score drops two consecutive weeks. That's a prompt for a pattern-break message (different listing, different framing), not a follow-up of the same thread.
 

package/payload/premium-plugins/real-agent/plugins/leads/skills/morning-round/SKILL.md

@@ -79,5 +79,5 @@ Before the morning round, call `visitor-recent-by-person` for every `:Person` in
 
 Also call `visitor-recent-by-page` for any listing that picks up activity from previously-unidentified visitors — these are anonymous prospects worth surfacing to the operator even when no `:Person` is attached.
 
-Outbound URLs in the briefing (links the operator might click to send to the contact) are minted via `mint-visitor-token` against the `:Person` and appended as `&v=<token>` to the existing `/listings/<slug>/click?session=<sk>` URL. The token binds the recipient's browser to the `:Person` on click.
+Outbound URLs in the briefing (links the operator might click to send to the contact) are minted via the `mint-visitor-token` tool — call it with the recipient's `:Person` elementId (`mint-visitor-token({ personId })`) and append the returned `token` as `&v=<token>` to the existing `/listings/<slug>/click?session=<sk>` URL. The token binds the recipient's browser to the `:Person` on click; never inline the secret yourself, always call the tool. Mint a fresh token per outbound URL — TTL defaults to 30 days and tokens are cheap to re-issue.
 

package/payload/premium-plugins/real-agent/plugins/vendors/skills/vendor-updates/SKILL.md

@@ -162,5 +162,5 @@ The weekly vendor email reports on viewing activity against the vendor's listing
 
 The vendor sees real engagement, not just enquiry count. Tone stays factual — "twelve known visitors and twenty-three anonymous browsers" is honest; "interest is strong" is editorial. Let the numbers speak.
 
-Outbound URLs in vendor emails are NOT tokenised — the vendor is not the visitor, and binding the vendor's browser to their own listing's `:Person` is meaningless.
+When the update embeds a link to the vendor's listing, mint a token via `mint-visitor-token({ personId })` against the vendor's `:Person` elementId and append the returned `token` as `&v=<token>` to the `/listings/<slug>/click?session=<sk>` URL. The vendor is a `:Person` like any other contact — binding their click attributes their own engagement with the marketing page (did they open the report, did they actually look at their listing) to the same visitor graph the buyer side feeds. Mint a fresh token per outbound update; TTL defaults to 30 days.