@rubytech/create-realagent-code 0.1.574 → 0.1.575

package/payload/platform/lib/dispatch-read/src/__tests__/read.test.ts

@@ -41,14 +41,18 @@ describe("projectVisit", () => {
         startDate: "2026-08-07T09:00:00.000Z",
         endDate: null,
         purpose: null,
-        workerId: "W1",
         siteName: null,
         customerId: null,
         customerName: null,
         jobType: null,
-        arrivedPressedAt: "2026-08-07T09:05:00.000Z",
-        arrivedObservedAt: "2026-08-07T08:58:00.000Z",
-        arrivedObservedDistanceM: 42,
+        attendances: [
+          {
+            workerId: "W1",
+            arrivedPressedAt: "2026-08-07T09:05:00.000Z",
+            arrivedObservedAt: "2026-08-07T08:58:00.000Z",
+            arrivedObservedDistanceM: 42,
+          },
+        ],
       }),
     );
     expect(v.arrivedPressedAt).toBe("2026-08-07T09:05:00.000Z");
@@ -65,19 +69,114 @@ describe("projectVisit", () => {
         startDate: null,
         endDate: null,
         purpose: null,
-        workerId: null,
         siteName: null,
         customerId: null,
         customerName: null,
         jobType: null,
-        arrivedPressedAt: null,
-        arrivedObservedAt: null,
-        arrivedObservedDistanceM: { low: 137, high: 0 },
+        attendances: [
+          {
+            workerId: "W1",
+            arrivedPressedAt: null,
+            arrivedObservedAt: null,
+            arrivedObservedDistanceM: { low: 137, high: 0 },
+          },
+        ],
       }),
     );
     expect(v.arrivedObservedDistanceM).toBe(137);
   });
 
+  // Task 2512. The shipped projection returned a scalar `workerId` off a second
+  // ATTENDED_BY edge, so a two-worker visit arrived as two records sharing one
+  // set of times and drew as two separate visits.
+  it("projects a single-attendance visit exactly as Task 2499 returned it", () => {
+    const v = projectVisit(
+      row({
+        visitId: "V5",
+        jobId: "J5",
+        status: "On site",
+        startDate: "2026-08-07T09:00:00.000Z",
+        endDate: null,
+        purpose: null,
+        siteName: null,
+        customerId: null,
+        customerName: null,
+        jobType: null,
+        attendances: [
+          {
+            workerId: "W1",
+            arrivedPressedAt: "2026-08-07T09:05:00.000Z",
+            arrivedObservedAt: null,
+            arrivedObservedDistanceM: null,
+          },
+        ],
+      }),
+    );
+    expect(v.workerId).toBe("W1");
+    expect(v.arrivedPressedAt).toBe("2026-08-07T09:05:00.000Z");
+    expect(v.attendances).toHaveLength(1);
+  });
+
+  it("carries two workers on one visit, each with their own arrival", () => {
+    const v = projectVisit(
+      row({
+        visitId: "V6",
+        jobId: "J6",
+        status: "On site",
+        startDate: "2026-08-07T09:00:00.000Z",
+        endDate: null,
+        purpose: null,
+        siteName: null,
+        customerId: null,
+        customerName: null,
+        jobType: null,
+        attendances: [
+          {
+            workerId: "W2",
+            arrivedPressedAt: "2026-08-07T09:20:00.000Z",
+            arrivedObservedAt: null,
+            arrivedObservedDistanceM: null,
+          },
+          {
+            workerId: "W1",
+            arrivedPressedAt: "2026-08-07T09:05:00.000Z",
+            arrivedObservedAt: null,
+            arrivedObservedDistanceM: null,
+          },
+        ],
+      }),
+    );
+    expect(v.attendances).toHaveLength(2);
+    // Sorted, so two reads of one visit cannot order the names differently.
+    expect(v.attendances.map((a) => a.workerId)).toEqual(["W1", "W2"]);
+    expect(v.attendances[0].arrivedPressedAt).toBe("2026-08-07T09:05:00.000Z");
+    expect(v.attendances[1].arrivedPressedAt).toBe("2026-08-07T09:20:00.000Z");
+    // The sole-attendee scalars go null rather than picking one of the two: a
+    // silent cross-assignment shows one worker another's arrival.
+    expect(v.workerId).toBeNull();
+    expect(v.arrivedPressedAt).toBeNull();
+  });
+
+  it("returns no attendances for an unallocated visit, never a list holding an empty entry", () => {
+    const v = projectVisit(
+      row({
+        visitId: "V7",
+        jobId: null,
+        status: "New",
+        startDate: null,
+        endDate: null,
+        purpose: null,
+        siteName: null,
+        customerId: null,
+        customerName: null,
+        jobType: null,
+        attendances: [],
+      }),
+    );
+    expect(v.attendances).toEqual([]);
+    expect(v.workerId).toBeNull();
+  });
+
   it("renders an empty string as null so a blank never reads as a real value", () => {
     const v = projectVisit(
       row({

package/payload/platform/lib/dispatch-read/src/__tests__/worker-day.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it, vi } from "vitest";
 import { __setDriverForTests } from "../session.js";
-import { readWorkerDay, readSiteHistory } from "../read.js";
+import { readWorkerDay, readSiteHistory, readFieldVisit } from "../read.js";
 import { workerForTelegramUser } from "../config.js";
 import type { DispatchConfig } from "../types.js";
 
@@ -31,8 +31,23 @@ const ROW = {
   customerName: "Acme",
   contactName: "Jo Bell",
   contactTelephone: "01234 567890",
+  addressed: false,
+  streetAddress: null,
+  addressLocality: null,
+  postalCode: null,
 };
 
+const ADDRESSED = {
+  ...ROW,
+  addressed: true,
+  streetAddress: "12 High Street",
+  addressLocality: "Dunmow",
+  postalCode: "CM6 1EJ",
+};
+
+const FROM = "2026-08-07T00:00:00.000Z";
+const TO = "2026-08-08T00:00:00.000Z";
+
 describe("readWorkerDay", () => {
   it("returns the field card shape", async () => {
     __setDriverForTests(driverReturning([ROW]));
@@ -48,17 +63,39 @@ describe("readWorkerDay", () => {
     __setDriverForTests(null);
   });
 
-  it("carries no address and no postcode key at all", async () => {
+  it("carries no address key when the site has no AT_ADDRESS edge", async () => {
     __setDriverForTests(driverReturning([ROW]));
-    const [visit] = await readWorkerDay(
-      "a1", "w1", "2026-08-07T00:00:00.000Z", "2026-08-08T00:00:00.000Z",
-    );
-    // Conflict 7 of the design: the ontology has no address for a :Site. The
-    // keys must be ABSENT, not null, so the deferral to task 2514 cannot be
-    // half-implemented as an always-empty column that reads to a worker as
-    // "this site has no address".
+    const [visit] = await readWorkerDay("a1", "w1", FROM, TO);
+    // ABSENT, not null. An always-present key holding nulls reads to a worker
+    // as "this site has no address" rather than "we hold none for it", which is
+    // the reason task 2502 shipped no column at all.
     expect(Object.keys(visit)).not.toContain("address");
-    expect(Object.keys(visit)).not.toContain("postcode");
+    __setDriverForTests(null);
+  });
+
+  it("carries the address as one object when the edge exists", async () => {
+    __setDriverForTests(driverReturning([ADDRESSED]));
+    const [visit] = await readWorkerDay("a1", "w1", FROM, TO);
+    expect(visit.address).toEqual({
+      streetAddress: "12 High Street",
+      addressLocality: "Dunmow",
+      postalCode: "CM6 1EJ",
+    });
+    __setDriverForTests(null);
+  });
+
+  it("carries the address whole when the edge exists but a part is missing", async () => {
+    // The edge is what decides the key. A PostalAddress written without its
+    // locality is still an address the worker can drive to, and dropping the
+    // key would report the site as unaddressed while the census counted it
+    // addressed — the two would disagree.
+    __setDriverForTests(driverReturning([{ ...ADDRESSED, addressLocality: null }]));
+    const [visit] = await readWorkerDay("a1", "w1", FROM, TO);
+    expect(visit.address).toEqual({
+      streetAddress: "12 High Street",
+      addressLocality: null,
+      postalCode: "CM6 1EJ",
+    });
     __setDriverForTests(null);
   });
 
@@ -76,6 +113,128 @@ describe("readWorkerDay", () => {
     expect(visit.contactName).toBeNull();
     __setDriverForTests(null);
   });
+
+  it("shows the caller their OWN arrival on a visit they share (Task 2512)", async () => {
+    // The sole-attendee rule returns null at two attendances, and a sheet
+    // showing no arrival to the worker who pressed it reads as a lost press.
+    // The worker day therefore reads arrival off the caller's own attendance,
+    // which the query returns in the `own*` columns.
+    __setDriverForTests(driverReturning([
+      {
+        ...ROW,
+        attendances: [
+          { workerId: "w1", arrivedPressedAt: "2026-08-07T08:12:00.000Z",
+            arrivedObservedAt: null, arrivedObservedDistanceM: null },
+          { workerId: "w2", arrivedPressedAt: "2026-08-07T08:40:00.000Z",
+            arrivedObservedAt: null, arrivedObservedDistanceM: null },
+        ],
+        ownArrivedPressedAt: "2026-08-07T08:12:00.000Z",
+        ownArrivedObservedAt: null,
+        ownArrivedObservedDistanceM: null,
+      },
+    ]));
+    const [visit] = await readWorkerDay("a1", "w1", FROM, TO);
+    expect(visit.workerId).toBe("w1");
+    expect(visit.arrivedPressedAt).toBe("2026-08-07T08:12:00.000Z");
+    // Both workers reach the sheet, so it can name who they are working with.
+    expect(visit.attendances.map((a) => a.workerId)).toEqual(["w1", "w2"]);
+    __setDriverForTests(null);
+  });
+
+  it("is ONE card for a shared visit, never one per worker", async () => {
+    // The failure the task exists to end: a row per attendance rendered as two
+    // separate visits sharing one set of times.
+    __setDriverForTests(driverReturning([
+      {
+        ...ROW,
+        attendances: [
+          { workerId: "w1", arrivedPressedAt: null, arrivedObservedAt: null,
+            arrivedObservedDistanceM: null },
+          { workerId: "w2", arrivedPressedAt: null, arrivedObservedAt: null,
+            arrivedObservedDistanceM: null },
+        ],
+      },
+    ]));
+    const visits = await readWorkerDay("a1", "w1", FROM, TO);
+    expect(visits).toHaveLength(1);
+    __setDriverForTests(null);
+  });
+});
+
+describe("readFieldVisit", () => {
+  // The job sheet's read. It exists so the sheet and the today list share one
+  // projection: the sheet served a plain visit row, so its site name, customer
+  // and contact rendered as absent on every card since the sheet shipped.
+  it("returns the same field shape as the day read, for one visit", async () => {
+    const session = {
+      run: vi.fn(async () => ({
+        records: [{ get: (k: string) => (ADDRESSED as Record<string, unknown>)[k] }],
+      })),
+    } as never;
+    const visit = await readFieldVisit(session, "a1", "v1");
+    expect(visit?.siteName).toBe("Ladywell Prospect");
+    expect(visit?.contactTelephone).toBe("01234 567890");
+    expect(visit?.address?.postalCode).toBe("CM6 1EJ");
+  });
+
+  it("omits the address key for a site with no edge", async () => {
+    const session = {
+      run: vi.fn(async () => ({
+        records: [{ get: (k: string) => (ROW as Record<string, unknown>)[k] }],
+      })),
+    } as never;
+    const visit = await readFieldVisit(session, "a1", "v1");
+    expect(Object.keys(visit ?? {})).not.toContain("address");
+  });
+
+  it("returns null for a visit that is not on this account", async () => {
+    const session = { run: vi.fn(async () => ({ records: [] })) } as never;
+    expect(await readFieldVisit(session, "a1", "nope")).toBeNull();
+  });
+
+  it("names no single worker on a shared visit, and lists both (Task 2512)", async () => {
+    // This read applies no worker filter — the route does its own ownership
+    // check — so there is no "my" attendance to prefer. Answering "which single
+    // worker?" with either one would be a silent cross-assignment, so it
+    // answers with nothing and the list carries both.
+    const row = {
+      ...ROW,
+      attendances: [
+        { workerId: "w2", arrivedPressedAt: "2026-08-07T08:40:00.000Z",
+          arrivedObservedAt: null, arrivedObservedDistanceM: null },
+        { workerId: "w1", arrivedPressedAt: "2026-08-07T08:12:00.000Z",
+          arrivedObservedAt: null, arrivedObservedDistanceM: null },
+      ],
+    };
+    const session = {
+      run: vi.fn(async () => ({
+        records: [{ get: (k: string) => (row as Record<string, unknown>)[k] }],
+      })),
+    } as never;
+    const visit = await readFieldVisit(session, "a1", "v1");
+    expect(visit?.workerId).toBeNull();
+    expect(visit?.arrivedPressedAt).toBeNull();
+    // Sorted, so two reads of one visit cannot order the workers differently.
+    expect(visit?.attendances.map((a) => a.workerId)).toEqual(["w1", "w2"]);
+  });
+
+  it("still projects a one-worker visit exactly as before", async () => {
+    const row = {
+      ...ROW,
+      attendances: [
+        { workerId: "w1", arrivedPressedAt: "2026-08-07T08:12:00.000Z",
+          arrivedObservedAt: null, arrivedObservedDistanceM: null },
+      ],
+    };
+    const session = {
+      run: vi.fn(async () => ({
+        records: [{ get: (k: string) => (row as Record<string, unknown>)[k] }],
+      })),
+    } as never;
+    const visit = await readFieldVisit(session, "a1", "v1");
+    expect(visit?.workerId).toBe("w1");
+    expect(visit?.arrivedPressedAt).toBe("2026-08-07T08:12:00.000Z");
+  });
 });
 
 describe("readSiteHistory", () => {
@@ -139,3 +298,49 @@ describe("workerForTelegramUser", () => {
     expect(workerForTelegramUser(cfg, "")).toBeNull();
   });
 });
+
+describe("a site with more than one address", () => {
+  // An OPTIONAL MATCH that finds two nodes returns two rows, so a site holding
+  // two AT_ADDRESS edges would put the same visit on a worker's list twice,
+  // each copy showing a different address. That state is reachable:
+  // `memory-write`'s edge check is warn-only, so nothing blocks a second edge.
+  //
+  // The collapse is in Cypher, so the query is what carries it. Asserting a row
+  // count against the fake driver would prove nothing — the fake returns the
+  // rows it was handed and models no aggregation.
+  function captureQuery() {
+    const seen: string[] = [];
+    __setDriverForTests({
+      session: () => ({
+        run: vi.fn(async (q: string) => {
+          seen.push(q);
+          return { records: [] };
+        }),
+        close: vi.fn(async () => {}),
+      }),
+    } as never);
+    return seen;
+  }
+
+  it("collapses the day read to one address and one contact per visit", async () => {
+    const seen = captureQuery();
+    await readWorkerDay("a1", "w1", FROM, TO);
+    __setDriverForTests(null);
+    expect(seen, "no query was captured").toHaveLength(1);
+    expect(seen[0]).toContain("head(collect(DISTINCT pa0)) AS pa");
+    expect(seen[0]).toContain("head(collect(DISTINCT ct0)) AS ct");
+  });
+
+  it("collapses the sheet read the same way", async () => {
+    const seen: string[] = [];
+    const session = {
+      run: vi.fn(async (q: string) => {
+        seen.push(q);
+        return { records: [] };
+      }),
+    } as never;
+    await readFieldVisit(session, "a1", "v1");
+    expect(seen, "no query was captured").toHaveLength(1);
+    expect(seen[0]).toContain("head(collect(DISTINCT pa0)) AS pa");
+  });
+});

package/payload/platform/lib/dispatch-read/src/geo.ts

@@ -0,0 +1,56 @@
+/**
+ * Distance to a site, and whether that counts as being there.
+ *
+ * The verdict names why it could not fire rather than returning a bare false.
+ * "This site has no coordinates", "this account configured no radius" and "the
+ * worker is four kilometres away" are three different problems with three
+ * different fixes, and a single boolean sends an operator to the wrong one.
+ */
+import type { DispatchConfig, SiteLocation } from "./types.js";
+
+const EARTH_RADIUS_M = 6_371_000;
+
+const toRad = (deg: number): number => (deg * Math.PI) / 180;
+
+/** Great-circle distance in metres, rounded. */
+export function distanceM(
+  a: { latitude: number; longitude: number },
+  b: { latitude: number; longitude: number },
+): number {
+  const dLat = toRad(b.latitude - a.latitude);
+  const dLon = toRad(b.longitude - a.longitude);
+  const lat1 = toRad(a.latitude);
+  const lat2 = toRad(b.latitude);
+  const h =
+    Math.sin(dLat / 2) ** 2 + Math.sin(dLon / 2) ** 2 * Math.cos(lat1) * Math.cos(lat2);
+  return Math.round(2 * EARTH_RADIUS_M * Math.asin(Math.sqrt(h)));
+}
+
+export interface GeofenceVerdict {
+  siteHasCoords: boolean;
+  /** The site's own radius, else the account default, else null. */
+  radiusM: number | null;
+  /** Null when there is nothing to measure against. */
+  distanceM: number | null;
+  inside: boolean;
+}
+
+export function geofenceVerdict(p: {
+  site: SiteLocation | null;
+  cfg: DispatchConfig;
+  at: { latitude: number; longitude: number };
+}): GeofenceVerdict {
+  const siteHasCoords =
+    p.site !== null && p.site.latitude !== null && p.site.longitude !== null;
+  const radiusM = p.site?.geofenceRadiusM ?? p.cfg.vehicles?.defaultGeofenceRadiusM ?? null;
+  if (!siteHasCoords) {
+    return { siteHasCoords: false, radiusM, distanceM: null, inside: false };
+  }
+  const d = distanceM(
+    { latitude: p.site!.latitude as number, longitude: p.site!.longitude as number },
+    p.at,
+  );
+  // A distance with no radius to compare it against cannot say whether anybody
+  // arrived. Reported, never assumed.
+  return { siteHasCoords: true, radiusM, distanceM: d, inside: radiusM !== null && d <= radiusM };
+}

package/payload/platform/lib/dispatch-read/src/index.ts

@@ -18,6 +18,18 @@ export {
   workerForTelegramUser,
 } from "./config.js";
 export type { RecordableField } from "./config.js";
+
+// Task 2510 — the card's buttons and the press's wire format. Config-derived
+// and pure, so the plugin that draws a card and the route that reads a press
+// share one implementation rather than two encoders that can drift.
+export {
+  CALLBACK_DATA_MAX_BYTES,
+  buildVisitKeyboard,
+  dispatchCallbackData,
+  parseDispatchCallback,
+} from "./keyboard.js";
+export type { DispatchButton, VisitKeyboard } from "./keyboard.js";
+
 export { withSession } from "./session.js";
 export { resolveAccountZone } from "./zone.js";
 export {
@@ -34,21 +46,33 @@ export {
 // Session-taking reads: the dispatch plugin's, moved here unchanged.
 export {
   buildJobListQuery,
+  projectFieldVisit,
   projectJob,
   projectVisit,
   readCommitments,
+  readDraft,
+  readDrafts,
+  readFieldVisit,
   readJob,
   readJobs,
   readNodeId,
+  readOpenVisitsForWorker,
+  readPreviousVisits,
   readSiteHistory,
+  readSiteLocation,
   readVisit,
   readVisitRecordState,
   readVisitsForJob,
   readVisitsInWindow,
 } from "./read.js";
 
+// Task 2510 — the geofence maths. Pure, so it is asserted against real
+// coordinates rather than against a mocked graph.
+export { distanceM, geofenceVerdict } from "./geo.js";
+export type { GeofenceVerdict } from "./geo.js";
+
 // Session-owning reads: the planner's, so a route holds no graph access.
 export { nonZuluStarts, readCounts, readDay, readJobList, readWorkerDay } from "./read.js";
 
-export type { Commitment, VisitRecordState } from "./read.js";
+export type { Commitment, DraftRow, PreviousVisit, VisitRecordState } from "./read.js";
 export type * from "./types.js";

package/payload/platform/lib/dispatch-read/src/keyboard.ts

@@ -0,0 +1,98 @@
+/**
+ * The buttons on a dispatch card, and the wire format a press comes back on.
+ *
+ * One implementation for two processes. The dispatch MCP plugin draws the card;
+ * the UI server's webhook route reads the press and redraws it. Two encoders
+ * would be two authorities for one wire format, and the failure would be a
+ * button that does nothing with no line anywhere saying why.
+ *
+ * No status string appears below. The buttons are the account's own configured
+ * transitions out of the visit's current status, labelled with the account's own
+ * status names.
+ */
+import type { DispatchConfig } from "./types.js";
+
+/** Bot API: "Data to be sent in a callback query to the bot when the button is
+ *  pressed, UTF-8 1-64 bytes." Telegram refuses a longer button at send time
+ *  with nothing in our logs to explain it, so the builder measures instead. */
+export const CALLBACK_DATA_MAX_BYTES = 64;
+
+/** The prefix that makes a press ours. A press without it belongs to some other
+ *  keyboard and falls through the route untouched. */
+const PREFIX = "d";
+
+const SEP = ":";
+
+export interface DispatchButton {
+  text: string;
+  callbackData?: string;
+  webAppUrl?: string;
+}
+
+export interface VisitKeyboard {
+  rows: DispatchButton[][];
+  /** Transitions whose encoded data exceeded the cap. Named, never silent: a
+   *  dropped button is a worker who cannot close a job. */
+  dropped: Array<{ status: string; bytes: number }>;
+}
+
+/**
+ * `d:<visitId>:<to>:<drawnFor>`.
+ *
+ * Status NAMES rather than indices into `cfg.statuses.visit`. Indices always fit
+ * the 64 bytes, but an operator reordering the status list would silently
+ * repoint every live button, and the stale check exists to catch a visit that
+ * moved on, not a config that did.
+ */
+export function dispatchCallbackData(p: {
+  visitId: string;
+  to: string;
+  drawnFor: string;
+}): string {
+  return [PREFIX, p.visitId, p.to, p.drawnFor].join(SEP);
+}
+
+/** Null means "not ours". A status name containing a colon would split wrongly,
+ *  so the parse requires exactly four parts rather than joining the tail. */
+export function parseDispatchCallback(
+  data: string | null,
+): { visitId: string; to: string; drawnFor: string } | null {
+  if (data === null) return null;
+  const parts = data.split(SEP);
+  if (parts.length !== 4 || parts[0] !== PREFIX) return null;
+  const [, visitId, to, drawnFor] = parts;
+  if (!visitId || !to || !drawnFor) return null;
+  return { visitId, to, drawnFor };
+}
+
+/**
+ * The card's buttons for a visit at `status`.
+ *
+ * One button per legal transition out of `status`, plus one `web_app` button
+ * opening the job sheet. `web_app` and never `url`: a `url` button sends the
+ * worker to the device browser, where Telegram has signed nothing and the sheet
+ * refuses him.
+ */
+export function buildVisitKeyboard(p: {
+  cfg: DispatchConfig;
+  visitId: string;
+  status: string;
+  sheetUrl: string;
+}): VisitKeyboard {
+  const rows: DispatchButton[][] = [];
+  const dropped: Array<{ status: string; bytes: number }> = [];
+
+  for (const [from, to] of p.cfg.statuses.visitTransitions) {
+    if (from !== p.status) continue;
+    const callbackData = dispatchCallbackData({ visitId: p.visitId, to, drawnFor: p.status });
+    const bytes = Buffer.byteLength(callbackData, "utf8");
+    if (bytes > CALLBACK_DATA_MAX_BYTES) {
+      dropped.push({ status: to, bytes });
+      continue;
+    }
+    rows.push([{ text: to, callbackData }]);
+  }
+
+  rows.push([{ text: p.cfg.vocabulary.visit, webAppUrl: p.sheetUrl }]);
+  return { rows, dropped };
+}