@pentatonic-ai/ai-agent-sdk 0.7.10 → 0.7.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pentatonic-ai/ai-agent-sdk",
-  "version": "0.7.10",
+  "version": "0.7.12",
   "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/src/__tests__/engine.test.js

@@ -4,6 +4,8 @@ import {
   engineStore,
   engineSearch,
   engineForget,
+  composeArena,
+  composeArenas,
   DEFAULT_ENGINE_URL,
 } from "../engine.js";
 
@@ -82,7 +84,7 @@ describe("engine HTTP client", () => {
   });
 
   describe("engineStore", () => {
-    it("builds canonical /store body with arena=clientId", async () => {
+    it("tenant-wide by default when no userId", async () => {
       mockOk({ id: "abc", content: "hello", layerId: "ml_acme_episodic" });
       await engineStore("https://e", {
         clientId: "acme",
@@ -104,6 +106,39 @@ describe("engine HTTP client", () => {
       });
     });
 
+    it("user-scoped by default when userId provided", async () => {
+      mockOk({ id: "x", content: "x", layerId: "ml_acme_episodic" });
+      await engineStore("https://e", {
+        clientId: "acme",
+        userId: "user-42",
+        content: "x",
+      });
+      const body = JSON.parse(calls[0].init.body);
+      expect(body.metadata.arena).toBe("acme:user-42");
+    });
+
+    it("scope=tenant overrides user-scoped default", async () => {
+      mockOk({ id: "x", content: "x", layerId: "ml_acme_episodic" });
+      await engineStore("https://e", {
+        clientId: "acme",
+        userId: "user-42",
+        scope: "tenant",
+        content: "x",
+      });
+      const body = JSON.parse(calls[0].init.body);
+      expect(body.metadata.arena).toBe("acme");
+    });
+
+    it("scope=user without userId throws", async () => {
+      await expect(
+        engineStore("https://e", {
+          clientId: "acme",
+          scope: "user",
+          content: "x",
+        })
+      ).rejects.toThrow(/scope=user requires userId/);
+    });
+
     it("omits layer_type and actor_user_id when not provided", async () => {
       mockOk({ id: "x", content: "x", layerId: "ml_acme_episodic" });
       await engineStore("https://e", { clientId: "acme", content: "x" });
@@ -116,7 +151,6 @@ describe("engine HTTP client", () => {
       await engineStore("https://e", {
         clientId: "acme",
         content: "x",
-        // attempted hostile arena spoof:
         metadata: { arena: "tenant-b" },
       });
       const body = JSON.parse(calls[0].init.body);
@@ -135,7 +169,7 @@ describe("engine HTTP client", () => {
   });
 
   describe("engineSearch", () => {
-    it("builds canonical /search body and forwards arena/limit/min_score", async () => {
+    it("tenant-only arenas list when no userId", async () => {
       mockOk({ results: [] });
       await engineSearch("https://e", {
         clientId: "acme",
@@ -147,12 +181,26 @@ describe("engine HTTP client", () => {
       expect(calls[0].url).toBe("https://e/search");
       expect(body).toEqual({
         arena: "acme",
+        arenas: ["acme"],
         query: "hello",
         limit: 5,
         min_score: 0.5,
       });
     });
 
+    it("tenant + user-scope arenas list when userId provided", async () => {
+      mockOk({ results: [] });
+      await engineSearch("https://e", {
+        clientId: "acme",
+        userId: "user-42",
+        query: "hi",
+      });
+      const body = JSON.parse(calls[0].init.body);
+      expect(body.arenas).toEqual(["acme", "acme:user-42"]);
+      // single-arena field kept for back-compat — points at tenant-wide
+      expect(body.arena).toBe("acme");
+    });
+
     it("includes metadata_filter only when non-empty", async () => {
       mockOk({ results: [] });
       await engineSearch("https://e", {
@@ -183,6 +231,90 @@ describe("engine HTTP client", () => {
     });
   });
 
+  describe("opts.headers passthrough (CF Access)", () => {
+    const cfAccess = {
+      "CF-Access-Client-Id": "tes-worker.id",
+      "CF-Access-Client-Secret": "shh-it-secret",
+    };
+
+    it("fetchEngine merges opts.headers on top of the default content-type", async () => {
+      mockOk({});
+      await fetchEngine("https://e", "/store", { a: 1 }, { headers: cfAccess });
+      const sent = calls[0].init.headers;
+      expect(sent["content-type"]).toBe("application/json");
+      expect(sent["CF-Access-Client-Id"]).toBe("tes-worker.id");
+      expect(sent["CF-Access-Client-Secret"]).toBe("shh-it-secret");
+    });
+
+    it("engineStore forwards opts.headers", async () => {
+      mockOk({ id: "x", content: "x", layerId: "ml_acme_episodic" });
+      await engineStore("https://e", {
+        clientId: "acme",
+        content: "x",
+        headers: cfAccess,
+      });
+      const sent = calls[0].init.headers;
+      expect(sent["CF-Access-Client-Id"]).toBe("tes-worker.id");
+    });
+
+    it("engineSearch forwards opts.headers", async () => {
+      mockOk({ results: [] });
+      await engineSearch("https://e", {
+        clientId: "acme",
+        query: "x",
+        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("engineForget forwards opts.headers", async () => {
+      mockOk({ deleted: 0 });
+      await engineForget("https://e", {
+        clientId: "acme",
+        id: "abc",
+        headers: cfAccess,
+      });
+      const sent = calls[0].init.headers;
+      expect(sent["CF-Access-Client-Id"]).toBe("tes-worker.id");
+    });
+
+    it("no headers sent when opts.headers omitted (back-compat)", async () => {
+      mockOk({});
+      await engineStore("https://e", { clientId: "acme", content: "x" });
+      const sent = calls[0].init.headers;
+      expect(Object.keys(sent)).toEqual(["content-type"]);
+    });
+  });
+
+  describe("composeArena", () => {
+    it("tenant scope by default when no userId", () => {
+      expect(composeArena("acme")).toBe("acme");
+    });
+    it("user scope by default when userId present", () => {
+      expect(composeArena("acme", "u-1")).toBe("acme:u-1");
+    });
+    it("explicit scope=tenant overrides", () => {
+      expect(composeArena("acme", "u-1", "tenant")).toBe("acme");
+    });
+    it("scope=user without userId throws", () => {
+      expect(() => composeArena("acme", null, "user")).toThrow(/userId/);
+    });
+    it("missing clientId throws", () => {
+      expect(() => composeArena("")).toThrow(/clientId/);
+    });
+  });
+
+  describe("composeArenas", () => {
+    it("tenant only when no userId", () => {
+      expect(composeArenas("acme")).toEqual(["acme"]);
+    });
+    it("tenant + user-scope when userId present", () => {
+      expect(composeArenas("acme", "u-1")).toEqual(["acme", "acme:u-1"]);
+    });
+  });
+
   describe("engineForget", () => {
     it("forwards id when provided", async () => {
       mockOk({ deleted: 1 });

package/packages/memory/src/corpus/adapters.js

@@ -308,6 +308,11 @@ export function hostedAdapter(config, opts = {}) {
  * @param {string} config.engineUrl - e.g. "http://localhost:8099"
  * @param {string} [config.arena] - tenant scope; defaults to "default"
  * @param {string} [config.apiKey] - optional Authorization: Bearer
+ * @param {string} [config.cfAccessClientId] - CF Access service token id;
+ *   sent as `CF-Access-Client-Id` when the engine is locked behind a
+ *   Cloudflare Access policy.
+ * @param {string} [config.cfAccessClientSecret] - paired secret; sent as
+ *   `CF-Access-Client-Secret`.
  * @param {object} [opts]
  * @param {number} [opts.timeoutMs=30000]
  * @returns {{ingestChunk, deleteByCorpusFile, init}}
@@ -319,11 +324,15 @@ export function engineAdapter(config, opts = {}) {
   }
   const arena = config.arena || "default";
   const apiKey = config.apiKey || null;
+  const cfAccessId = config.cfAccessClientId || null;
+  const cfAccessSecret = config.cfAccessClientSecret || null;
   const timeoutMs = opts.timeoutMs ?? 30000;
 
   function headers() {
     const h = { "content-type": "application/json" };
     if (apiKey) h["authorization"] = `Bearer ${apiKey}`;
+    if (cfAccessId) h["CF-Access-Client-Id"] = cfAccessId;
+    if (cfAccessSecret) h["CF-Access-Client-Secret"] = cfAccessSecret;
     return h;
   }
 

package/packages/memory/src/corpus/cli.js

@@ -99,6 +99,13 @@ function readPluginConfig() {
 }
 
 function buildAdapterOrFail() {
+  // CF Access service token (optional). When the engine domain is
+  // locked behind a CF Access policy, callers need these headers or
+  // the edge returns 403 before traffic reaches the tunnel. Env-var
+  // names match the canonical Cloudflare Access convention.
+  const cfAccessClientId = process.env.CF_ACCESS_CLIENT_ID || null;
+  const cfAccessClientSecret = process.env.CF_ACCESS_CLIENT_SECRET || null;
+
   // 1. Env-var override (CI / scripts / explicit). Highest precedence.
   const envEngineUrl =
     process.env.MEMORY_ENGINE_URL || process.env.PENTATONIC_ENGINE_URL || null;
@@ -114,6 +121,8 @@ function buildAdapterOrFail() {
         engineUrl: envEngineUrl,
         arena,
         apiKey: process.env.MEMORY_ENGINE_API_KEY || null,
+        cfAccessClientId,
+        cfAccessClientSecret,
       }),
     };
   }
@@ -124,7 +133,12 @@ function buildAdapterOrFail() {
     const arena = pluginConfig.client_id || "default";
     return {
       tenant: { source: `plugin-config (${pluginConfig._path})`, engineUrl: pluginConfig.memory_url, arena },
-      adapter: engineAdapter({ engineUrl: pluginConfig.memory_url, arena }),
+      adapter: engineAdapter({
+        engineUrl: pluginConfig.memory_url,
+        arena,
+        cfAccessClientId,
+        cfAccessClientSecret,
+      }),
     };
   }
 

package/packages/memory/src/engine.js

@@ -67,19 +67,31 @@ export const DEFAULT_MIN_SCORE = 0.3;
  * @param {string} engineUrl - engine base URL (no trailing slash)
  * @param {string} path      - "/store" | "/search" | "/forget" | "/health" | "/store-batch"
  * @param {object} body      - JSON body, serialised verbatim
+ * @param {object} [opts]
+ * @param {Record<string,string>} [opts.headers] - additional request
+ *   headers; merged on top of the default `content-type`. Canonical
+ *   use case is Cloudflare Access service tokens
+ *   (`CF-Access-Client-Id` + `CF-Access-Client-Secret`) when the
+ *   engine domain is locked behind a CF Access policy. Any auth
+ *   scheme can flow through this — the helper makes no assumptions
+ *   about header names.
  * @returns {Promise<object>} parsed JSON response
  * @throws {Error} - "engine_<status>" with `.detail` set to response text
  *                   on HTTP non-2xx, or "engine_network: <msg>" on
  *                   transport failure.
  */
-export async function fetchEngine(engineUrl, path, body) {
+export async function fetchEngine(engineUrl, path, body, opts = {}) {
   const base = engineUrl || DEFAULT_ENGINE_URL;
   const url = `${base}${path}`;
+  // Default content-type first so callers can override it via opts.headers
+  // if they ever need to (none do today, but the spread makes the rule
+  // explicit: caller wins on conflict).
+  const headers = { "content-type": "application/json", ...(opts.headers || {}) };
   let res;
   try {
     res = await fetch(url, {
       method: "POST",
-      headers: { "content-type": "application/json" },
+      headers,
       body: JSON.stringify(body),
     });
   } catch (err) {
@@ -99,68 +111,139 @@ export async function fetchEngine(engineUrl, path, body) {
   return res.json();
 }
 
+/**
+ * Compose the engine arena for a (clientId, userId, scope) triple.
+ *
+ *   tenant scope: clientId            (e.g. "acme")
+ *   user scope:   clientId + ":" + userId  (e.g. "acme:user-42")
+ *
+ * Default scope: "user" when userId is supplied, "tenant" otherwise.
+ * Multi-tenant search composes arena lists from this same vocabulary.
+ *
+ * @param {string} clientId
+ * @param {string|null|undefined} userId
+ * @param {"tenant"|"user"} [scope]
+ * @returns {string} the arena value to stamp on /store metadata
+ */
+export function composeArena(clientId, userId, scope) {
+  if (!clientId) throw new Error("composeArena: clientId required");
+  const effectiveScope = scope || (userId ? "user" : "tenant");
+  if (effectiveScope === "user") {
+    if (!userId) throw new Error("composeArena: scope=user requires userId");
+    return `${clientId}:${userId}`;
+  }
+  return clientId;
+}
+
+/**
+ * Compose the arenas list a search should span for a given user.
+ *
+ *   no userId: [clientId]                                (tenant-wide only)
+ *   with userId: [clientId, clientId + ":" + userId]    (tenant-wide + own user-scope)
+ *
+ * Order is informational; the engine treats it as a set. Callers passing
+ * `userId` get visibility into both their own user-scoped memories and
+ * the shared tenant-wide memories — never another user's user-scoped data.
+ *
+ * @param {string} clientId
+ * @param {string|null|undefined} userId
+ * @returns {string[]}
+ */
+export function composeArenas(clientId, userId) {
+  if (!clientId) throw new Error("composeArenas: clientId required");
+  return userId ? [clientId, `${clientId}:${userId}`] : [clientId];
+}
+
 /**
  * Store a single memory in the engine.
  *
- * Builds the canonical /store body: `arena = clientId` is set on
- * metadata so the engine's multi-tenant scoping works. Caller-supplied
- * metadata fields take precedence on conflict.
+ * Builds the canonical /store body. By default the row is **user-scoped**
+ * (`arena = clientId:userId`) when `userId` is supplied, otherwise
+ * **tenant-wide** (`arena = clientId`). Pass `scope: "tenant"` explicitly
+ * to write a shared row from a user-context (e.g. a super-admin uploading
+ * a doc that should be visible to every user in the tenant).
+ *
+ * The arena value is fixed by the SDK after the caller's metadata, so a
+ * resolver can't be tricked into spoofing arena via metadata.
  *
  * @param {string} engineUrl
  * @param {object} opts
- * @param {string} opts.clientId      tenant id (becomes engine arena)
- * @param {string} opts.content
- * @param {object} [opts.metadata]    extra metadata; merged into engine body
- * @param {string} [opts.layerType]   "episodic" | "semantic" | "procedural" | "working"
- * @param {string} [opts.actorUserId] passes through as metadata.actor_user_id
+ * @param {string}  opts.clientId      tenant id
+ * @param {string}  [opts.userId]      user id within the tenant; controls default scope
+ * @param {"tenant"|"user"} [opts.scope]  override the default scope. "user" requires userId.
+ * @param {string}  opts.content
+ * @param {object}  [opts.metadata]    extra metadata; merged into engine body
+ * @param {string}  [opts.layerType]   "episodic" | "semantic" | "procedural" | "working"
+ * @param {string}  [opts.actorUserId] passes through as metadata.actor_user_id
+ * @param {Record<string,string>} [opts.headers]  forwarded HTTP headers
+ *   (e.g. CF Access service token pair when the engine domain is
+ *   locked behind a Cloudflare Access policy).
  * @returns {Promise<EngineStoreResult>}
  */
 export async function engineStore(engineUrl, opts) {
   const {
     clientId,
+    userId,
+    scope,
     content,
     metadata = {},
     layerType,
     actorUserId,
+    headers,
   } = opts || {};
   if (!clientId) throw new Error("engineStore: clientId required");
   if (typeof content !== "string") throw new Error("engineStore: content required");
+  const arena = composeArena(clientId, userId, scope);
   const body = {
     content,
     metadata: {
       ...metadata,
-      arena: clientId,
+      arena,
       ...(layerType ? { layer_type: layerType } : {}),
       ...(actorUserId !== undefined ? { actor_user_id: actorUserId } : {}),
     },
   };
-  return fetchEngine(engineUrl, "/store", body);
+  return fetchEngine(engineUrl, "/store", body, { headers });
 }
 
 /**
  * Search the engine, scoped to a tenant.
  *
+ * When `userId` is supplied the search spans **both** the tenant-wide
+ * arena (`clientId`) and the user's own scope (`clientId:userId`) — so a
+ * caller sees their own memories plus shared tenant memories, never
+ * another user's. Without `userId` the search is tenant-wide only.
+ *
  * @param {string} engineUrl
  * @param {object} opts
- * @param {string} opts.clientId
- * @param {string} opts.query
- * @param {number} [opts.limit=10]
- * @param {number} [opts.minScore=0.3]
- * @param {object} [opts.metadataFilter]  arbitrary equality filter on result metadata
+ * @param {string}   opts.clientId
+ * @param {string}   [opts.userId]
+ * @param {string}   opts.query
+ * @param {number}   [opts.limit=10]
+ * @param {number}   [opts.minScore=0.3]
+ * @param {object}   [opts.metadataFilter]  arbitrary equality filter on result metadata
+ * @param {Record<string,string>} [opts.headers]  forwarded HTTP headers
+ *   (e.g. CF Access service token pair).
  * @returns {Promise<{results: EngineSearchHit[]}>}
  */
 export async function engineSearch(engineUrl, opts) {
   const {
     clientId,
+    userId,
     query,
     limit = DEFAULT_LIMIT,
     minScore = DEFAULT_MIN_SCORE,
     metadataFilter,
+    headers,
   } = opts || {};
   if (!clientId) throw new Error("engineSearch: clientId required");
   if (typeof query !== "string") throw new Error("engineSearch: query required");
+  const arenas = composeArenas(clientId, userId);
   const body = {
-    arena: clientId,
+    arenas,
+    // Single-arena field kept for callers / engines that haven't been
+    // upgraded to the arenas-list shape. The list is authoritative.
+    arena: arenas[0],
     query,
     limit,
     min_score: minScore,
@@ -168,7 +251,7 @@ export async function engineSearch(engineUrl, opts) {
       ? { metadata_filter: metadataFilter }
       : {}),
   };
-  return fetchEngine(engineUrl, "/search", body);
+  return fetchEngine(engineUrl, "/search", body, { headers });
 }
 
 /**
@@ -181,10 +264,12 @@ export async function engineSearch(engineUrl, opts) {
  * @param {string} opts.clientId
  * @param {string} [opts.id]                forget a single record by engine id
  * @param {object} [opts.metadataContains]  forget all records matching every key=value pair
+ * @param {Record<string,string>} [opts.headers]  forwarded HTTP headers
+ *   (e.g. CF Access service token pair).
  * @returns {Promise<{deleted: number}>}
  */
 export async function engineForget(engineUrl, opts) {
-  const { clientId, id, metadataContains } = opts || {};
+  const { clientId, id, metadataContains, headers } = opts || {};
   if (!clientId) throw new Error("engineForget: clientId required");
   if (!id && !metadataContains) {
     throw new Error("engineForget: provide id or metadataContains");
@@ -194,5 +279,5 @@ export async function engineForget(engineUrl, opts) {
     ...(id ? { id } : {}),
     ...(metadataContains ? { metadata_contains: metadataContains } : {}),
   };
-  return fetchEngine(engineUrl, "/forget", body);
+  return fetchEngine(engineUrl, "/forget", body, { headers });
 }

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

@@ -102,12 +102,15 @@ class SearchRequest(BaseModel):
     query: str
     limit: Optional[int] = 10
     min_score: Optional[float] = 0.001
-    # Tenant scope. Required for multi-tenant deployments. Forwarded to
-    # layers that support arena filtering natively (L6); applied as a
-    # post-filter on the shim for layers that don't yet (L2, L4, L5).
-    # When unset, search is global — same behaviour as v0.7.x; safe for
-    # single-tenant deployments. Multi-tenant callers MUST set this.
+    # Tenant scope (single arena). Back-compat shape — single-arena callers
+    # can keep sending this. Treated as a one-element `arenas` list.
     arena: Optional[str] = None
+    # Multi-arena scope. Used by callers that want to span both a tenant-
+    # wide arena ("acme") and a user-scoped arena ("acme:user-42") in one
+    # search — the SDK helper composes this list automatically when a
+    # `userId` is supplied. Authoritative when both `arena` and `arenas`
+    # are present; engine treats it as a set.
+    arenas: Optional[list[str]] = None
     # Arbitrary metadata equality filters, applied as a post-filter on
     # the shim. Useful for `kind`, `layer_type`, `source_repo`, etc.
     # Keys not present on a result's metadata are treated as no-match.
@@ -545,29 +548,49 @@ async def store_batch(req: StoreBatchRequest):
     }
 
 
+def _arenas_for(req: SearchRequest) -> list[str]:
+    """Normalize req's single-arena + multi-arena fields into one list.
+
+    `arenas` is authoritative when set; otherwise `arena` is treated as
+    a one-element list; otherwise empty (= search is unscoped, dev/test).
+    """
+    if req.arenas:
+        return [a for a in req.arenas if a]
+    if req.arena:
+        return [req.arena]
+    return []
+
+
 def _apply_metadata_filters(results: list[dict[str, Any]], req: SearchRequest) -> list[dict[str, Any]]:
-    """Post-filter results by arena + arbitrary metadata equality.
+    """Post-filter results by arena set + arbitrary metadata equality.
 
     Many layer searches don't yet honour arena/metadata at the storage
     level, so the shim enforces tenant isolation here as defence in
     depth. Even if the underlying layer leaks across arenas, the shim
-    drops cross-tenant rows before returning.
+    drops cross-arena rows before returning.
+
+    Multi-arena rule: a row passes if its arena tag is in the request's
+    arena set. So a user-scoped search (arenas=[acme, acme:u-42]) sees
+    both tenant-wide rows (arena=acme) and that user's own user-scoped
+    rows (arena=acme:u-42), but never another user's user-scoped rows
+    (arena=acme:u-99).
     """
-    arena = req.arena
+    arenas = _arenas_for(req)
     extra = req.metadata_filter or {}
-    if not arena and not extra:
+    if not arenas and not extra:
         return results
+    arena_set = set(arenas)
     out: list[dict[str, Any]] = []
     for item in results:
         meta = item.get("metadata") or {}
-        if arena:
+        if arena_set:
             row_arena = meta.get("arena") or item.get("arena")
-            if row_arena and row_arena != arena:
+            if row_arena and row_arena not in arena_set:
                 continue
             # If row has no arena tag at all, drop on multi-tenant
             # safety: a row without arena predates the multi-tenant
             # plumbing and could belong to anyone.
-            if arena and not row_arena:
+            if not row_arena:
                 continue
         ok = True
         for k, v in extra.items():
@@ -587,7 +610,7 @@ def _search_overfetch(req: SearchRequest) -> int:
     between accuracy and latency.
     """
     base = req.limit or 10
-    return base * 5 if (req.arena or req.metadata_filter) else base * 3
+    return base * 5 if (_arenas_for(req) or req.metadata_filter) else base * 3
 
 
 @app.post("/search")
@@ -624,16 +647,17 @@ async def search(req: SearchRequest):
         import asyncio
         async def _q_l6(query: str):
             try:
-                params: dict[str, Any] = {
-                    "q": query,
-                    "limit": _search_overfetch(req),
-                    "method": "hybrid",
-                }
-                if req.arena:
-                    # L6 supports arena natively (l6-document-store.py:837).
-                    # Forward it so the underlying Milvus query and FTS
-                    # query both filter to this tenant before returning.
-                    params["arena"] = req.arena
+                params: list = [
+                    ("q", query),
+                    ("limit", str(_search_overfetch(req))),
+                    ("method", "hybrid"),
+                ]
+                # L6 supports arena natively (l6-document-store.py).
+                # Forward all arenas in the search scope; L6 expands the
+                # filter to `arena IN (...)`. Multiple `arenas` query
+                # params on the wire = list-shaped server side.
+                for a in _arenas_for(req):
+                    params.append(("arenas", a))
                 r = await _client().get(
                     f"{L6_DOC_URL}/search",
                     params=params,
@@ -741,10 +765,14 @@ async def search(req: SearchRequest):
         # then trim to the requested limit.
         out_results = _apply_metadata_filters(out_results, req)
         return {"results": out_results[: req.limit or 10]}
+    arenas = _arenas_for(req)
     try:
-        get_params: dict[str, Any] = {"q": req.query, "limit": _search_overfetch(req)}
-        if req.arena:
-            get_params["arena"] = req.arena
+        get_params: list = [
+            ("q", req.query),
+            ("limit", str(_search_overfetch(req))),
+        ]
+        for a in arenas:
+            get_params.append(("arenas", a))
         r = await _client().get(
             f"{L2_PROXY_URL}/search",
             params=get_params,
@@ -760,8 +788,8 @@ async def search(req: SearchRequest):
                 "limit": _search_overfetch(req),
                 "min_score": req.min_score or 0.001,
             }
-            if req.arena:
-                post_body["arena"] = req.arena
+            if arenas:
+                post_body["arenas"] = arenas
             r = await _client().post(
                 f"{L2_PROXY_URL}/v1/search",
                 json=post_body,
@@ -772,11 +800,14 @@ async def search(req: SearchRequest):
         except Exception as exc2:
             last_err = exc2
             try:
-                params: dict[str, Any] = {"q": req.query, "limit": _search_overfetch(req)}
-                # L6 supports arena natively; forward it on the
-                # last-resort fallback path too.
-                if req.arena:
-                    params["arena"] = req.arena
+                params: list = [
+                    ("q", req.query),
+                    ("limit", str(_search_overfetch(req))),
+                ]
+                # L6 supports arena natively; forward all in the search
+                # scope on the last-resort fallback path too.
+                for a in arenas:
+                    params.append(("arenas", a))
                 r = await _client().get(
                     f"{L6_DOC_URL}/search",
                     params=params,

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

@@ -719,17 +719,18 @@ L0_MEMORY_DB = Path(os.environ.get(
     str(Path.home() / ".pentatonic" / "memory" / "main.sqlite"),
 ))
 
-def search_l0_bm25(query: str, limit: int = 6, arena: str = None) -> List[Dict]:
+def search_l0_bm25(query: str, limit: int = 6, arena: str = None,
+                   arenas: List[str] = None) -> List[Dict]:
     """Search native BM25 index over workspace memory files.
 
     Covers chunks from daily notes, memory files, people profiles,
     infrastructure docs, project files — corpus that L3-L6 don't index.
     Sub-millisecond local SQLite reads, zero network overhead.
 
-    arena (optional): when set, filter to paths under bench/<arena>/.
-    Records stored via the compat shim land under that prefix per
-    _stash_all_keys; this is the L0 path-based equivalent of the
-    arena dynamic-field filter on L5/L6.
+    arena / arenas: when set, filter to paths under bench/<arena>/.
+    Multi-arena queries (e.g. tenant-wide + user-scoped in one search)
+    use OR'd path-prefix LIKE clauses. `arenas` wins when both are
+    supplied; `arena` is treated as a one-element list for back-compat.
     """
     if not L0_MEMORY_DB.exists():
         return []
@@ -744,6 +745,9 @@ def search_l0_bm25(query: str, limit: int = 6, arena: str = None) -> List[Dict]:
             return []
         fts_query = " OR ".join(f'"{t}"' for t in meaningful)
 
+        # Normalize single+multi arena inputs into one list.
+        arena_list = list(arenas) if arenas else ([arena] if arena else [])
+
         conn = sqlite3.connect(str(L0_MEMORY_DB), timeout=2)
         conn.execute("PRAGMA journal_mode=WAL")
         sql = """
@@ -755,9 +759,10 @@ def search_l0_bm25(query: str, limit: int = 6, arena: str = None) -> List[Dict]:
               AND path NOT LIKE '%-backup-%'
         """
         params: list = [fts_query]
-        if arena:
-            sql += " AND path LIKE ?"
-            params.append(f"bench/{arena}/%")
+        if arena_list:
+            clauses = " OR ".join(["path LIKE ?"] * len(arena_list))
+            sql += f" AND ({clauses})"
+            params.extend([f"bench/{a}/%" for a in arena_list])
         sql += " ORDER BY rank ASC LIMIT ?"
         params.append(limit * 2)
         rows = conn.execute(sql, params).fetchall()
@@ -800,17 +805,21 @@ def search_l0_bm25(query: str, limit: int = 6, arena: str = None) -> List[Dict]:
 
 L5_API_URL = os.environ.get("PME_L5_URL", "http://127.0.0.1:8034")
 
-def search_l5_communications(query: str, limit: int = 6, arena: str = None) -> List[Dict]:
+def search_l5_communications(query: str, limit: int = 6, arena: str = None,
+                             arenas: List[str] = None) -> List[Dict]:
     """Search L5 Communications Context via L5 API (emails, chats, calendar).
 
-    arena (optional): forwarded to L5; filters Milvus by the arena
-    dynamic field. Records id is included in the result so callers
-    can attach metadata via the shim's _META_CACHE.
+    arena / arenas (optional): forwarded to L5; filters Milvus by the
+    arena dynamic field. Multi-arena calls become a Milvus
+    `arena IN ["X","Y"]` filter expression on the L5 side.
     """
     try:
-        params: dict = {"q": query, "limit": limit}
-        if arena:
-            params["arena"] = arena
+        # Build a list of (key, value) tuples so multi-valued query
+        # params (?arenas=A&arenas=B) wire-shape correctly.
+        arena_list = list(arenas) if arenas else ([arena] if arena else [])
+        params: list = [("q", query), ("limit", str(limit))]
+        for a in arena_list:
+            params.append(("arenas", a))
         resp = requests.get(
             f"{L5_API_URL}/search",
             params=params,
@@ -857,16 +866,23 @@ def search_l5_communications(query: str, limit: int = 6, arena: str = None) -> L
 # L6: Document Store Search
 L6_URL = os.environ.get("PME_L6_URL", "http://localhost:8037")
 
-def search_l6_documents(query: str, limit: int = 6, arena: str = None) -> List[Dict]:
+def search_l6_documents(query: str, limit: int = 6, arena: str = None,
+                        arenas: List[str] = None) -> List[Dict]:
     """Search L6 Document Store (research, legal, financial, project docs).
 
-    arena (optional): forwarded to L6 — L6 already supports arena
+    arena / arenas (optional): forwarded to L6 — L6 supports multi-arena
     natively (see l6-document-store.py search_vector / search_fts).
     """
     try:
-        params: dict = {"q": query, "method": "hybrid", "limit": limit, "rerank": "true"}
-        if arena:
-            params["arena"] = arena
+        arena_list = list(arenas) if arenas else ([arena] if arena else [])
+        params: list = [
+            ("q", query),
+            ("method", "hybrid"),
+            ("limit", str(limit)),
+            ("rerank", "true"),
+        ]
+        for a in arena_list:
+            params.append(("arenas", a))
         resp = requests.get(
             f"{L6_URL}/search",
             params=params,
@@ -914,19 +930,22 @@ def search_l6_documents(query: str, limit: int = 6, arena: str = None) -> List[D
         return []
 
 
-def sequential_hybridrag_search(query: str, limit: int = 16, arena: str = None) -> List[Dict]:
+def sequential_hybridrag_search(query: str, limit: int = 16,
+                                arena: str = None,
+                                arenas: List[str] = None) -> List[Dict]:
     """Main HybridRAG processing: L0 BM25 → L1 System Files → L2 HybridRAG (L3 Graph + L4 Vector + L5 Comms + L6 Docs).
 
-    arena (optional): tenant scope. Forwarded to L0 (path-prefix
-    filter), L5 (Milvus dynamic-field filter), L6 (native arena).
-    L4 vector and L3 graph don't yet support native arena filtering;
-    the compat shim post-filter catches those before they leak out.
+    arena / arenas (optional): tenant + user scope. Multi-arena lets a
+    user's search span tenant-wide rows + their own user-scoped rows in
+    a single hybrid pass. Forwarded to L0, L5, L6 native filters; L4
+    and L3 still rely on the compat shim post-filter.
     """
+    arena_list = list(arenas) if arenas else ([arena] if arena else [])
     start_time = time.time()
-    log.info(f"Starting sequential HybridRAG search for: '{query}' arena={arena!r}")
+    log.info(f"Starting sequential HybridRAG search for: '{query}' arenas={arena_list!r}")
 
     # L0: BM25 workspace memory (keyword search — complements semantic layers)
-    l0_results = search_l0_bm25(query, limit=6, arena=arena)
+    l0_results = search_l0_bm25(query, limit=6, arenas=arena_list)
     log.info(f"L0 BM25 workspace: {len(l0_results)} results")
 
     # L1: System Files (HIGHEST PRIORITY)
@@ -947,11 +966,11 @@ def sequential_hybridrag_search(query: str, limit: int = 16, arena: str = None)
     log.info(f"L4 Vector search: {len(vector_results)} results (HyDE={'on' if hyde_query != query else 'off'})")
 
     # L5: Communications Context (emails, chats, calendar) — also use HyDE
-    l5_results = search_l5_communications(hyde_query, limit=6, arena=arena)
+    l5_results = search_l5_communications(hyde_query, limit=6, arenas=arena_list)
     log.info(f"L5 Communications: {len(l5_results)} results")
 
     # L6: Document Store (research, legal, financial, project docs)
-    l6_results = search_l6_documents(hyde_query, limit=6, arena=arena)
+    l6_results = search_l6_documents(hyde_query, limit=6, arenas=arena_list)
     log.info(f"L6 Documents: {len(l6_results)} results")
 
     # L2: HybridRAG fusion (combines all layers with L1 priority)
@@ -1012,10 +1031,11 @@ async def search_endpoint(request: Request) -> dict:
         query = body.get("query", "")
         limit = body.get("limit", 16)
         arena = body.get("arena") or None
+        arenas = body.get("arenas") or None
         if not query:
             raise HTTPException(status_code=400, detail="query is required")
 
-        results = sequential_hybridrag_search(query, limit=limit, arena=arena)
+        results = sequential_hybridrag_search(query, limit=limit, arena=arena, arenas=arenas)
 
         # Also return raw graph entities for context enrichment
         entities = extract_query_entities(query)

package/packages/memory-engine/engine/services/l5/l5-comms-layer.py

@@ -449,12 +449,15 @@ def index_memory(client):
 
 # --- Search ---
 
-def search(query: str, collection: str = None, limit: int = 10, arena: str = None):
+def search(query: str, collection: str = None, limit: int = 10,
+           arena: str = None, arenas=None):
     """Search across collections.
 
-    arena (optional): when set, filter to records whose arena dynamic
-    field matches. Records indexed before arena was added carry no
-    arena field — those are dropped under multi-tenant safety.
+    arena / arenas (optional): when set, filter rows whose `arena`
+    dynamic field matches. Multi-arena uses Milvus `in [...]` so a
+    single-pass user-scoped search (tenant + own user) returns rows
+    from both buckets. Records without an arena tag are dropped under
+    multi-tenant safety.
     """
     client = get_client()
     vectors = embed_texts([query])
@@ -465,11 +468,20 @@ def search(query: str, collection: str = None, limit: int = 10, arena: str = Non
     collections = [collection] if collection else ["chats", "emails", "contacts", "memory"]
     all_results = []
 
+    # Normalize arenas list and build the Milvus filter expression.
+    if arenas is None:
+        arena_list = [arena] if arena else []
+    else:
+        arena_list = [a for a in arenas if a]
     filter_expr = ""
-    if arena:
-        # Escape double quotes; Milvus filter syntax for dynamic fields.
-        safe = str(arena).replace('"', '\\"')
+    if len(arena_list) == 1:
+        safe = str(arena_list[0]).replace('"', '\\"')
         filter_expr = f'arena == "{safe}"'
+    elif len(arena_list) > 1:
+        quoted = ", ".join(
+            '"{}"'.format(str(a).replace('"', '\\"')) for a in arena_list
+        )
+        filter_expr = f'arena in [{quoted}]'
 
     for coll in collections:
         if not client.has_collection(coll):
@@ -562,8 +574,12 @@ def serve(port=8034):
 
     @api.get("/search")
     def api_search(q: str = Query(...), collection: str = None, limit: int = 10,
-                   arena: str = None):
-        results = search(q, collection=collection, limit=limit, arena=arena)
+                   arena: str = None, arenas: list = Query(default=[])):
+        # `arenas` (repeated query param) wins when both are present.
+        results = search(
+            q, collection=collection, limit=limit,
+            arena=arena, arenas=arenas or None,
+        )
         return {"query": q, "results": results, "count": len(results)}
 
     @api.get("/stats")

package/packages/memory-engine/engine/services/l6/l6-document-store.py

@@ -303,9 +303,25 @@ def get_milvus() -> MilvusClient:
 
 
 def search_vector(client: MilvusClient, query_vec: List[float], limit: int = 20,
-                  arena: Optional[str] = None) -> List[Dict]:
-    """Vector similarity search."""
-    filter_expr = f'arena == "{arena}"' if arena else ""
+                  arena: Optional[str] = None,
+                  arenas: Optional[List[str]] = None) -> List[Dict]:
+    """Vector similarity search.
+
+    Multi-arena: pass `arenas=[...]` to span more than one tenant scope
+    (e.g. tenant-wide + a single user-scope). Builds an `arena IN [...]`
+    Milvus filter. `arena` is treated as a single-element list when set.
+    """
+    arena_list = list(arenas) if arenas else ([arena] if arena else [])
+    if len(arena_list) == 1:
+        safe = str(arena_list[0]).replace('"', '\\"')
+        filter_expr = f'arena == "{safe}"'
+    elif len(arena_list) > 1:
+        quoted = ", ".join(
+            '"{}"'.format(str(a).replace('"', '\\"')) for a in arena_list
+        )
+        filter_expr = f'arena in [{quoted}]'
+    else:
+        filter_expr = ""
     results = client.search(
         collection_name=COLLECTION_NAME,
         data=[query_vec],
@@ -386,15 +402,26 @@ def get_fts_db() -> sqlite3.Connection:
 
 
 def search_fts(conn: sqlite3.Connection, query: str, limit: int = 20,
-               arena: Optional[str] = None) -> List[Dict]:
-    """BM25 keyword search via FTS5."""
+               arena: Optional[str] = None,
+               arenas: Optional[List[str]] = None) -> List[Dict]:
+    """BM25 keyword search via FTS5.
+
+    Multi-arena: pass `arenas=[...]` to OR multiple `c.arena = ?` clauses,
+    so a single search can span tenant-wide + own user-scope.
+    """
     # Escape FTS5 special chars
     safe_query = re.sub(r'[^\w\s]', ' ', query).strip()
     if not safe_query:
         return []
 
-    arena_filter = f"AND c.arena = ?" if arena else ""
-    params = [safe_query, limit] if not arena else [safe_query, arena, limit]
+    arena_list = list(arenas) if arenas else ([arena] if arena else [])
+    if arena_list:
+        placeholders = ", ".join(["?"] * len(arena_list))
+        arena_filter = f"AND c.arena IN ({placeholders})"
+        params = [safe_query, *arena_list, limit]
+    else:
+        arena_filter = ""
+        params = [safe_query, limit]
 
     sql = f"""
         SELECT c.*, bm25(chunks_fts) as rank
@@ -690,19 +717,28 @@ def _parse_entities_json(s: str) -> List[str]:
 # ---------------------------------------------------------------------------
 
 def search(query: str, method: str = "hybrid", limit: int = 10,
-           arena: Optional[str] = None, enable_rerank: bool = True) -> List[Dict]:
-    """Search documents with specified method."""
+           arena: Optional[str] = None,
+           arenas: Optional[List[str]] = None,
+           enable_rerank: bool = True) -> List[Dict]:
+    """Search documents with specified method.
+
+    arena / arenas: pass either; multi-arena lets a single query span
+    multiple tenant scopes (tenant-wide + user-scope). Forwarded
+    natively to both the vector path (Milvus `arena IN [...]`) and the
+    BM25 path (SQLite `c.arena IN (...)`).
+    """
+    arena_list = list(arenas) if arenas else ([arena] if arena else [])
 
     if method == "vector":
         vec = embed_text(query)
-        results = search_vector(get_milvus(), vec, limit=limit, arena=arena)
+        results = search_vector(get_milvus(), vec, limit=limit, arenas=arena_list)
     elif method == "bm25":
-        results = search_fts(get_fts_db(), query, limit=limit, arena=arena)
+        results = search_fts(get_fts_db(), query, limit=limit, arenas=arena_list)
     else:
         # Hybrid: RRF fusion
         vec = embed_text(query)
-        vector_results = search_vector(get_milvus(), vec, limit=20, arena=arena)
-        bm25_results = search_fts(get_fts_db(), query, limit=20, arena=arena)
+        vector_results = search_vector(get_milvus(), vec, limit=20, arenas=arena_list)
+        bm25_results = search_fts(get_fts_db(), query, limit=20, arenas=arena_list)
         results = rrf_fuse(vector_results, bm25_results)
 
     # Rerank if enabled
@@ -812,9 +848,14 @@ def serve(port: int = DEFAULT_PORT):
         method: str = Q("hybrid", description="hybrid|vector|bm25"),
         limit: int = Q(10, ge=1, le=50),
         arena: Optional[str] = Q(None),
+        arenas: List[str] = Q(default=[]),
         rerank: bool = Q(True),
     ):
-        results = search(q, method=method, limit=limit, arena=arena, enable_rerank=rerank)
+        results = search(
+            q, method=method, limit=limit,
+            arena=arena, arenas=arenas or None,
+            enable_rerank=rerank,
+        )
         return {"query": q, "method": method, "results": results, "count": len(results)}
 
     @api.post("/search")
@@ -823,10 +864,15 @@ def serve(port: int = DEFAULT_PORT):
         method: str = "hybrid",
         limit: int = 10,
         arena: Optional[str] = None,
+        arenas: Optional[List[str]] = None,
         rerank: bool = True,
     ):
         """POST version of search for compatibility."""
-        results = search(q, method=method, limit=limit, arena=arena, enable_rerank=rerank)
+        results = search(
+            q, method=method, limit=limit,
+            arena=arena, arenas=arenas,
+            enable_rerank=rerank,
+        )
         return {"query": q, "method": method, "results": results, "count": len(results)}
 
     @api.post("/index")

package/packages/memory-engine/tests/e2e_arena.sh

@@ -125,6 +125,66 @@ print("yes" if ok and data else "no")')
 [ "$all_match" = "yes" ] && ok "metadata_filter scopes to probe + arena" \
   || fail "metadata_filter let other rows through"
 
+# ---------------------------------------------------------------------------
+# User-scope vs tenant-wide arenas — proves the multi-arena search model.
+#
+#   tenant-wide row    arena=acme               (visible to every user in acme)
+#   user-A's row       arena=acme:user-a        (only user-A retrieves it)
+#   user-B's row       arena=acme:user-b        (only user-B retrieves it)
+#
+# A user-scoped search sends arenas=[acme, acme:userX] so the user sees
+# tenant-wide AND own user-scope, but never another user's user-scope.
+# ---------------------------------------------------------------------------
+
+echo ""
+echo "=== user-scope vs tenant-wide ==="
+post '{"content":"acme tenant-wide rules of engagement","metadata":{"arena":"acme","probe":"e2e-arena"}}' >/dev/null
+post '{"content":"alice private note about Project Mercury","metadata":{"arena":"acme:alice","probe":"e2e-arena"}}' >/dev/null
+post '{"content":"bob private note about Project Saturn","metadata":{"arena":"acme:bob","probe":"e2e-arena"}}' >/dev/null
+sleep 3
+
+# Search as alice: arenas=[acme, acme:alice] — should see tenant-wide + own
+SAlice=$(curl -sf -X POST "$BASE/search" -H "Content-Type: application/json" \
+  -d '{"query":"Project rules note","limit":20,"arenas":["acme","acme:alice"]}')
+
+alice_sees_tenant=$(echo "$SAlice" | python3 -c '
+import json,sys
+data=json.load(sys.stdin).get("results",[])
+print("yes" if any("tenant-wide" in r.get("content","") for r in data) else "no")')
+alice_sees_own=$(echo "$SAlice" | python3 -c '
+import json,sys
+data=json.load(sys.stdin).get("results",[])
+print("yes" if any("Mercury" in r.get("content","") for r in data) else "no")')
+alice_leak_bob=$(echo "$SAlice" | python3 -c '
+import json,sys
+data=json.load(sys.stdin).get("results",[])
+print(sum(1 for r in data if "Saturn" in r.get("content","")))')
+
+[ "$alice_sees_tenant" = "yes" ] && ok "alice: tenant-wide visible" \
+  || fail "alice: missing tenant-wide row"
+[ "$alice_sees_own" = "yes" ] && ok "alice: own user-scope visible" \
+  || fail "alice: missing own user-scope row"
+[ "$alice_leak_bob" = "0" ] && ok "alice: no leakage of bob's user-scope" \
+  || fail "alice leaked $alice_leak_bob bob rows (cross-user!)"
+
+# Search as bob: arenas=[acme, acme:bob] — should see tenant-wide + own
+SBob=$(curl -sf -X POST "$BASE/search" -H "Content-Type: application/json" \
+  -d '{"query":"Project rules note","limit":20,"arenas":["acme","acme:bob"]}')
+
+bob_sees_own=$(echo "$SBob" | python3 -c '
+import json,sys
+data=json.load(sys.stdin).get("results",[])
+print("yes" if any("Saturn" in r.get("content","") for r in data) else "no")')
+bob_leak_alice=$(echo "$SBob" | python3 -c '
+import json,sys
+data=json.load(sys.stdin).get("results",[])
+print(sum(1 for r in data if "Mercury" in r.get("content","")))')
+
+[ "$bob_sees_own" = "yes" ] && ok "bob: own user-scope visible" \
+  || fail "bob: missing own user-scope row"
+[ "$bob_leak_alice" = "0" ] && ok "bob: no leakage of alice's user-scope" \
+  || fail "bob leaked $bob_leak_alice alice rows (cross-user!)"
+
 # ---------------------------------------------------------------------------
 # Same content across two arenas — proves the arena-aware id derivation.
 # Pre-v0.7.8, identical content collapsed to one row in L4/L5/L6 because