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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pentatonic-ai/ai-agent-sdk",
-  "version": "0.7.11",
+  "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

@@ -231,6 +231,63 @@ 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");

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) {
@@ -163,6 +175,9 @@ export function composeArenas(clientId, userId) {
  * @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) {
@@ -174,6 +189,7 @@ export async function engineStore(engineUrl, opts) {
     metadata = {},
     layerType,
     actorUserId,
+    headers,
   } = opts || {};
   if (!clientId) throw new Error("engineStore: clientId required");
   if (typeof content !== "string") throw new Error("engineStore: content required");
@@ -187,7 +203,7 @@ export async function engineStore(engineUrl, opts) {
       ...(actorUserId !== undefined ? { actor_user_id: actorUserId } : {}),
     },
   };
-  return fetchEngine(engineUrl, "/store", body);
+  return fetchEngine(engineUrl, "/store", body, { headers });
 }
 
 /**
@@ -206,6 +222,8 @@ export async function engineStore(engineUrl, opts) {
  * @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) {
@@ -216,6 +234,7 @@ export async function engineSearch(engineUrl, opts) {
     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");
@@ -232,7 +251,7 @@ export async function engineSearch(engineUrl, opts) {
       ? { metadata_filter: metadataFilter }
       : {}),
   };
-  return fetchEngine(engineUrl, "/search", body);
+  return fetchEngine(engineUrl, "/search", body, { headers });
 }
 
 /**
@@ -245,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");
@@ -258,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 });
 }