@pentatonic-ai/ai-agent-sdk 0.8.0 → 0.8.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pentatonic-ai/ai-agent-sdk",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "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/openclaw-plugin/index.js

@@ -500,6 +500,13 @@ export default {
   description: "Persistent, searchable memory with multi-signal retrieval and HyDE query expansion",
   kind: "context-engine",
 
+  // Tool contracts (names + parameter schemas) live in openclaw.plugin.json
+  // under the top-level "contracts.tools" key — that's what the openclaw
+  // loader reads at install time. The execute bodies are registered at
+  // runtime via api.registerTool(...) inside register() below; names and
+  // schemas there MUST match the manifest contracts or 5.7+ will refuse
+  // to register the tool.
+
   register(api) {
     const config = api.pluginConfig || api.config?.plugins?.entries?.["pentatonic-memory"]?.config || api.config || {};
     const hosted = !!(config.tes_endpoint && config.tes_api_key);

package/packages/memory/openclaw-plugin/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "pentatonic-memory",
   "name": "Pentatonic Memory",
   "description": "Persistent, searchable memory with multi-signal retrieval and HyDE query expansion. Local (Docker + Ollama) or hosted (Pentatonic TES).",
-  "version": "0.8.4",
+  "version": "0.8.5",
   "kind": "context-engine",
   "configSchema": {
     "type": "object",
@@ -75,5 +75,13 @@
   },
   "setup": {
     "description": "Set up persistent memory — local (Docker + Ollama, fully private) or hosted (Pentatonic TES, team-wide)."
+  },
+  "contracts": {
+    "tools": [
+      "pentatonic_memory_search",
+      "pentatonic_memory_store",
+      "pentatonic_memory_status",
+      "pentatonic_memory_setup"
+    ]
   }
 }

package/packages/memory/openclaw-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pentatonic-ai/openclaw-memory-plugin",
-  "version": "0.8.4",
+  "version": "0.8.5",
   "description": "Pentatonic Memory plugin for OpenClaw — persistent, searchable memory with multi-signal retrieval and HyDE query expansion",
   "type": "module",
   "main": "index.js",

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

@@ -3,6 +3,7 @@ import {
   fetchEngine,
   engineStore,
   engineSearch,
+  engineAggregate,
   engineForget,
   composeArena,
   composeArenas,
@@ -315,6 +316,147 @@ describe("engine HTTP client", () => {
     });
   });
 
+  describe("engineAggregate", () => {
+    it("posts to /aggregate with single arena (tenant-only when no userId)", async () => {
+      mockOk({ arena: "acme", total: 0, last_seen: null, buckets: [] });
+      await engineAggregate("https://e", {
+        clientId: "acme",
+        contactEmail: "alex@x.io",
+      });
+      const body = JSON.parse(calls[0].init.body);
+      expect(calls[0].url).toBe("https://e/aggregate");
+      expect(body).toEqual({
+        arena: "acme",
+        contact_email: "alex@x.io",
+        group_by: ["channel"],
+      });
+      // Aggregate is single-arena by design (cross-tenant aggregation
+      // would be a multi-tenancy violation), so no `arenas` list.
+      expect(body).not.toHaveProperty("arenas");
+    });
+
+    it("scopes to user-arena (clientId:userId) when userId is set", async () => {
+      mockOk({ arena: "acme:user-42", total: 0, last_seen: null, buckets: [] });
+      await engineAggregate("https://e", {
+        clientId: "acme",
+        userId: "user-42",
+        contactEmail: "alex@x.io",
+      });
+      const body = JSON.parse(calls[0].init.body);
+      expect(body.arena).toBe("acme:user-42");
+    });
+
+    it("forwards contact_name when supplied (resolves Person by name alias)", async () => {
+      mockOk({ arena: "acme", total: 0, last_seen: null, buckets: [] });
+      await engineAggregate("https://e", {
+        clientId: "acme",
+        contactName: "Alex Tong",
+      });
+      const body = JSON.parse(calls[0].init.body);
+      expect(body.contact_name).toBe("Alex Tong");
+      expect(body).not.toHaveProperty("contact_email");
+    });
+
+    it("forwards both contact_email and contact_name when both supplied", async () => {
+      mockOk({ arena: "acme", total: 0, last_seen: null, buckets: [] });
+      await engineAggregate("https://e", {
+        clientId: "acme",
+        contactEmail: "alex@x.io",
+        contactName: "Alex Tong",
+      });
+      const body = JSON.parse(calls[0].init.body);
+      expect(body.contact_email).toBe("alex@x.io");
+      expect(body.contact_name).toBe("Alex Tong");
+    });
+
+    it("forwards custom group_by when non-empty", async () => {
+      mockOk({ arena: "acme", total: 0, last_seen: null, buckets: [] });
+      await engineAggregate("https://e", {
+        clientId: "acme",
+        contactEmail: "alex@x.io",
+        groupBy: ["channel", "direction"],
+      });
+      const body = JSON.parse(calls[0].init.body);
+      expect(body.group_by).toEqual(["channel", "direction"]);
+    });
+
+    it("defaults group_by to ['channel'] when caller omits it", async () => {
+      mockOk({ arena: "acme", total: 0, last_seen: null, buckets: [] });
+      await engineAggregate("https://e", {
+        clientId: "acme",
+        contactEmail: "alex@x.io",
+      });
+      const body = JSON.parse(calls[0].init.body);
+      expect(body.group_by).toEqual(["channel"]);
+    });
+
+    it("defaults group_by to ['channel'] when caller passes empty array", async () => {
+      // Defensive: TS callers can pass `groupBy: []` to mean "no
+      // grouping" but we treat that as "use the sensible default" so
+      // the default behaviour matches a missing field. The engine
+      // itself is the place that supports empty group_by → single
+      // bucket; expose that explicitly only when the caller asks.
+      mockOk({ arena: "acme", total: 0, last_seen: null, buckets: [] });
+      await engineAggregate("https://e", {
+        clientId: "acme",
+        contactEmail: "alex@x.io",
+        groupBy: [],
+      });
+      const body = JSON.parse(calls[0].init.body);
+      expect(body.group_by).toEqual(["channel"]);
+    });
+
+    it("requires clientId", async () => {
+      await expect(
+        engineAggregate("https://e", { contactEmail: "alex@x.io" })
+      ).rejects.toThrow(/clientId required/);
+    });
+
+    it("requires contactEmail or contactName", async () => {
+      await expect(
+        engineAggregate("https://e", { clientId: "acme" })
+      ).rejects.toThrow(/contactEmail.*contactName/i);
+    });
+
+    it("forwards CF Access headers when supplied", async () => {
+      mockOk({ arena: "acme", total: 0, last_seen: null, buckets: [] });
+      await engineAggregate("https://e", {
+        clientId: "acme",
+        contactEmail: "alex@x.io",
+        headers: {
+          "CF-Access-Client-Id": "id123",
+          "CF-Access-Client-Secret": "sec456",
+        },
+      });
+      expect(calls[0].init.headers["CF-Access-Client-Id"]).toBe("id123");
+      expect(calls[0].init.headers["CF-Access-Client-Secret"]).toBe("sec456");
+    });
+
+    it("returns the engine's response shape unchanged", async () => {
+      const expected = {
+        arena: "acme",
+        total: 47,
+        last_seen: "2026-05-09T09:00:00Z",
+        buckets: [
+          {
+            keys: { channel: "email" },
+            count: 35,
+            inbound: 14,
+            outbound: 21,
+            last_seen: "2026-05-09T09:00:00Z",
+            first_seen: "2025-09-01T08:00:00Z",
+          },
+        ],
+      };
+      mockOk(expected);
+      const out = await engineAggregate("https://e", {
+        clientId: "acme",
+        contactEmail: "alex@x.io",
+      });
+      expect(out).toEqual(expected);
+    });
+  });
+
   describe("engineForget", () => {
     it("forwards id when provided", async () => {
       mockOk({ deleted: 1 });

package/packages/memory/src/engine.js

@@ -281,3 +281,68 @@ export async function engineForget(engineUrl, opts) {
   };
   return fetchEngine(engineUrl, "/forget", body, { headers });
 }
+
+/**
+ * Aggregate communications history about one person from the typed-
+ * Person graph (memory-engine #30 / 0.8.x). Backs ``personFacets``-
+ * style queries: total + per-channel breakdown + last_seen, all
+ * computed by a single Cypher aggregate over
+ * ``(:Person)-[:COMMUNICATED]->(:Chunk)`` edges.
+ *
+ * Caller must supply at least one of ``contactEmail`` or
+ * ``contactName``. ``arena`` is single-valued here (not an arenas
+ * list) — aggregating across arenas isn't a valid operation in a
+ * multi-tenant product, so we don't expose it.
+ *
+ * Returns ``null`` shape: ``{arena, total, last_seen, buckets: [{keys,
+ * count, inbound, outbound, last_seen, first_seen}]}``. ``total: 0``
+ * with empty ``buckets`` when no Person node exists for this contact
+ * in the requested arena (older memories pre-#28, tenants whose data
+ * isn't re-ingested under the new writer yet). The fallback to
+ * over-fetch search lives in TES — this helper is a thin wire bridge.
+ *
+ * @param {string} engineUrl
+ * @param {object} opts
+ * @param {string} opts.clientId
+ * @param {string} [opts.userId]              defaults to tenant-wide arena
+ * @param {string} [opts.contactEmail]
+ * @param {string} [opts.contactName]
+ * @param {string[]} [opts.groupBy=["channel"]]  bucket keys; engine
+ *   whitelists "channel"+"direction" today, unknown keys silently
+ *   dropped.
+ * @param {Record<string,string>} [opts.headers]  forwarded HTTP headers
+ *   (e.g. CF Access service token pair).
+ * @returns {Promise<{
+ *   arena: string,
+ *   total: number,
+ *   last_seen: string|null,
+ *   buckets: Array<{
+ *     keys: Record<string, string|null>,
+ *     count: number,
+ *     inbound: number,
+ *     outbound: number,
+ *     last_seen: string|null,
+ *     first_seen: string|null,
+ *   }>,
+ * }>}
+ */
+export async function engineAggregate(engineUrl, opts) {
+  const { clientId, userId, contactEmail, contactName, groupBy, headers } =
+    opts || {};
+  if (!clientId) throw new Error("engineAggregate: clientId required");
+  if (!contactEmail && !contactName) {
+    throw new Error(
+      "engineAggregate: provide contactEmail and/or contactName",
+    );
+  }
+  // Single-arena: clientId:userId when userId is set, clientId
+  // tenant-wide otherwise. Mirrors composeArenas's first element.
+  const arenas = composeArenas(clientId, userId);
+  const body = {
+    arena: arenas[arenas.length - 1],
+    group_by: groupBy && groupBy.length > 0 ? groupBy : ["channel"],
+    ...(contactEmail ? { contact_email: contactEmail } : {}),
+    ...(contactName ? { contact_name: contactName } : {}),
+  };
+  return fetchEngine(engineUrl, "/aggregate", body, { headers });
+}

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

@@ -125,6 +125,21 @@ class ForgetRequest(BaseModel):
     id: Optional[str] = None
 
 
+class AggregateRequest(BaseModel):
+    """Public-facing /aggregate request.
+
+    Mirrors /aggregate-internal on the L2 proxy with arena scoping
+    enforced at the shim layer (multi-arena spans aren't allowed
+    here — pick a single arena per call). The relationships UI
+    queries this directly via TES; future callers will too.
+    """
+
+    arena: str
+    contact_email: Optional[str] = None
+    contact_name: Optional[str] = None
+    group_by: Optional[list[str]] = None
+
+
 # ----------------------------------------------------------------------
 # Engine clients (one per layer)
 # ----------------------------------------------------------------------
@@ -401,8 +416,14 @@ async def health():
         "engine": "pentatonic-memory-engine",
         "layers": {},
     }
-    # NV-Embed exposes /health alongside /v1/embeddings.
-    nv_embed_health = NV_EMBED_URL.replace("/v1/embeddings", "/health")
+    # NV-Embed (or the upstream gateway) exposes /health at the host root.
+    # Use urlparse so we swap *just* the path component instead of doing a
+    # string replace — that breaks the moment NV_EMBED_URL is /v1/embed,
+    # /v1/embeddings, or bare-host. The probe is informational only; gateways
+    # that return non-200 on root-/health don't block engine operation.
+    from urllib.parse import urlparse, urlunparse
+    _u = urlparse(NV_EMBED_URL)
+    nv_embed_health = urlunparse((_u.scheme, _u.netloc, "/health", "", "", ""))
 
     import asyncio
     l2_v, l4_v, l5_v, l6_v, nv_v, l3_v = await asyncio.gather(
@@ -912,18 +933,88 @@ async def forget(req: ForgetRequest):
     # Also wipe L0 BM25 + L4 QMD + L3 KG so bench resets fully.
     # No per-id forget for these — bench harness uses /forget once at
     # start of each run with empty filters to reset state.
+    #
+    # Three forwarding rules:
+    #   - metadata_contains has `arena`  → tenant-scoped delete (forwards
+    #     the arena to the internal endpoint, which only wipes that
+    #     tenant's L3 data).
+    #   - metadata_contains is set, no arena → targeted L6-only delete;
+    #     do NOT call the internal wipe (we don't have arena scope and
+    #     a global wipe would be wildly wrong here).
+    #   - empty filters → bench-reset semantics; explicitly request the
+    #     unsafe global wipe via the new `confirm: GLOBAL_WIPE` gate.
+    arena_for_internal = None
+    if isinstance(req.metadata_contains, dict):
+        meta_arena = req.metadata_contains.get("arena")
+        if isinstance(meta_arena, str) and meta_arena:
+            arena_for_internal = meta_arena
     try:
-        r = await _client().post(f"{L2_PROXY_URL}/forget-internal",
-                                 json={}, timeout=15.0)
-        if r.status_code == 200:
-            d = r.json().get("deleted", {})
-            deleted_total += sum(int(v or 0) for v in d.values())
+        if arena_for_internal:
+            payload = {"arena": arena_for_internal}
+        elif req.metadata_contains:
+            payload = None  # skip — targeted delete shouldn't wipe shared layers
+        else:
+            payload = {"confirm": "GLOBAL_WIPE"}
+        if payload is not None:
+            r = await _client().post(
+                f"{L2_PROXY_URL}/forget-internal", json=payload, timeout=15.0,
+            )
+            if r.status_code == 200:
+                d = r.json().get("deleted", {})
+                deleted_total += sum(int(v or 0) for v in d.values())
     except Exception as exc:
         print(f"[shim] L2 /forget-internal failed: {exc}")
 
     return {"deleted": deleted_total, "engine": "pentatonic-memory-engine"}
 
 
+@app.post("/aggregate")
+async def aggregate(req: AggregateRequest) -> dict[str, Any]:
+    """Aggregate communications history with one person.
+
+    Pass-through to the L2 proxy's /aggregate-internal which runs a
+    single Cypher query against L3's typed-Person graph
+    ((:Person)-[:COMMUNICATED]->(:Chunk)). Used by TES personFacets
+    once we cut over from the over-fetch v1.
+
+    The shim's job here is shape validation + arena enforcement; the
+    real aggregation lives in L3. No layer fan-out, no metadata
+    filter scanning — when the typed-Person nodes don't exist for
+    this contact (older memories, tenants pre-#28), the response is
+    `total: 0` and the caller falls back to whatever it had before.
+    """
+    arena = (req.arena or "").strip()
+    if not arena:
+        raise HTTPException(status_code=400, detail="arena is required")
+    if not (req.contact_email or req.contact_name):
+        raise HTTPException(
+            status_code=400,
+            detail="provide contact_email and/or contact_name to identify the Person",
+        )
+    payload: dict[str, Any] = {
+        "arena": arena,
+        "group_by": req.group_by or ["channel"],
+    }
+    if req.contact_email:
+        payload["contact_email"] = req.contact_email
+    if req.contact_name:
+        payload["contact_name"] = req.contact_name
+    try:
+        r = await _client().post(
+            f"{L2_PROXY_URL}/aggregate-internal", json=payload, timeout=15.0,
+        )
+        if r.status_code != 200:
+            raise HTTPException(
+                status_code=r.status_code,
+                detail=f"aggregate failed: {r.text[:200]}",
+            )
+        return r.json()
+    except HTTPException:
+        raise
+    except Exception as exc:
+        raise HTTPException(status_code=502, detail=f"aggregate upstream: {exc}")
+
+
 # ----------------------------------------------------------------------
 # Entrypoint
 # ----------------------------------------------------------------------