@pentatonic-ai/ai-agent-sdk 0.8.7 → 0.9.0

package/dist/index.cjs

@@ -906,7 +906,7 @@ function fireAndForgetEmit(clientConfig, sessionOpts, messages, result, model) {
 }
 
 // src/telemetry.js
-var VERSION = "0.8.7";
+var VERSION = "0.9.0";
 var TELEMETRY_URL = "https://sdk-telemetry.philip-134.workers.dev";
 function machineId() {
   const raw = typeof process !== "undefined" ? `${process.env?.USER || process.env?.USERNAME || "u"}:${process.platform || "x"}:${process.arch || "x"}` : "browser";

package/dist/index.js

@@ -875,7 +875,7 @@ function fireAndForgetEmit(clientConfig, sessionOpts, messages, result, model) {
 }
 
 // src/telemetry.js
-var VERSION = "0.8.7";
+var VERSION = "0.9.0";
 var TELEMETRY_URL = "https://sdk-telemetry.philip-134.workers.dev";
 function machineId() {
   const raw = typeof process !== "undefined" ? `${process.env?.USER || process.env?.USERNAME || "u"}:${process.platform || "x"}:${process.arch || "x"}` : "browser";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pentatonic-ai/ai-agent-sdk",
-  "version": "0.8.7",
+  "version": "0.9.0",
   "description": "TES SDK — LLM observability and lifecycle tracking via Pentatonic Thing Event System. Track token usage, tool calls, and conversations. Manage things through event-sourced lifecycle stages with AI enrichment and vector search.",
   "type": "module",
   "main": "./dist/index.cjs",

package/packages/memory/package-lock.json

@@ -6,14 +6,9 @@
   "packages": {
     "": {
       "name": "@pentatonic/memory",
-      "version": "0.1.0",
-      "license": "MIT",
       "dependencies": {
         "@modelcontextprotocol/sdk": "^1.0.0",
         "pg": "^8.13.0"
-      },
-      "bin": {
-        "memory-server": "src/server.js"
       }
     },
     "node_modules/@hono/node-server": {
@@ -436,9 +431,9 @@
       "license": "MIT"
     },
     "node_modules/fast-uri": {
-      "version": "3.1.0",
-      "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.0.tgz",
-      "integrity": "sha512-iPeeDKJSWf4IEOasVVrknXpaBV0IApz/gp7S2bb7Z4Lljbl2MGJRqInZiUrQwV16cpzw/D3S5j5Julj/gT52AA==",
+      "version": "3.1.2",
+      "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.2.tgz",
+      "integrity": "sha512-rVjf7ArG3LTk+FS6Yw81V1DLuZl1bRbNrev6Tmd/9RaroeeRRJhAt7jg/6YFxbvAQXUCavSoZhPPj6oOx+5KjQ==",
       "funding": [
         {
           "type": "github",

package/packages/memory/src/__tests__/engine.test.js

@@ -4,6 +4,7 @@ import {
   engineStore,
   engineSearch,
   engineAggregate,
+  enginePeopleList,
   engineForget,
   composeArena,
   composeArenas,
@@ -281,6 +282,17 @@ describe("engine HTTP client", () => {
       expect(sent["CF-Access-Client-Id"]).toBe("tes-worker.id");
     });
 
+    it("enginePeopleList forwards opts.headers", async () => {
+      mockOk({ total_count: 0, has_more: false, items: [] });
+      await enginePeopleList("https://e", {
+        clientId: "acme",
+        headers: cfAccess,
+      });
+      const sent = calls[0].init.headers;
+      expect(sent["CF-Access-Client-Id"]).toBe("tes-worker.id");
+      expect(sent["CF-Access-Client-Secret"]).toBe("shh-it-secret");
+    });
+
     it("no headers sent when opts.headers omitted (back-compat)", async () => {
       mockOk({});
       await engineStore("https://e", { clientId: "acme", content: "x" });
@@ -457,6 +469,142 @@ describe("engine HTTP client", () => {
     });
   });
 
+  describe("enginePeopleList", () => {
+    const emptyPage = { total_count: 0, has_more: false, items: [] };
+
+    it("posts to /people-list with arenas list (tenant + user-scope) when userId is set", async () => {
+      mockOk(emptyPage);
+      await enginePeopleList("https://e", {
+        clientId: "acme",
+        userId: "user-42",
+      });
+      const body = JSON.parse(calls[0].init.body);
+      expect(calls[0].url).toBe("https://e/people-list");
+      // Mirrors engineSearch's arena composition: tenant + user-scope.
+      // The engine dedups by person_email, so cross-arena spans are
+      // safe and expected for this query.
+      expect(body.arenas).toEqual(["acme", "acme:user-42"]);
+    });
+
+    it("uses tenant-only arenas when no userId", async () => {
+      mockOk(emptyPage);
+      await enginePeopleList("https://e", { clientId: "acme" });
+      const body = JSON.parse(calls[0].init.body);
+      expect(body.arenas).toEqual(["acme"]);
+    });
+
+    it("uses explicit arenas list when provided, ignoring clientId/userId", async () => {
+      // Cross-user view: caller passes the arenas it wants spanned.
+      // Backs the "people known by Philip OR Jeanne" use case.
+      mockOk(emptyPage);
+      await enginePeopleList("https://e", {
+        clientId: "ignored",
+        userId: "also-ignored",
+        arenas: ["acme:user-philip", "acme:user-jeanne"],
+      });
+      const body = JSON.parse(calls[0].init.body);
+      expect(body.arenas).toEqual(["acme:user-philip", "acme:user-jeanne"]);
+    });
+
+    it("throws when neither clientId nor arenas are provided", async () => {
+      mockOk(emptyPage);
+      await expect(enginePeopleList("https://e", {})).rejects.toThrow(
+        /clientId or arenas required/,
+      );
+    });
+
+    it("forwards emails for batched-mode lookup", async () => {
+      mockOk(emptyPage);
+      await enginePeopleList("https://e", {
+        clientId: "acme",
+        emails: ["alex@x.io", "bea@y.io"],
+      });
+      const body = JSON.parse(calls[0].init.body);
+      expect(body.emails).toEqual(["alex@x.io", "bea@y.io"]);
+    });
+
+    it("omits emails when empty list (engine treats missing field as 'no filter')", async () => {
+      mockOk(emptyPage);
+      await enginePeopleList("https://e", { clientId: "acme", emails: [] });
+      const body = JSON.parse(calls[0].init.body);
+      expect(body).not.toHaveProperty("emails");
+    });
+
+    it("forwards search substring when provided", async () => {
+      mockOk(emptyPage);
+      await enginePeopleList("https://e", {
+        clientId: "acme",
+        search: "pentatonic",
+      });
+      const body = JSON.parse(calls[0].init.body);
+      expect(body.search).toBe("pentatonic");
+    });
+
+    it("uses defaults for limit/offset/orderBy", async () => {
+      mockOk(emptyPage);
+      await enginePeopleList("https://e", { clientId: "acme" });
+      const body = JSON.parse(calls[0].init.body);
+      expect(body.limit).toBe(200);
+      expect(body.offset).toBe(0);
+      expect(body.order_by).toBe("last_seen_desc");
+    });
+
+    it("forwards limit/offset/orderBy when provided", async () => {
+      mockOk(emptyPage);
+      await enginePeopleList("https://e", {
+        clientId: "acme",
+        limit: 50,
+        offset: 100,
+        orderBy: "total_desc",
+      });
+      const body = JSON.parse(calls[0].init.body);
+      expect(body.limit).toBe(50);
+      expect(body.offset).toBe(100);
+      expect(body.order_by).toBe("total_desc");
+    });
+
+    it("returns the response body verbatim", async () => {
+      const expected = {
+        total_count: 2,
+        has_more: false,
+        items: [
+          {
+            person_email: "alex@x.io",
+            person_name: "Alex Tong",
+            total: 42,
+            inbound: 20,
+            outbound: 22,
+            last_seen: "2026-05-13T10:00:00Z",
+            first_seen: "2024-01-01T00:00:00Z",
+            channels: [
+              {
+                channel: "email",
+                count: 30,
+                inbound: 15,
+                outbound: 15,
+                last_seen: "2026-05-13T10:00:00Z",
+                first_seen: "2024-01-01T00:00:00Z",
+              },
+            ],
+          },
+          {
+            person_email: "bea@y.io",
+            person_name: null,
+            total: 5,
+            inbound: 5,
+            outbound: 0,
+            last_seen: "2026-04-01T00:00:00Z",
+            first_seen: "2025-12-01T00:00:00Z",
+            channels: [],
+          },
+        ],
+      };
+      mockOk(expected);
+      const out = await enginePeopleList("https://e", { clientId: "acme" });
+      expect(out).toEqual(expected);
+    });
+  });
+
   describe("engineForget", () => {
     it("forwards id when provided", async () => {
       mockOk({ deleted: 1 });

package/packages/memory/src/engine.js

@@ -346,3 +346,89 @@ export async function engineAggregate(engineUrl, opts) {
   };
   return fetchEngine(engineUrl, "/aggregate", body, { headers });
 }
+
+/**
+ * Corpus-level "all people I've communicated with" projection.
+ *
+ * Distinct from ``engineAggregate``, which returns the per-channel
+ * breakdown for ONE person: ``enginePeopleList`` returns one row
+ * per Person across one or more arenas, with the per-channel
+ * breakdown nested. Backs the Pip Relationships UI list page (and
+ * any future "people known to X" query) without the per-person
+ * round-trip that 8k contacts would otherwise require.
+ *
+ * Multi-arena is intentional: cross-user views like "people known
+ * by Philip OR Jeanne" are a legitimate use case here, and the
+ * engine dedups by person_email so the response is collapsed
+ * before paginating.
+ *
+ * ``arenas`` defaults to ``composeArenas(clientId, userId)`` — the
+ * usual `[clientId, clientId:userId]` pair, matching engineSearch.
+ * Pass an explicit arena list when you need cross-user spans.
+ *
+ * ``emails`` is a batched-mode filter (return only these emails).
+ * Used by Pip's nightly health-recompute to fetch facets for a
+ * known set of contacts in one call.
+ *
+ * @param {string} engineUrl
+ * @param {object} opts
+ * @param {string} [opts.clientId]              required unless ``arenas`` is set
+ * @param {string} [opts.userId]                appended to default arena
+ * @param {string[]} [opts.arenas]              explicit arena list; overrides clientId/userId
+ * @param {string[]} [opts.emails]              batched-mode filter
+ * @param {string} [opts.search]                case-insensitive substring on name/email
+ * @param {number} [opts.limit=200]
+ * @param {number} [opts.offset=0]
+ * @param {("last_seen_desc"|"last_seen_asc"|"total_desc"|"total_asc"|"name_asc"|"name_desc")} [opts.orderBy="last_seen_desc"]
+ * @param {Record<string,string>} [opts.headers]   forwarded HTTP headers (CF Access etc.)
+ * @returns {Promise<{
+ *   total_count: number,
+ *   has_more: boolean,
+ *   items: Array<{
+ *     person_email: string,
+ *     person_name: string|null,
+ *     total: number,
+ *     inbound: number,
+ *     outbound: number,
+ *     last_seen: string|null,
+ *     first_seen: string|null,
+ *     channels: Array<{
+ *       channel: string,
+ *       count: number,
+ *       inbound: number,
+ *       outbound: number,
+ *       last_seen: string|null,
+ *       first_seen: string|null,
+ *     }>,
+ *   }>,
+ * }>}
+ */
+export async function enginePeopleList(engineUrl, opts) {
+  const {
+    clientId,
+    userId,
+    arenas,
+    emails,
+    search,
+    limit,
+    offset,
+    orderBy,
+    headers,
+  } = opts || {};
+  let arenaList = arenas;
+  if (!arenaList || arenaList.length === 0) {
+    if (!clientId) {
+      throw new Error("enginePeopleList: clientId or arenas required");
+    }
+    arenaList = composeArenas(clientId, userId);
+  }
+  const body = {
+    arenas: arenaList,
+    limit: typeof limit === "number" ? limit : 200,
+    offset: typeof offset === "number" ? offset : 0,
+    order_by: orderBy || "last_seen_desc",
+    ...(emails && emails.length > 0 ? { emails } : {}),
+    ...(search ? { search } : {}),
+  };
+  return fetchEngine(engineUrl, "/people-list", body, { headers });
+}

package/packages/memory-engine/compat/server.py

@@ -140,6 +140,34 @@ class AggregateRequest(BaseModel):
     group_by: Optional[list[str]] = None
 
 
+class PeopleListRequest(BaseModel):
+    """Public-facing /people-list request.
+
+    Corpus-level "all people across these arenas" projection backing
+    the Pip Relationships UI list page. Distinct from /aggregate
+    (which is per-person): /people-list returns one row per Person
+    across the whole arena set, with per-channel breakdown nested.
+
+    Multi-arena is supported here (unlike /aggregate) because the
+    UI use case — "people known by Philip OR Jeanne" — is a
+    legitimate cross-user view. The L2 proxy does the dedup by
+    person_email.
+
+    `emails`: batched-mode filter. Return only these emails.
+    `search`: case-insensitive substring on person_name and
+              person_email.
+    `order_by`: whitelisted sort key; see the L2 proxy for the
+                allowlist.
+    """
+
+    arenas: list[str]
+    emails: Optional[list[str]] = None
+    search: Optional[str] = None
+    limit: int = 200
+    offset: int = 0
+    order_by: str = "last_seen_desc"
+
+
 # ----------------------------------------------------------------------
 # Engine clients (one per layer)
 # ----------------------------------------------------------------------
@@ -1089,6 +1117,55 @@ async def aggregate(req: AggregateRequest) -> dict[str, Any]:
         raise HTTPException(status_code=502, detail=f"aggregate upstream: {exc}")
 
 
+@app.post("/people-list")
+async def people_list(req: PeopleListRequest) -> dict[str, Any]:
+    """List all people across one or more arenas.
+
+    Pass-through to the L2 proxy's /people-list-internal which runs a
+    single Cypher pass over the ChannelStat denorm keyed on
+    (arena, person_email, channel). Returns paginated, filtered,
+    sorted rows with per-channel breakdown.
+
+    Shim's job: shape validation + arena enforcement. The real
+    aggregation lives in L3 over ChannelStat — see PRs #28-33 for
+    the writer side that maintains those nodes.
+
+    Multi-arena: legitimate here (unlike /aggregate). The UI
+    fetches "people known by Philip OR Jeanne" by passing both
+    arenas; the L2 proxy collapses duplicates by person_email.
+    """
+    arenas = [a.strip() for a in (req.arenas or []) if a and a.strip()]
+    if not arenas:
+        raise HTTPException(status_code=400, detail="at least one arena is required")
+    payload: dict[str, Any] = {
+        "arenas": arenas,
+        "limit": req.limit,
+        "offset": req.offset,
+        "order_by": req.order_by,
+    }
+    if req.emails:
+        # Lowercase here so the L2 path can rely on exact-match; the
+        # writer side also lowercases person_email on the ChannelStat
+        # node, so this stays consistent.
+        payload["emails"] = [e.strip().lower() for e in req.emails if e and e.strip()]
+    if req.search:
+        payload["search"] = req.search.strip()
+    try:
+        r = await _client().post(
+            f"{L2_PROXY_URL}/people-list-internal", json=payload, timeout=15.0,
+        )
+        if r.status_code != 200:
+            raise HTTPException(
+                status_code=r.status_code,
+                detail=f"people-list failed: {r.text[:200]}",
+            )
+        return r.json()
+    except HTTPException:
+        raise
+    except Exception as exc:
+        raise HTTPException(status_code=502, detail=f"people-list upstream: {exc}")
+
+
 # ----------------------------------------------------------------------
 # Entrypoint
 # ----------------------------------------------------------------------

package/packages/memory-engine/engine/services/l2/l2-hybridrag-proxy.py

@@ -1167,7 +1167,7 @@ async def search_endpoint(request: Request) -> dict:
         # the entities returned could include cross-tenant rows.
         arena_list = list(arenas) if arenas else ([arena] if arena else [])
         entities = extract_query_entities(query)
-        graph_context = search_neo4j_sequential(query, entities, arena_list, limit=8)
+        graph_context = await search_neo4j_sequential(query, entities, arena_list, limit=8)
 
         return {
             "results": results,
@@ -2200,6 +2200,283 @@ async def aggregate_internal(req: AggregateInternalRequest) -> AggregateInternal
         raise HTTPException(status_code=500, detail=f"aggregate failed: {e}")
 
 
+# ── /people-list-internal ───────────────────────────────────────────────
+#
+# Corpus-level "all people in these arenas" projection backing the Pip
+# Relationships UI list page. Different aggregation level from
+# /aggregate-internal: that one returns buckets PER ONE PERSON; this one
+# returns one row PER PERSON across the whole arena, sorted by recency.
+#
+# Reads the ChannelStat denorm directly. ChannelStats are keyed on
+# (arena, person_email, channel) and maintained on every store by the
+# writer block above (~line 1645 onwards). Each person has one
+# ChannelStat row per channel they appear on. Aggregating over
+# person_email collapses to one row per person; the per-channel
+# breakdown rides along as a nested list for callers who want both.
+#
+# Falls back to an edge walk path only when ChannelStats are absent
+# for the arena (older tenant predating the rollup writer). In normal
+# operation the fast path serves every read.
+
+class PeopleListInternalRequest(BaseModel):
+    """List all people communicated with across one or more arenas.
+
+    Multi-arena support exists so the Pip Relationships UI can answer
+    "which colleagues do Philip AND Jeanne both know" without N round-
+    trips. The endpoint is invariant to arena ordering — duplicates
+    across arenas are collapsed by person_email.
+
+    `emails` is a batched-mode filter (return only these emails). Used
+    by Pip's nightly health-recompute to fetch facets for a known set
+    of contacts in one call.
+
+    `search` matches person_email and person_name as case-insensitive
+    substrings. Empty/null → no filter. Server-side, so the caller
+    doesn't have to overfetch.
+
+    Pagination is `limit`/`offset`. Default limit matches the Pip UI
+    page size; large limits are fine since the underlying read is one
+    Cypher query against an indexed denorm.
+    """
+
+    arenas: List[str]
+    emails: Optional[List[str]] = None
+    search: Optional[str] = None
+    limit: int = 200
+    offset: int = 0
+    # Sort key. Whitelisted; unknown → ValidationError so callers can't
+    # smuggle Cypher fragments into the ORDER BY.
+    order_by: str = "last_seen_desc"
+
+
+class ChannelStatBucket(BaseModel):
+    """Per-channel breakdown for one person, denormalised from ChannelStat."""
+
+    channel: str
+    count: int
+    inbound: int
+    outbound: int
+    last_seen: Optional[str] = None
+    first_seen: Optional[str] = None
+
+
+class PeopleListEntry(BaseModel):
+    """One person's rollup in the corpus-level list response."""
+
+    person_email: str
+    person_name: Optional[str] = None
+    total: int
+    inbound: int
+    outbound: int
+    last_seen: Optional[str] = None
+    first_seen: Optional[str] = None
+    channels: List[ChannelStatBucket]
+
+
+class PeopleListInternalResponse(BaseModel):
+    """Paginated people-list result.
+
+    `total_count` is the distinct-people count after filters, before
+    pagination — so the caller can paint a "Showing 1-200 of 1206"
+    header without a second round-trip. `has_more` is the derived
+    pagination signal.
+    """
+
+    total_count: int
+    has_more: bool
+    items: List[PeopleListEntry]
+
+
+# Whitelist for order_by to keep the ORDER BY clause injection-safe.
+# Values are templated into Cypher after `WITH row` so each one must
+# qualify properties with `row.` (or wrap in a function that does).
+_PEOPLE_LIST_ORDER_BY = {
+    "last_seen_desc": "row.last_seen DESC",
+    "last_seen_asc": "row.last_seen ASC",
+    "total_desc": "row.total DESC",
+    "total_asc": "row.total ASC",
+    "name_asc": "coalesce(row.person_name, row.person_email) ASC",
+    "name_desc": "coalesce(row.person_name, row.person_email) DESC",
+}
+
+
+@app.post("/people-list-internal", response_model=PeopleListInternalResponse)
+async def people_list_internal(
+    req: PeopleListInternalRequest,
+) -> PeopleListInternalResponse:
+    """Corpus-level "all people I've communicated with" projection.
+
+    Single Cypher pass over ChannelStat keyed on (arena, person_email).
+    Returns paginated, filtered, sorted rows with per-channel
+    breakdown for each person.
+
+    Authentication is enforced by the surrounding TES module
+    (`authorizeClient` in resolvers.js); this endpoint itself trusts
+    its caller by virtue of running inside the engine network.
+    """
+
+    arenas = [a.strip() for a in (req.arenas or []) if a and a.strip()]
+    if not arenas:
+        raise HTTPException(status_code=400, detail="at least one arena is required")
+
+    if req.order_by not in _PEOPLE_LIST_ORDER_BY:
+        raise HTTPException(
+            status_code=400,
+            detail=f"order_by must be one of: {sorted(_PEOPLE_LIST_ORDER_BY)}",
+        )
+    order_clause = _PEOPLE_LIST_ORDER_BY[req.order_by]
+
+    limit = max(1, min(req.limit or 200, 2000))
+    offset = max(0, req.offset or 0)
+    emails_filter = (
+        [e.strip().lower() for e in req.emails if e and e.strip()]
+        if req.emails
+        else None
+    )
+    search_pattern = (req.search or "").strip().lower() or None
+
+    driver = get_neo4j_driver()
+
+    try:
+        async with driver.session() as session:
+            # Fast path: read ChannelStat directly. Aggregation walks
+            # the (arena, person_email) compound index — O(channels)
+            # per person, one row per channel.
+            #
+            # Two-stage shape: first WITH collects per-person rollups
+            # (sum across channels + collect the per-channel buckets);
+            # second WITH applies the filter, sort, total, and pagination.
+            params: Dict[str, Any] = {
+                "arenas": arenas,
+                "limit": limit,
+                "offset": offset,
+            }
+
+            # Build the filter clause. `arena IN $arenas` is the
+            # multi-arena gate. `s.person_email IN $emails` is the
+            # batched-mode filter; toLower handles caller-side case
+            # drift. `search` matches against person_email or
+            # (joined) person_name.
+            email_filter_clause = ""
+            if emails_filter:
+                email_filter_clause = " AND s.person_email IN $emails"
+                params["emails"] = emails_filter
+
+            search_clause = ""
+            if search_pattern:
+                # Match against person_email; person_name is resolved
+                # via the OPTIONAL MATCH on Person below, so we can't
+                # apply it inside the initial WHERE without joining first.
+                # Two-step: filter on email here, then re-filter after
+                # joining the Person. (Works at our scale; revisit if
+                # we ever need search to scale to 10k+ people.)
+                search_clause = " AND toLower(s.person_email) CONTAINS $search"
+                params["search"] = search_pattern
+
+            cypher = (
+                "MATCH (s:ChannelStat)\n"
+                "WHERE s.arena IN $arenas"
+                + email_filter_clause
+                + search_clause
+                + "\n"
+                "WITH s.person_email AS person_email,\n"
+                "     collect({channel: s.channel, count: s.count,\n"
+                "              inbound: s.inbound, outbound: s.outbound,\n"
+                "              last_seen: s.last_seen, first_seen: s.first_seen,\n"
+                "              arena: s.arena}) AS channels\n"
+                # Resolve display name from the typed-Person node when
+                # one exists. OPTIONAL so people who only have edge data
+                # (no Person node yet) still show up — name falls back
+                # to email at the caller.
+                "OPTIONAL MATCH (p:Person {email: person_email})\n"
+                "WHERE p.arena IN $arenas\n"
+                "WITH person_email,\n"
+                "     channels,\n"
+                "     head(collect(DISTINCT p.name)) AS person_name\n"
+                # Apply the name-side of the search filter now that we
+                # have the joined name.
+                + (
+                    "WHERE ($search IS NULL OR person_name IS NULL OR toLower(person_name) CONTAINS $search\n"
+                    "       OR toLower(person_email) CONTAINS $search)\n"
+                    if search_pattern
+                    else ""
+                )
+                + "WITH person_email, person_name, channels,\n"
+                "     reduce(t = 0, x IN channels | t + coalesce(x.count, 0)) AS total,\n"
+                "     reduce(t = 0, x IN channels | t + coalesce(x.inbound, 0)) AS inbound,\n"
+                "     reduce(t = 0, x IN channels | t + coalesce(x.outbound, 0)) AS outbound,\n"
+                "     reduce(latest = '', x IN channels |\n"
+                "         CASE WHEN x.last_seen IS NOT NULL AND toString(x.last_seen) > latest\n"
+                "              THEN toString(x.last_seen) ELSE latest END) AS last_seen_raw,\n"
+                "     reduce(earliest = '', x IN channels |\n"
+                "         CASE WHEN x.first_seen IS NOT NULL AND (earliest = '' OR toString(x.first_seen) < earliest)\n"
+                "              THEN toString(x.first_seen) ELSE earliest END) AS first_seen_raw\n"
+                "WITH person_email, person_name, channels, total, inbound, outbound,\n"
+                "     CASE WHEN last_seen_raw = '' THEN null ELSE last_seen_raw END AS last_seen,\n"
+                "     CASE WHEN first_seen_raw = '' THEN null ELSE first_seen_raw END AS first_seen\n"
+                # collect-into-list and then split is the standard
+                # Cypher trick for getting both the total count and a
+                # paginated slice from one query.
+                "WITH collect({person_email: person_email, person_name: person_name,\n"
+                "              channels: channels, total: total,\n"
+                "              inbound: inbound, outbound: outbound,\n"
+                "              last_seen: last_seen, first_seen: first_seen}) AS all_rows\n"
+                "WITH all_rows, size(all_rows) AS total_count\n"
+                "UNWIND all_rows AS row\n"
+                f"WITH row, total_count ORDER BY {order_clause}\n"
+                "SKIP $offset LIMIT $limit\n"
+                "RETURN total_count, collect(row) AS page\n"
+            )
+
+            res = await session.run(cypher, **params)
+            record = await res.single()
+            if record is None:
+                return PeopleListInternalResponse(
+                    total_count=0, has_more=False, items=[]
+                )
+
+            total_count = int(record["total_count"] or 0)
+            page = record["page"] or []
+
+            items: List[PeopleListEntry] = []
+            for row in page:
+                channels = [
+                    ChannelStatBucket(
+                        channel=ch.get("channel") or "unknown",
+                        count=int(ch.get("count") or 0),
+                        inbound=int(ch.get("inbound") or 0),
+                        outbound=int(ch.get("outbound") or 0),
+                        last_seen=str(ch.get("last_seen")) if ch.get("last_seen") else None,
+                        first_seen=str(ch.get("first_seen")) if ch.get("first_seen") else None,
+                    )
+                    for ch in (row.get("channels") or [])
+                ]
+                items.append(
+                    PeopleListEntry(
+                        person_email=row.get("person_email"),
+                        person_name=row.get("person_name"),
+                        total=int(row.get("total") or 0),
+                        inbound=int(row.get("inbound") or 0),
+                        outbound=int(row.get("outbound") or 0),
+                        last_seen=str(row.get("last_seen")) if row.get("last_seen") else None,
+                        first_seen=str(row.get("first_seen")) if row.get("first_seen") else None,
+                        channels=channels,
+                    )
+                )
+
+            return PeopleListInternalResponse(
+                total_count=total_count,
+                has_more=(offset + len(items)) < total_count,
+                items=items,
+            )
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        log.error(f"people-list-internal failed: {e}")
+        raise HTTPException(status_code=500, detail=f"people-list failed: {e}")
+
+
 @app.get("/index-internal-stats")
 async def index_internal_stats() -> dict:
     """Quick sanity check that the L0/L4-qmd/L3 stores are populated."""

package/packages/memory-engine/tests/test_people_list_reader.py

@@ -0,0 +1,379 @@
+"""Integration tests for the /people-list-internal endpoint.
+
+Sister file to ``test_channel_stat_reader.py``: that one covers
+``aggregate_internal`` (per-person aggregate); this one covers
+``people_list_internal`` (corpus-level aggregate — one row per
+Person across one or more arenas).
+
+The endpoint backs the Pip Relationships UI list page. Where
+``aggregate_internal`` returns the per-channel breakdown FOR one
+person, ``people_list_internal`` returns one row PER PERSON across
+the whole arena set, with the per-channel breakdown nested.
+
+Gated on NEO4J_TEST_URI + NEO4J_TEST_PASSWORD; skip cleanly when
+those env vars are absent so unit-only test runs stay fast.
+
+Run:
+
+    cd packages/memory-engine
+    NEO4J_TEST_URI=bolt://localhost:17687 \\
+    NEO4J_TEST_PASSWORD=testpassword \\
+    .venv/bin/python -m pytest tests/test_people_list_reader.py -v
+"""
+from __future__ import annotations
+
+import asyncio
+import importlib.util
+import os
+import sys
+import uuid
+from pathlib import Path
+
+import pytest
+
+
+_NEO4J_URI = os.environ.get("NEO4J_TEST_URI")
+_NEO4J_USER = os.environ.get("NEO4J_TEST_USER", "neo4j")
+_NEO4J_PASSWORD = os.environ.get("NEO4J_TEST_PASSWORD")
+
+_skip_no_neo4j = pytest.mark.skipif(
+    not (_NEO4J_URI and _NEO4J_PASSWORD),
+    reason="set NEO4J_TEST_URI + NEO4J_TEST_PASSWORD to run integration tests",
+)
+
+
+ENGINE_ROOT = Path(__file__).resolve().parent.parent / "engine" / "services" / "l2"
+sys.path.insert(0, str(ENGINE_ROOT))
+
+
+@pytest.fixture(scope="module")
+def proxy_module():
+    """Mirror of the helper in test_channel_stat_reader.py — load
+    l2-hybridrag-proxy as a module so we can call the FastAPI handler
+    directly without HTTP. Override NEO4J_URI/NEO4J_AUTH at runtime
+    rather than at import time."""
+    spec = importlib.util.spec_from_file_location(
+        "l2_proxy_module",
+        ENGINE_ROOT / "l2-hybridrag-proxy.py",
+    )
+    assert spec and spec.loader
+    try:
+        mod = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(mod)
+    except ImportError:
+        pytest.skip("l2 proxy deps unavailable in this venv (fine for unit-only runs)")
+    mod.NEO4J_URI = _NEO4J_URI
+    mod.NEO4J_AUTH = (_NEO4J_USER, _NEO4J_PASSWORD)
+    return mod
+
+
+@pytest.fixture
+def neo4j_driver():
+    """Per-test driver + cleanup. Three arenas so multi-arena tests
+    have something to span across."""
+    from neo4j import GraphDatabase
+
+    driver = GraphDatabase.driver(_NEO4J_URI, auth=(_NEO4J_USER, _NEO4J_PASSWORD))
+    arenas = [
+        f"pl_a_{uuid.uuid4().hex[:8]}",
+        f"pl_b_{uuid.uuid4().hex[:8]}",
+        f"pl_c_{uuid.uuid4().hex[:8]}",
+    ]
+    yield driver, arenas
+    with driver.session() as session:
+        for arena in arenas:
+            session.run(
+                "MATCH (n) WHERE n.arena = $arena DETACH DELETE n",
+                arena=arena,
+            )
+    driver.close()
+
+
+def _ensure_indexes(session) -> None:
+    """Idempotent index + constraint setup matching the writer block."""
+    session.run(
+        "CREATE INDEX channelstat_arena_email IF NOT EXISTS "
+        "FOR (s:ChannelStat) ON (s.arena, s.person_email)"
+    )
+    session.run(
+        "CREATE CONSTRAINT channelstat_unique IF NOT EXISTS "
+        "FOR (s:ChannelStat) REQUIRE (s.arena, s.person_email, s.channel) IS UNIQUE"
+    )
+
+
+def _write_stat(
+    session,
+    arena: str,
+    email: str,
+    channel: str,
+    count: int = 1,
+    inbound: int = 0,
+    outbound: int = 0,
+    last_seen: str = "2026-05-10T00:00:00Z",
+    first_seen: str = "2024-01-01T00:00:00Z",
+    name: str | None = None,
+) -> None:
+    """Insert a ChannelStat node + matching Person (with optional
+    name). Skips the Chunk + COMMUNICATED edge — those aren't read
+    by ``people_list_internal`` since it reads the denorm directly."""
+    session.run(
+        """
+        MERGE (s:ChannelStat {arena: $arena, person_email: $email, channel: $channel})
+        SET s.count = $count,
+            s.inbound = $inbound,
+            s.outbound = $outbound,
+            s.last_seen = $last_seen,
+            s.first_seen = $first_seen
+        """,
+        arena=arena, email=email, channel=channel,
+        count=count, inbound=inbound, outbound=outbound,
+        last_seen=last_seen, first_seen=first_seen,
+    )
+    # Person node carries the display name. Email is the join key.
+    # OPTIONAL MATCH in the reader joins on email + arena.
+    session.run(
+        """
+        MERGE (p:Entity:Person {arena: $arena, email: $email})
+        SET p.name = $name
+        """,
+        arena=arena, email=email, name=name,
+    )
+
+
+def _call_people_list(proxy_module, **kwargs):
+    """Invoke people_list_internal directly. Same shape as
+    _call_aggregate in the sister file."""
+    req = proxy_module.PeopleListInternalRequest(**kwargs)
+    return asyncio.run(proxy_module.people_list_internal(req))
+
+
+# ---------------------------------------------------------------------------
+# Single-arena basic behaviour.
+# ---------------------------------------------------------------------------
+
+
+@_skip_no_neo4j
+def test_returns_one_row_per_person_with_channels_nested(
+    neo4j_driver, proxy_module
+) -> None:
+    """Three ChannelStats for two people in one arena → two list rows.
+    Channels collapse into the nested ``channels`` list per person."""
+    driver, (arena, _, _) = neo4j_driver
+    with driver.session() as session:
+        _ensure_indexes(session)
+        # Alex: email + slack
+        _write_stat(session, arena, "alex@x.io", "email", count=3, inbound=2, outbound=1,
+                    last_seen="2026-05-10T00:00:00Z", name="Alex Tong")
+        _write_stat(session, arena, "alex@x.io", "slack", count=1, inbound=1, outbound=0,
+                    last_seen="2026-05-08T00:00:00Z", name="Alex Tong")
+        # Bea: email only
+        _write_stat(session, arena, "bea@y.io", "email", count=5, inbound=5, outbound=0,
+                    last_seen="2026-05-09T00:00:00Z", name="Bea Chen")
+
+    out = _call_people_list(proxy_module, arenas=[arena])
+    assert out.total_count == 2
+    assert out.has_more is False
+    emails = sorted(item.person_email for item in out.items)
+    assert emails == ["alex@x.io", "bea@y.io"]
+    alex = next(item for item in out.items if item.person_email == "alex@x.io")
+    assert alex.person_name == "Alex Tong"
+    assert alex.total == 4  # 3 email + 1 slack
+    assert alex.inbound == 3
+    assert alex.outbound == 1
+    assert alex.last_seen == "2026-05-10T00:00:00Z"
+    assert {ch.channel for ch in alex.channels} == {"email", "slack"}
+
+
+@_skip_no_neo4j
+def test_default_order_is_last_seen_desc(neo4j_driver, proxy_module) -> None:
+    """Default sort: most-recently-active person first. Backs the
+    Relationships UI's default landing view."""
+    driver, (arena, _, _) = neo4j_driver
+    with driver.session() as session:
+        _ensure_indexes(session)
+        _write_stat(session, arena, "old@x.io", "email", last_seen="2025-01-01T00:00:00Z")
+        _write_stat(session, arena, "new@x.io", "email", last_seen="2026-05-12T00:00:00Z")
+        _write_stat(session, arena, "mid@x.io", "email", last_seen="2026-01-01T00:00:00Z")
+
+    out = _call_people_list(proxy_module, arenas=[arena])
+    assert [i.person_email for i in out.items] == ["new@x.io", "mid@x.io", "old@x.io"]
+
+
+# ---------------------------------------------------------------------------
+# Multi-arena behaviour.
+# ---------------------------------------------------------------------------
+
+
+@_skip_no_neo4j
+def test_multi_arena_returns_persons_from_both_arenas(
+    neo4j_driver, proxy_module
+) -> None:
+    """A vendor who appears in arena A AND arena B should be one row
+    with both arenas' channel data. Backs the "people known by Philip
+    OR Jeanne" use case."""
+    driver, (arena_a, arena_b, _) = neo4j_driver
+    with driver.session() as session:
+        _ensure_indexes(session)
+        # Same vendor in both arenas
+        _write_stat(session, arena_a, "vendor@v.io", "email", count=2,
+                    last_seen="2026-05-10T00:00:00Z", name="Vendor Co")
+        _write_stat(session, arena_b, "vendor@v.io", "slack", count=3,
+                    last_seen="2026-05-11T00:00:00Z", name="Vendor Co")
+        # Unique-to-A person
+        _write_stat(session, arena_a, "only@a.io", "email", last_seen="2026-05-09T00:00:00Z")
+
+    out = _call_people_list(proxy_module, arenas=[arena_a, arena_b])
+    emails = sorted(i.person_email for i in out.items)
+    assert emails == ["only@a.io", "vendor@v.io"]
+    vendor = next(i for i in out.items if i.person_email == "vendor@v.io")
+    # Total across both arenas
+    assert vendor.total == 5
+    # Both channels surface
+    assert {ch.channel for ch in vendor.channels} == {"email", "slack"}
+    # last_seen is the max across arenas
+    assert vendor.last_seen == "2026-05-11T00:00:00Z"
+
+
+@_skip_no_neo4j
+def test_arena_filter_excludes_other_arenas(neo4j_driver, proxy_module) -> None:
+    """A person in arena C must NOT appear when only A+B are requested."""
+    driver, (arena_a, arena_b, arena_c) = neo4j_driver
+    with driver.session() as session:
+        _ensure_indexes(session)
+        _write_stat(session, arena_a, "a-only@x.io", "email")
+        _write_stat(session, arena_c, "c-only@x.io", "email")
+
+    out = _call_people_list(proxy_module, arenas=[arena_a, arena_b])
+    emails = {i.person_email for i in out.items}
+    assert "a-only@x.io" in emails
+    assert "c-only@x.io" not in emails
+
+
+# ---------------------------------------------------------------------------
+# Filters.
+# ---------------------------------------------------------------------------
+
+
+@_skip_no_neo4j
+def test_emails_filter_restricts_to_listed_addresses(
+    neo4j_driver, proxy_module
+) -> None:
+    """``emails`` is the batched-mode filter — used by Pip's nightly
+    health-recompute to fetch facets for many specific people in one
+    call. Cuts 8k×9 SQL queries to ~9 GraphQL calls."""
+    driver, (arena, _, _) = neo4j_driver
+    with driver.session() as session:
+        _ensure_indexes(session)
+        _write_stat(session, arena, "alex@x.io", "email")
+        _write_stat(session, arena, "bea@y.io", "email")
+        _write_stat(session, arena, "carl@z.io", "email")
+
+    out = _call_people_list(
+        proxy_module,
+        arenas=[arena],
+        emails=["alex@x.io", "carl@z.io"],
+    )
+    emails = sorted(i.person_email for i in out.items)
+    assert emails == ["alex@x.io", "carl@z.io"]
+
+
+@_skip_no_neo4j
+def test_search_substring_matches_email_or_name(
+    neo4j_driver, proxy_module
+) -> None:
+    """Search is case-insensitive substring on person_name and
+    person_email. Backs the Relationships UI search box."""
+    driver, (arena, _, _) = neo4j_driver
+    with driver.session() as session:
+        _ensure_indexes(session)
+        _write_stat(session, arena, "alex@pentatonic.com", "email", name="Alex Tong")
+        _write_stat(session, arena, "bea@pentatonic.com", "email", name="Bea Chen")
+        _write_stat(session, arena, "carl@external.com", "email", name="Carl X")
+
+    # Search by name fragment
+    out = _call_people_list(proxy_module, arenas=[arena], search="alex")
+    assert {i.person_email for i in out.items} == {"alex@pentatonic.com"}
+
+    # Search by email-domain fragment matches everyone at pentatonic
+    out = _call_people_list(proxy_module, arenas=[arena], search="pentatonic")
+    assert {i.person_email for i in out.items} == {
+        "alex@pentatonic.com", "bea@pentatonic.com",
+    }
+
+
+# ---------------------------------------------------------------------------
+# Pagination.
+# ---------------------------------------------------------------------------
+
+
+@_skip_no_neo4j
+def test_pagination_limit_and_offset(neo4j_driver, proxy_module) -> None:
+    """`limit` slices the page; `total_count` is the unfiltered count
+    BEFORE pagination so the UI can render "Showing N of M"."""
+    driver, (arena, _, _) = neo4j_driver
+    with driver.session() as session:
+        _ensure_indexes(session)
+        # 5 people, last_seen ascending so a desc sort puts e first
+        for i, letter in enumerate("abcde"):
+            _write_stat(
+                session, arena, f"{letter}@x.io", "email",
+                last_seen=f"2026-05-{10 + i:02d}T00:00:00Z",
+            )
+
+    page1 = _call_people_list(proxy_module, arenas=[arena], limit=2, offset=0)
+    page2 = _call_people_list(proxy_module, arenas=[arena], limit=2, offset=2)
+    page3 = _call_people_list(proxy_module, arenas=[arena], limit=2, offset=4)
+    assert page1.total_count == 5 == page2.total_count == page3.total_count
+    assert page1.has_more is True
+    assert page2.has_more is True
+    assert page3.has_more is False
+    assert [i.person_email for i in page1.items] == ["e@x.io", "d@x.io"]
+    assert [i.person_email for i in page2.items] == ["c@x.io", "b@x.io"]
+    assert [i.person_email for i in page3.items] == ["a@x.io"]
+
+
+@_skip_no_neo4j
+def test_order_by_total_desc(neo4j_driver, proxy_module) -> None:
+    driver, (arena, _, _) = neo4j_driver
+    with driver.session() as session:
+        _ensure_indexes(session)
+        _write_stat(session, arena, "many@x.io", "email", count=100)
+        _write_stat(session, arena, "few@x.io", "email", count=5)
+        _write_stat(session, arena, "mid@x.io", "email", count=50)
+
+    out = _call_people_list(proxy_module, arenas=[arena], order_by="total_desc")
+    assert [i.person_email for i in out.items] == [
+        "many@x.io", "mid@x.io", "few@x.io",
+    ]
+
+
+# ---------------------------------------------------------------------------
+# Validation.
+# ---------------------------------------------------------------------------
+
+
+@_skip_no_neo4j
+def test_empty_arenas_list_rejected(neo4j_driver, proxy_module) -> None:
+    """An empty arenas list should 400, not silently return everything.
+    Multi-tenant safety: a missing/empty filter must not become an
+    'all tenants' query."""
+    from fastapi import HTTPException
+
+    with pytest.raises(HTTPException) as exc:
+        _call_people_list(proxy_module, arenas=[])
+    assert exc.value.status_code == 400
+
+
+@_skip_no_neo4j
+def test_unknown_order_by_rejected(neo4j_driver, proxy_module) -> None:
+    """Whitelisted sort keys — anything else 400s. Belt-and-braces
+    against ORDER BY templating becoming an injection vector."""
+    from fastapi import HTTPException
+
+    driver, (arena, _, _) = neo4j_driver
+    with pytest.raises(HTTPException) as exc:
+        _call_people_list(
+            proxy_module, arenas=[arena],
+            order_by="totally_made_up",
+        )
+    assert exc.value.status_code == 400