@rubytech/create-sitedesk-code 0.1.522 → 0.1.524

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

@@ -0,0 +1,384 @@
+import { describe, it, expect, afterEach } from "vitest";
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  normalizeE164,
+  phonesMatch,
+  readChannelAdmins,
+  registeredAccountForDestination,
+  boundSubAccountFor,
+  validateAgentDestination,
+  listDispatchDestinations,
+} from "../index.js";
+import { normalizeE164 as canonicalNormalizeE164 } from "../../../../ui/app/lib/whatsapp/normalize.js";
+
+const HOUSE = "11111111-1111-4111-8111-111111111111";
+const SUB_A = "22222222-2222-4222-8222-222222222222";
+const SUB_B = "33333333-3333-4333-8333-333333333333";
+
+const dirs: string[] = [];
+
+function makeAccountsDir(seed: (accountsDir: string) => void): string {
+  const dir = mkdtempSync(join(tmpdir(), "agent-dispatch-rule-"));
+  dirs.push(dir);
+  seed(dir);
+  return dir;
+}
+
+function seedAccount(accountsDir: string, id: string, cfg: Record<string, unknown>): void {
+  const d = join(accountsDir, id);
+  mkdirSync(d, { recursive: true });
+  writeFileSync(join(d, "account.json"), JSON.stringify(cfg), "utf-8");
+}
+
+afterEach(() => {
+  while (dirs.length > 0) rmSync(dirs.pop()!, { recursive: true, force: true });
+});
+
+// The replica exists because this package must not depend on platform/ui. That
+// makes drift the standing risk, so the two implementations are run over one
+// corpus and asserted equal. An edit to either that changes behaviour turns
+// this red rather than splitting the WhatsApp identity rule in half.
+
+const E164_CORPUS = [
+  " whatsapp:+44 (7700) 900-123 ",
+  "00447700900123",
+  "+447700900123",
+  "447700900123",
+  "whatsapp:447700900123",
+  "WhatsApp:+44-7700-900-123",
+  "not-a-number",
+  "",
+  "   ",
+  "+",
+  "00",
+  "007",
+  "+0044 7700 900123",
+  "(0)7700900123",
+  "07700900123",
+  "44 7700 900 123",
+  "+1 (555) 010-9999",
+  "555.010.9999",
+  "12345678901234567890",
+  "+44770090012a",
+  "٤٤٧٧٠٠",
+];
+
+describe("E.164 replica parity with platform/ui normalize.ts", () => {
+  it("agrees with the canonical implementation on every corpus entry", () => {
+    for (const value of E164_CORPUS) {
+      expect([value, normalizeE164(value)]).toEqual([value, canonicalNormalizeE164(value)]);
+    }
+  });
+});
+
+describe("normalizeE164 / phonesMatch", () => {
+  it("strips punctuation, a whatsapp prefix, and a leading + or 00", () => {
+    expect(normalizeE164(" whatsapp:+44 (7700) 900-123 ")).toBe("447700900123");
+    expect(normalizeE164("00447700900123")).toBe("447700900123");
+    expect(normalizeE164("not-a-number")).toBe("");
+  });
+
+  it("matches on the normalized form and never matches empty", () => {
+    expect(phonesMatch("+447700900123", "whatsapp:447700900123")).toBe(true);
+    expect(phonesMatch("", "")).toBe(false);
+  });
+});
+
+describe("readChannelAdmins", () => {
+  it("reads adminPhones and a bare-string account manager", () => {
+    const accountsDir = makeAccountsDir((d) => {
+      seedAccount(d, HOUSE, {
+        role: "house",
+        whatsapp: { adminPhones: ["+447700900111"], accountManagers: { "+447700900222": SUB_A } },
+      });
+    });
+    const wa = readChannelAdmins(join(accountsDir, HOUSE), "whatsapp");
+    expect(wa.adminPhones).toEqual(["+447700900111"]);
+    expect(wa.accountManagers).toEqual({ "+447700900222": SUB_A });
+  });
+
+  it("reads an OBJECT-shaped manager binding whose mode is active or absent", () => {
+    const accountsDir = makeAccountsDir((d) => {
+      seedAccount(d, HOUSE, {
+        role: "house",
+        whatsapp: {
+          adminPhones: [],
+          accountManagers: {
+            "+447700900222": { managesAccount: SUB_A, mode: "active" },
+            "+447700900444": { managesAccount: SUB_B },
+          },
+        },
+      });
+    });
+    const wa = readChannelAdmins(join(accountsDir, HOUSE), "whatsapp");
+    expect(wa.accountManagers).toEqual({
+      "+447700900222": SUB_A,
+      "+447700900444": SUB_B,
+    });
+  });
+
+  it("excludes a PASSIVE binding, which no fire path can deliver to", () => {
+    // effective-account.ts returns null for mode:'passive' and
+    // schedule-inject answers 403 account-manager-unresolved without spawning,
+    // so a routine bound to one would save and then fail on every fire.
+    const accountsDir = makeAccountsDir((d) => {
+      seedAccount(d, HOUSE, {
+        role: "house",
+        whatsapp: {
+          adminPhones: [],
+          accountManagers: {
+            "+447700900222": SUB_A,
+            "+447700900333": { managesAccount: SUB_B, mode: "passive" },
+          },
+        },
+      });
+    });
+    expect(readChannelAdmins(join(accountsDir, HOUSE), "whatsapp").accountManagers).toEqual({
+      "+447700900222": SUB_A,
+    });
+  });
+
+  it("treats an unrecognised mode as passive, failing closed", () => {
+    const accountsDir = makeAccountsDir((d) => {
+      seedAccount(d, HOUSE, {
+        role: "house",
+        whatsapp: { adminPhones: [], accountManagers: { "+447700900555": { managesAccount: SUB_A, mode: "activ" } } },
+      });
+    });
+    expect(readChannelAdmins(join(accountsDir, HOUSE), "whatsapp").accountManagers).toEqual({});
+  });
+
+  it("drops a manager entry with no string managesAccount", () => {
+    const accountsDir = makeAccountsDir((d) => {
+      seedAccount(d, HOUSE, {
+        role: "house",
+        whatsapp: { adminPhones: [], accountManagers: { "+447700900222": { mode: "active" } } },
+      });
+    });
+    expect(readChannelAdmins(join(accountsDir, HOUSE), "whatsapp").accountManagers).toEqual({});
+  });
+
+  it("yields empty lists for missing or malformed config", () => {
+    const accountsDir = makeAccountsDir(() => {});
+    const wa = readChannelAdmins(join(accountsDir, "nope"), "whatsapp");
+    expect(wa.adminPhones).toEqual([]);
+    expect(wa.accountManagers).toEqual({});
+    expect(readChannelAdmins(join(accountsDir, "nope"), "telegram").adminUsers).toEqual([]);
+  });
+
+  it("keeps only numeric telegram adminUsers", () => {
+    const accountsDir = makeAccountsDir((d) => {
+      seedAccount(d, SUB_A, { telegram: { adminUsers: [123, "456", 789] } });
+    });
+    expect(readChannelAdmins(join(accountsDir, SUB_A), "telegram").adminUsers).toEqual([123, 789]);
+  });
+});
+
+describe("registeredAccountForDestination", () => {
+  it("gives a manager binding precedence over an adminPhones match", () => {
+    const accountsDir = makeAccountsDir((d) => {
+      seedAccount(d, HOUSE, {
+        role: "house",
+        whatsapp: {
+          adminPhones: ["+447700900222"],
+          accountManagers: { "+447700900222": SUB_A },
+        },
+      });
+    });
+    expect(registeredAccountForDestination(join(accountsDir, HOUSE), HOUSE, "447700900222")).toBe(SUB_A);
+  });
+
+  it("returns the house for an adminPhones-only entry and null for an unknown number", () => {
+    const accountsDir = makeAccountsDir((d) => {
+      seedAccount(d, HOUSE, {
+        role: "house",
+        whatsapp: { adminPhones: ["+447700900111"], accountManagers: {} },
+      });
+    });
+    const houseDir = join(accountsDir, HOUSE);
+    expect(registeredAccountForDestination(houseDir, HOUSE, "+447700900111")).toBe(HOUSE);
+    expect(registeredAccountForDestination(houseDir, HOUSE, "+447700900999")).toBeNull();
+  });
+
+  it("resolves an object-form ACTIVE binding and refuses a passive one", () => {
+    const accountsDir = makeAccountsDir((d) => {
+      seedAccount(d, HOUSE, {
+        role: "house",
+        whatsapp: {
+          adminPhones: [],
+          accountManagers: {
+            "+447700900444": { managesAccount: SUB_A, mode: "active" },
+            "+447700900333": { managesAccount: SUB_B, mode: "passive" },
+          },
+        },
+      });
+    });
+    const houseDir = join(accountsDir, HOUSE);
+    expect(registeredAccountForDestination(houseDir, HOUSE, "447700900444")).toBe(SUB_A);
+    expect(registeredAccountForDestination(houseDir, HOUSE, "447700900333")).toBeNull();
+  });
+});
+
+describe("boundSubAccountFor", () => {
+  it("returns the bound sub-account for a manager phone and null otherwise", () => {
+    const accountsDir = makeAccountsDir((d) => {
+      seedAccount(d, HOUSE, {
+        role: "house",
+        whatsapp: { adminPhones: [], accountManagers: { "+447700900222": SUB_A } },
+      });
+    });
+    const houseDir = join(accountsDir, HOUSE);
+    expect(boundSubAccountFor(houseDir, "447700900222")).toBe(SUB_A);
+    expect(boundSubAccountFor(houseDir, "447700900999")).toBeNull();
+  });
+});
+
+describe("validateAgentDestination", () => {
+  function houseWith(managers: Record<string, unknown>, adminPhones: string[] = ["+447700900111"]): string {
+    return makeAccountsDir((d) => {
+      seedAccount(d, HOUSE, { role: "house", whatsapp: { adminPhones, accountManagers: managers } });
+      seedAccount(d, SUB_A, { telegram: { adminUsers: [555001] } });
+      seedAccount(d, SUB_B, {});
+    });
+  }
+
+  it("accepts an adminPhones number for the house itself", () => {
+    const dir = houseWith({});
+    expect(validateAgentDestination(dir, HOUSE, HOUSE, "whatsapp", "+447700900111")).toEqual({ valid: true });
+  });
+
+  it("accepts a sub-account targeting its own bound manager phone", () => {
+    const dir = houseWith({ "+447700900222": SUB_A });
+    expect(validateAgentDestination(dir, HOUSE, SUB_A, "whatsapp", "+447700900222")).toEqual({ valid: true });
+  });
+
+  it("accepts the house targeting any registered manager phone", () => {
+    const dir = houseWith({ "+447700900222": SUB_A });
+    expect(validateAgentDestination(dir, HOUSE, HOUSE, "whatsapp", "+447700900222")).toEqual({ valid: true });
+  });
+
+  it("refuses an unknown number as not-registered", () => {
+    const dir = houseWith({});
+    expect(validateAgentDestination(dir, HOUSE, SUB_A, "whatsapp", "+447700900999")).toEqual({
+      valid: false,
+      reason: "not-registered",
+    });
+  });
+
+  it("refuses another sub-account's manager phone as cross-account, naming both", () => {
+    const dir = houseWith({ "+447700900222": SUB_A });
+    expect(validateAgentDestination(dir, HOUSE, SUB_B, "whatsapp", "+447700900222")).toEqual({
+      valid: false,
+      reason: "cross-account",
+      destinationAccount: SUB_A,
+      scheduleAccount: SUB_B,
+    });
+  });
+
+  it("accepts an object-form ACTIVE manager phone for its own account", () => {
+    const dir = houseWith({ "+447700900444": { managesAccount: SUB_A, mode: "active" } });
+    expect(validateAgentDestination(dir, HOUSE, SUB_A, "whatsapp", "+447700900444")).toEqual({ valid: true });
+  });
+
+  it("refuses a PASSIVE manager phone, matching what the fire path can deliver", () => {
+    const dir = houseWith({ "+447700900333": { managesAccount: SUB_A, mode: "passive" } });
+    expect(validateAgentDestination(dir, HOUSE, SUB_A, "whatsapp", "+447700900333")).toEqual({
+      valid: false,
+      reason: "not-registered",
+    });
+  });
+
+  it("accepts a telegram id in the CREATING account's own list and refuses anything else", () => {
+    const dir = houseWith({});
+    expect(validateAgentDestination(dir, HOUSE, SUB_A, "telegram", "555001")).toEqual({ valid: true });
+    expect(validateAgentDestination(dir, HOUSE, SUB_A, "telegram", "555002")).toEqual({
+      valid: false,
+      reason: "not-registered",
+    });
+    expect(validateAgentDestination(dir, HOUSE, SUB_A, "telegram", "55.5")).toEqual({
+      valid: false,
+      reason: "not-registered",
+    });
+  });
+});
+
+describe("listDispatchDestinations", () => {
+  function seeded(): string {
+    return makeAccountsDir((d) => {
+      seedAccount(d, HOUSE, {
+        role: "house",
+        whatsapp: {
+          adminPhones: ["+447700900111", "+447700900222"],
+          accountManagers: {
+            "+447700900222": SUB_A,
+            "+447700900333": { managesAccount: SUB_B, mode: "passive" },
+            "+447700900444": { managesAccount: SUB_B, mode: "active" },
+          },
+        },
+        telegram: { adminUsers: [900001] },
+      });
+      seedAccount(d, SUB_A, { telegram: { adminUsers: [555002, 555001] } });
+      seedAccount(d, SUB_B, {});
+    });
+  }
+
+  it("offers the house every registered destination, each entry once", () => {
+    const dir = seeded();
+    expect(listDispatchDestinations({ accountsDir: dir, houseAccountId: HOUSE, accountId: HOUSE })).toEqual([
+      { channel: "whatsapp", destination: "+447700900222", label: "Account manager" },
+      { channel: "whatsapp", destination: "+447700900444", label: "Account manager" },
+      { channel: "whatsapp", destination: "+447700900111", label: "House admin" },
+      { channel: "telegram", destination: "900001", label: "Telegram admin" },
+    ]);
+  });
+
+  it("never offers the passive-bound phone, to anyone", () => {
+    const dir = seeded();
+    for (const accountId of [HOUSE, SUB_A, SUB_B]) {
+      const offered = listDispatchDestinations({ accountsDir: dir, houseAccountId: HOUSE, accountId })
+        .map((d) => d.destination);
+      expect(offered).not.toContain("+447700900333");
+    }
+  });
+
+  it("offers a sub-account only its own manager phone and its own telegram ids", () => {
+    const dir = seeded();
+    expect(listDispatchDestinations({ accountsDir: dir, houseAccountId: HOUSE, accountId: SUB_A })).toEqual([
+      { channel: "whatsapp", destination: "+447700900222", label: "Account manager" },
+      { channel: "telegram", destination: "555001", label: "Telegram admin" },
+      { channel: "telegram", destination: "555002", label: "Telegram admin" },
+    ]);
+  });
+
+  it("offers every listed entry to exactly the accounts validateAgentDestination accepts", () => {
+    const dir = seeded();
+    for (const accountId of [HOUSE, SUB_A, SUB_B]) {
+      for (const d of listDispatchDestinations({ accountsDir: dir, houseAccountId: HOUSE, accountId })) {
+        expect(validateAgentDestination(dir, HOUSE, accountId, d.channel, d.destination)).toEqual({ valid: true });
+      }
+    }
+  });
+
+  it("drops every WhatsApp entry when the house cannot be resolved, keeping telegram", () => {
+    const dir = seeded();
+    expect(listDispatchDestinations({ accountsDir: dir, houseAccountId: null, accountId: SUB_A })).toEqual([
+      { channel: "telegram", destination: "555001", label: "Telegram admin" },
+      { channel: "telegram", destination: "555002", label: "Telegram admin" },
+    ]);
+  });
+
+  it("offers a sub-account its ACTIVE binding but not its passive one", () => {
+    const dir = seeded();
+    expect(listDispatchDestinations({ accountsDir: dir, houseAccountId: HOUSE, accountId: SUB_B })).toEqual([
+      { channel: "whatsapp", destination: "+447700900444", label: "Account manager" },
+    ]);
+  });
+
+  it("returns an empty list for an account with no registered destination", () => {
+    const dir = seeded();
+    const stranger = "44444444-4444-4444-8444-444444444444";
+    expect(listDispatchDestinations({ accountsDir: dir, houseAccountId: HOUSE, accountId: stranger })).toEqual([]);
+  });
+});

package/payload/platform/lib/agent-dispatch-rule/src/index.ts

@@ -0,0 +1,269 @@
+/**
+ * The dispatch-destination rule, shared by the scheduling plugin and the admin
+ * UI so create-time, fire-time and dashboard-time cannot diverge on the rule or
+ * on the reason codes. Extracted from
+ * `plugins/scheduling/mcp/src/lib/agent-dispatch.ts`: `platform/ui` must never
+ * import from `platform/plugins`, and re-implementing the rule in the UI is the
+ * two-copies drift this module exists to prevent.
+ *
+ * House resolution is the CALLER's job. Every entry point takes the house
+ * account's id as a parameter and this module never scans the accounts
+ * directory to choose one. Two consequences, both deliberate: it carries no
+ * dependency on `account-enumeration`, so a consumer that already imports that
+ * lib does not end up with two copies of its per-process cache; and nothing
+ * here can answer for an account the caller did not name, which is the failure
+ * `check-admin-route-account-scope.mjs` exists to prevent on the UI side.
+ *
+ * The E.164 matching is a replica of
+ * `platform/ui/app/lib/whatsapp/normalize.ts`. The replica exists because this
+ * package must not depend on `platform/ui`. `src/__tests__/rule.test.ts` runs
+ * a shared corpus through BOTH implementations and asserts they agree, so an
+ * edit to either one that changes behaviour turns the suite red instead of
+ * silently splitting the two halves of the WhatsApp identity rule.
+ */
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+export type AgentChannel = "whatsapp" | "telegram";
+
+/**
+ * Reason codes are the true cause, not a symptom:
+ *  - `not-registered`: the destination is in no authoritative list (the house's
+ *    `adminPhones`/`accountManagers` for WhatsApp; the creating account's
+ *    `telegram.adminUsers` for Telegram).
+ *  - `cross-account`: the destination IS registered, but to an account other
+ *    than the one that created the schedule (and the creator is not the house).
+ *    Names both accounts so the mismatch is explained, not guessed.
+ */
+export type DestinationValidity =
+  | { valid: true }
+  | { valid: false; reason: "not-registered" }
+  | { valid: false; reason: "cross-account"; destinationAccount: string; scheduleAccount: string };
+
+/** Strip whitespace/dashes/parens, a `whatsapp:` prefix, and a leading `+` or
+ *  `00`; return digits-only or `''`. */
+export function normalizeE164(value: string): string {
+  let candidate = value.trim().replace(/[\s\-().]/g, "");
+  candidate = candidate.replace(/^whatsapp:/i, "");
+  if (candidate.startsWith("+")) candidate = candidate.slice(1);
+  else if (candidate.startsWith("00")) candidate = candidate.slice(2);
+  if (!/^\d+$/.test(candidate)) return "";
+  return candidate;
+}
+
+/** Normalized equality, non-empty. */
+export function phonesMatch(a: string, b: string): boolean {
+  const na = normalizeE164(a);
+  const nb = normalizeE164(b);
+  return na.length > 0 && na === nb;
+}
+
+interface WhatsAppAdmins {
+  adminPhones: string[];
+  /** Manager phone to the sub-account it is bound to. */
+  accountManagers: Record<string, string>;
+}
+
+/** Read the channel admin config from `<accountDir>/account.json`. Missing or
+ *  malformed config yields empty lists (a fail-closed default: no destination
+ *  validates against empty config). */
+export function readChannelAdmins(accountDir: string, channel: "whatsapp"): WhatsAppAdmins;
+export function readChannelAdmins(accountDir: string, channel: "telegram"): { adminUsers: number[] };
+export function readChannelAdmins(
+  accountDir: string,
+  channel: AgentChannel,
+): WhatsAppAdmins | { adminUsers: number[] } {
+  let config: Record<string, unknown> = {};
+  try {
+    config = JSON.parse(readFileSync(resolve(accountDir, "account.json"), "utf-8"));
+  } catch {
+    config = {};
+  }
+  if (channel === "whatsapp") {
+    const wa = (config.whatsapp as Record<string, unknown> | undefined) ?? {};
+    const adminPhones = Array.isArray(wa.adminPhones)
+      ? wa.adminPhones.filter((p): p is string => typeof p === "string")
+      : [];
+    const managersRaw = (wa.accountManagers as Record<string, unknown> | undefined) ?? {};
+    const accountManagers: Record<string, string> = {};
+    for (const [k, v] of Object.entries(managersRaw)) {
+      // This map is the set of manager phones a dispatch may be SENT to, which
+      // is narrower than the set of bindings that exist.
+      //
+      // `config-persist.ts` writes two shapes and the shape encodes the mode:
+      // an active binding persists as a bare string, and the object form
+      // `{managesAccount, mode:'passive'}` is written ONLY for passive. A
+      // passive manager is not a deliverable target — `effective-account.ts`
+      // returns null for `mode === 'passive'` and `schedule-inject.ts` answers
+      // 403 `account-manager-unresolved` without spawning — so admitting one
+      // here would let a routine save against a destination that fails on
+      // every single fire, which is the exact silence this surface exists to
+      // remove.
+      //
+      // The object form is therefore read for its `managesAccount` but kept
+      // only when its mode is active or absent. Today `config-persist` never
+      // writes an active object, so that arm admits nothing; it is here so an
+      // object-form active entry would be read correctly rather than dropped
+      // for its shape. An unrecognised mode is treated as passive, matching
+      // `readAccountManagers`, which coerces a malformed mode toward the less
+      // capable value rather than failing open.
+      if (typeof v === "string") accountManagers[k] = v;
+      else if (v && typeof v === "object" && typeof (v as { managesAccount?: unknown }).managesAccount === "string") {
+        const mode = (v as { mode?: unknown }).mode;
+        if (mode === undefined || mode === "active") {
+          accountManagers[k] = (v as { managesAccount: string }).managesAccount;
+        }
+      }
+    }
+    return { adminPhones, accountManagers };
+  }
+  const tg = (config.telegram as Record<string, unknown> | undefined) ?? {};
+  const adminUsers = Array.isArray(tg.adminUsers)
+    ? tg.adminUsers.filter((u): u is number => typeof u === "number")
+    : [];
+  return { adminUsers };
+}
+
+/**
+ * The account a WhatsApp `destination` is registered to on the HOUSE's lists,
+ * or null if it is in neither list. A manager binding wins over an admin match:
+ * if the number is an `accountManagers` key its registered account is the bound
+ * sub-account (the isolation-relevant fact); otherwise if it is an `adminPhones`
+ * entry its registered account is the house.
+ */
+export function registeredAccountForDestination(
+  houseDir: string,
+  houseAccountId: string,
+  destination: string,
+): string | null {
+  const { adminPhones, accountManagers } = readChannelAdmins(houseDir, "whatsapp");
+  for (const [managerPhone, subAccountId] of Object.entries(accountManagers)) {
+    if (subAccountId && phonesMatch(managerPhone, destination)) return subAccountId;
+  }
+  if (adminPhones.some((p) => phonesMatch(p, destination))) return houseAccountId;
+  return null;
+}
+
+/**
+ * The sub-account a WhatsApp manager destination is bound to, or null. Telegram
+ * has no account-manager surface (house-only), so it always returns null. Used
+ * by the standing audit to detect a deleted sub-account.
+ */
+export function boundSubAccountFor(accountDir: string, destination: string): string | null {
+  const { accountManagers } = readChannelAdmins(accountDir, "whatsapp");
+  for (const [managerPhone, subAccountId] of Object.entries(accountManagers)) {
+    if (subAccountId && phonesMatch(managerPhone, destination)) return subAccountId;
+  }
+  return null;
+}
+
+/**
+ * Validate a dispatch destination under the two-part rule.
+ * `accountsDir` is the PARENT accounts directory
+ * (`$PLATFORM_ROOT/../data/accounts`); `houseAccountId` is the socket-owning
+ * house, resolved by the CALLER; `creatingAccountId` is the account that
+ * created (or owns) the schedule.
+ *
+ *  - whatsapp: read the house's authoritative lists and compute the
+ *    destination's registered account. `not-registered` if it is in no house
+ *    list. Otherwise valid iff the creator IS the house (owner exception: it
+ *    owns the single line and may target any registered admin/manager) OR the
+ *    registered account equals the creating account. Any other case is
+ *    `cross-account`.
+ *  - telegram: house-only. Reads the creating account's own
+ *    `telegram.adminUsers`; there is no manager surface and thus no
+ *    cross-account concept — an integer chat id present in the list is valid,
+ *    anything else is `not-registered`. `houseAccountId` is unused on this
+ *    branch, which is why a telegram caller need not resolve one.
+ */
+export function validateAgentDestination(
+  accountsDir: string,
+  houseAccountId: string,
+  creatingAccountId: string,
+  channel: AgentChannel,
+  destination: string,
+): DestinationValidity {
+  if (channel === "whatsapp") {
+    const houseDir = resolve(accountsDir, houseAccountId);
+    const registered = registeredAccountForDestination(houseDir, houseAccountId, destination);
+    if (registered === null) return { valid: false, reason: "not-registered" };
+    if (creatingAccountId === houseAccountId) return { valid: true };
+    if (registered === creatingAccountId) return { valid: true };
+    return {
+      valid: false,
+      reason: "cross-account",
+      destinationAccount: registered,
+      scheduleAccount: creatingAccountId,
+    };
+  }
+  const { adminUsers } = readChannelAdmins(resolve(accountsDir, creatingAccountId), "telegram");
+  const asNumber = Number(destination);
+  const ok = Number.isInteger(asNumber) && adminUsers.includes(asNumber);
+  return ok ? { valid: true } : { valid: false, reason: "not-registered" };
+}
+
+/** Which authoritative list an offered destination came from. Not a name: no
+ *  personal name exists in `account.json`, and inventing one from the graph
+ *  would let the picker and the validator disagree. */
+export type DispatchLabel = "House admin" | "Account manager" | "Telegram admin";
+
+export interface DispatchDestination {
+  channel: AgentChannel;
+  destination: string;
+  label: DispatchLabel;
+}
+
+/**
+ * Every destination `accountId` may legally bind, computed from the same lists
+ * `validateAgentDestination` reads and filtered by the same two-part rule, so
+ * the picker can never offer what the save would refuse. The parity is asserted
+ * directly in this lib's test suite.
+ *
+ * `houseAccountId` is nullable because the caller's resolver throws on an
+ * install with no `role:'house'` account and more than one valid account. In
+ * that state no WhatsApp destination can be validated at all, so none is
+ * offered; Telegram is unaffected because it never consults the house.
+ */
+export function listDispatchDestinations(input: {
+  accountsDir: string;
+  houseAccountId: string | null;
+  accountId: string;
+}): DispatchDestination[] {
+  const { accountsDir, houseAccountId, accountId } = input;
+  const managers: DispatchDestination[] = [];
+  const admins: DispatchDestination[] = [];
+
+  if (houseAccountId !== null) {
+    const houseDir = resolve(accountsDir, houseAccountId);
+    const { adminPhones, accountManagers } = readChannelAdmins(houseDir, "whatsapp");
+    const seen = new Set<string>();
+    // Managers first, and a phone in both lists is emitted only as a manager:
+    // that is the account `registeredAccountForDestination` resolves for it, so
+    // any other label would name an account the rule does not use.
+    for (const [phone, subAccountId] of Object.entries(accountManagers)) {
+      const key = normalizeE164(phone);
+      if (key.length === 0 || seen.has(key)) continue;
+      if (accountId !== houseAccountId && subAccountId !== accountId) continue;
+      seen.add(key);
+      managers.push({ channel: "whatsapp", destination: phone, label: "Account manager" });
+    }
+    for (const phone of adminPhones) {
+      const key = normalizeE164(phone);
+      if (key.length === 0 || seen.has(key)) continue;
+      // An adminPhones entry registers to the house, so both arms of the rule
+      // collapse to the same test: only the house may target it.
+      if (accountId !== houseAccountId) continue;
+      seen.add(key);
+      admins.push({ channel: "whatsapp", destination: phone, label: "House admin" });
+    }
+  }
+
+  const { adminUsers } = readChannelAdmins(resolve(accountsDir, accountId), "telegram");
+  const telegram: DispatchDestination[] = [...adminUsers]
+    .sort((a, b) => a - b)
+    .map((id) => ({ channel: "telegram" as const, destination: String(id), label: "Telegram admin" as const }));
+
+  const byDestination = (a: DispatchDestination, b: DispatchDestination) =>
+    a.destination.localeCompare(b.destination);
+  return [...managers.sort(byDestination), ...admins.sort(byDestination), ...telegram];
+}

package/payload/platform/lib/agent-dispatch-rule/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"],
+  "exclude": ["src/__tests__"]
+}

package/payload/platform/lib/agent-dispatch-rule/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "node",
+    globals: false,
+    include: ["src/__tests__/**/*.test.ts"],
+  },
+});

package/payload/platform/lib/graph-style/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CA6NtD,CAAA;AAED,eAAO,MAAM,qBAAqB,YAAY,CAAA;AAE9C;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,sBAAsB,EAAE,WAAW,CAAC,MAAM,CAE/B,CAAA;AAExB,eAAO,MAAM,gBAAgB,EAAE,SAAS,MAAM,EAE7C,CAAA;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CAOzE;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEpD;AAiBD,eAAO,MAAM,qBAAqB,sFAQxB,CAAA;AAEV,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAA;AAEnE,eAAO,MAAM,oBAAoB,EAAE,cAAsB,CAAA;AAUzD,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,CAE3D;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB,EAAE,WAAW,CAAC,MAAM,CAEjC,CAAA;AA2IxB;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAIzD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAY7D;AAED,MAAM,WAAW,kBAAkB;IACjC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,MAAM,EAAE,MAAM,CAAA;IACd,eAAe,EAAE,MAAM,CAAA;CACxB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,kBAAkB,CAU/E;AASD;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAA;IACV,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACpC;AAKD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAI7D;AAED,iEAAiE;AACjE,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAIjE;AA2BD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAqH1D;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAoF3D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAmOtD,CAAA;AAED,eAAO,MAAM,qBAAqB,YAAY,CAAA;AAE9C;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,sBAAsB,EAAE,WAAW,CAAC,MAAM,CAE/B,CAAA;AAExB,eAAO,MAAM,gBAAgB,EAAE,SAAS,MAAM,EAE7C,CAAA;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CAOzE;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEpD;AAiBD,eAAO,MAAM,qBAAqB,sFAQxB,CAAA;AAEV,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAA;AAEnE,eAAO,MAAM,oBAAoB,EAAE,cAAsB,CAAA;AAUzD,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,CAE3D;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB,EAAE,WAAW,CAAC,MAAM,CAEjC,CAAA;AA4IxB;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAIzD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAY7D;AAED,MAAM,WAAW,kBAAkB;IACjC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,MAAM,EAAE,MAAM,CAAA;IACd,eAAe,EAAE,MAAM,CAAA;CACxB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,kBAAkB,CAU/E;AASD;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAA;IACV,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACpC;AAKD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAI7D;AAED,iEAAiE;AACjE,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAIjE;AA2BD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CA+H1D;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CA2F3D"}