@pentatonic-ai/ai-agent-sdk 0.5.6 → 0.5.8

package/packages/memory/src/hosted.js

@@ -0,0 +1,379 @@
+/**
+ * Hosted-mode helpers for the Pentatonic memory system.
+ *
+ * These talk to a remote TES tenant over HTTPS using GraphQL, with a
+ * `tes_<clientId>_<rand>` bearer token in the Authorization header.
+ * They are deliberately thin wrappers around the GraphQL surface so
+ * any caller (the OpenClaw plugin, the LLM proxy worker, a custom
+ * integration) gets the same wire shape, the same error handling, and
+ * the same operational patterns.
+ *
+ * No `pg`, no Node-only APIs — Workers-compatible. Pure `fetch`.
+ *
+ * @example
+ *   import { hostedSearch, hostedEmitChatTurn } from
+ *     "@pentatonic-ai/ai-agent-sdk/memory/hosted";
+ *
+ *   const config = {
+ *     endpoint: "https://acme.api.pentatonic.com",
+ *     clientId: "acme",
+ *     apiKey:   "tes_acme_xxxxx",
+ *   };
+ *
+ *   const { memories } = await hostedSearch(config, "What's my name?", {
+ *     limit: 6, minScore: 0.55, timeoutMs: 800,
+ *   });
+ *
+ *   await hostedEmitChatTurn(config, {
+ *     userMessage:       "Hi",
+ *     assistantResponse: "Hello!",
+ *     model:             "gpt-4o-mini",
+ *   }, { source: "my-product" });
+ */
+
+const SEMANTIC_SEARCH_QUERY = `
+  query SemanticSearchMemories($clientId: String!, $query: String!, $limit: Int, $minScore: Float) {
+    semanticSearchMemories(clientId: $clientId, query: $query, limit: $limit, minScore: $minScore) {
+      id
+      content
+      similarity
+    }
+  }
+`;
+
+const CREATE_MODULE_EVENT_MUTATION = `
+  mutation CreateModuleEvent($moduleId: String!, $input: ModuleEventInput!) {
+    createModuleEvent(moduleId: $moduleId, input: $input) { success eventId }
+  }
+`;
+
+const DEFAULT_SEARCH_TIMEOUT_MS = 5000;
+const DEFAULT_EMIT_TIMEOUT_MS = 10000;
+const DEFAULT_SEARCH_LIMIT = 6;
+const DEFAULT_SEARCH_MIN_SCORE = 0.55;
+
+/**
+ * Normalise a config object — accepts both modern (`endpoint/clientId/apiKey`)
+ * and legacy openclaw-style (`tes_endpoint/tes_client_id/tes_api_key`) keys.
+ *
+ * @param {object} config
+ * @returns {{endpoint: string, clientId: string, apiKey: string}}
+ */
+function normalizeConfig(config) {
+  if (!config) throw new Error("hosted: config is required");
+  const endpoint = config.endpoint || config.tes_endpoint;
+  const clientId = config.clientId || config.tes_client_id;
+  const apiKey = config.apiKey || config.tes_api_key;
+  if (!endpoint || !clientId || !apiKey) {
+    throw new Error(
+      "hosted: config requires { endpoint, clientId, apiKey } (or legacy tes_* equivalents)"
+    );
+  }
+  return { endpoint, clientId, apiKey };
+}
+
+/**
+ * Build the request headers TES expects for hosted-mode calls.
+ * Bearer auth if the apiKey starts with `tes_`; otherwise treated as a
+ * service key (for internal callers).
+ */
+export function buildHostedHeaders(config) {
+  const { clientId, apiKey } = normalizeConfig(config);
+  const headers = {
+    "Content-Type": "application/json",
+    "x-client-id": clientId,
+  };
+  if (apiKey.startsWith("tes_")) {
+    headers["Authorization"] = `Bearer ${apiKey}`;
+  } else {
+    headers["x-service-key"] = apiKey;
+  }
+  return headers;
+}
+
+/**
+ * Run a semantic memory search against a remote TES tenant.
+ *
+ * @param {object} config — { endpoint, clientId, apiKey }
+ * @param {string} query  — natural-language query
+ * @param {object} [opts]
+ * @param {number} [opts.limit=6]
+ * @param {number} [opts.minScore=0.55]
+ * @param {number} [opts.timeoutMs=5000]
+ * @returns {Promise<{
+ *   memories: Array<{id: string, content: string, similarity: number}>,
+ *   skipped?: string,
+ * }>}
+ *
+ * Failure mode: any error returns `{ memories: [], skipped: <reason> }`.
+ * Callers (e.g. the LLM proxy) inspect `skipped` to set `X-TES-Skipped`
+ * on their response, then forward unmodified. We never throw — the
+ * fail-soft contract means a hosted-search call never breaks the
+ * caller's primary user-facing flow.
+ */
+export async function hostedSearch(config, query, opts = {}) {
+  if (!query) return { memories: [], skipped: "no_query" };
+
+  let cfg;
+  try {
+    cfg = normalizeConfig(config);
+  } catch (err) {
+    return { memories: [], skipped: `config_error:${err.message}` };
+  }
+
+  const limit = opts.limit ?? DEFAULT_SEARCH_LIMIT;
+  const minScore = opts.minScore ?? DEFAULT_SEARCH_MIN_SCORE;
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_SEARCH_TIMEOUT_MS;
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+  let response;
+  try {
+    response = await fetch(`${cfg.endpoint}/api/graphql`, {
+      method: "POST",
+      headers: buildHostedHeaders(cfg),
+      body: JSON.stringify({
+        query: SEMANTIC_SEARCH_QUERY,
+        variables: { clientId: cfg.clientId, query, limit, minScore },
+      }),
+      signal: controller.signal,
+    });
+  } catch (err) {
+    clearTimeout(timer);
+    return {
+      memories: [],
+      skipped: err.name === "AbortError" ? "tes_timeout" : "tes_unreachable",
+    };
+  }
+  clearTimeout(timer);
+
+  if (!response.ok) {
+    return { memories: [], skipped: `tes_http_${response.status}` };
+  }
+
+  let payload;
+  try {
+    payload = await response.json();
+  } catch {
+    return { memories: [], skipped: "tes_invalid_json" };
+  }
+
+  if (payload.errors?.length) {
+    const reason = payload.errors[0].message || "tes_graphql_error";
+    return { memories: [], skipped: `tes_graphql:${shortenReason(reason)}` };
+  }
+
+  return { memories: payload.data?.semanticSearchMemories || [] };
+}
+
+/**
+ * Emit a CHAT_TURN event to the conversation-analytics module of a
+ * remote TES tenant. The deep-memory consumer also subscribes to
+ * CHAT_TURN, so a single emit lands in both pipelines via consumer
+ * fan-out at the queue layer.
+ *
+ * @param {object} config — { endpoint, clientId, apiKey }
+ * @param {object} payload
+ * @param {string} [payload.userMessage]
+ * @param {string} [payload.assistantResponse]
+ * @param {string} [payload.model]
+ * @param {object} [payload.usage]
+ * @param {Array}  [payload.toolCalls]
+ * @param {number} [payload.turnNumber]
+ * @param {string} [payload.systemPrompt]
+ * @param {string} [payload.sessionId]
+ * @param {string} [payload.userId]
+ * @param {object} [payload.extra] — additional attributes merged onto the event
+ * @param {object} [opts]
+ * @param {string} [opts.source="tes-sdk"] — attribution string written into attributes.source
+ * @param {number} [opts.timeoutMs=10000]
+ * @returns {Promise<{ ok: boolean, eventId?: string, skipped?: string }>}
+ */
+export async function hostedEmitChatTurn(config, payload, opts = {}) {
+  if (!payload) return { ok: false, skipped: "no_payload" };
+  if (!payload.userMessage && !payload.assistantResponse) {
+    return { ok: false, skipped: "empty_turn" };
+  }
+
+  let cfg;
+  try {
+    cfg = normalizeConfig(config);
+  } catch (err) {
+    return { ok: false, skipped: `config_error:${err.message}` };
+  }
+
+  const source = opts.source || "tes-sdk";
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_EMIT_TIMEOUT_MS;
+
+  const attributes = { source };
+  if (payload.userMessage !== undefined)
+    attributes.user_message = payload.userMessage;
+  if (payload.assistantResponse !== undefined)
+    attributes.assistant_response = payload.assistantResponse;
+  if (payload.model) attributes.model = payload.model;
+  if (payload.usage) attributes.usage = payload.usage;
+  if (payload.toolCalls?.length) attributes.tool_calls = payload.toolCalls;
+  if (payload.turnNumber !== undefined)
+    attributes.turn_number = payload.turnNumber;
+  if (payload.systemPrompt) attributes.system_prompt = payload.systemPrompt;
+  if (payload.userId) attributes.user_id = payload.userId;
+  if (payload.extra && typeof payload.extra === "object") {
+    Object.assign(attributes, payload.extra);
+  }
+
+  const data = { attributes };
+  if (payload.sessionId) data.entity_id = payload.sessionId;
+
+  const input = { eventType: "CHAT_TURN", data };
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+  let response;
+  try {
+    response = await fetch(`${cfg.endpoint}/api/graphql`, {
+      method: "POST",
+      headers: buildHostedHeaders(cfg),
+      body: JSON.stringify({
+        query: CREATE_MODULE_EVENT_MUTATION,
+        variables: { moduleId: "conversation-analytics", input },
+      }),
+      signal: controller.signal,
+    });
+  } catch (err) {
+    clearTimeout(timer);
+    return {
+      ok: false,
+      skipped: err.name === "AbortError" ? "tes_timeout" : "tes_unreachable",
+    };
+  }
+  clearTimeout(timer);
+
+  if (!response.ok) {
+    return { ok: false, skipped: `tes_http_${response.status}` };
+  }
+
+  let body;
+  try {
+    body = await response.json();
+  } catch {
+    return { ok: false, skipped: "tes_invalid_json" };
+  }
+
+  if (body.errors?.length) {
+    return {
+      ok: false,
+      skipped: `tes_graphql:${shortenReason(body.errors[0].message)}`,
+    };
+  }
+
+  return {
+    ok: !!body.data?.createModuleEvent?.success,
+    eventId: body.data?.createModuleEvent?.eventId,
+  };
+}
+
+/**
+ * Emit a STORE_MEMORY event against the deep-memory module. Used by the
+ * OpenClaw plugin for explicit memory-write tools.
+ *
+ * @param {object} config
+ * @param {string} content
+ * @param {object} [metadata]
+ * @param {object} [opts]
+ * @param {string} [opts.source="tes-sdk"]
+ * @param {number} [opts.timeoutMs=10000]
+ * @returns {Promise<{ ok: boolean, eventId?: string, skipped?: string }>}
+ */
+export async function hostedStoreMemory(
+  config,
+  content,
+  metadata = {},
+  opts = {}
+) {
+  if (!content) return { ok: false, skipped: "no_content" };
+
+  let cfg;
+  try {
+    cfg = normalizeConfig(config);
+  } catch (err) {
+    return { ok: false, skipped: `config_error:${err.message}` };
+  }
+
+  const source = opts.source || "tes-sdk";
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_EMIT_TIMEOUT_MS;
+
+  const data = {
+    entity_id: metadata.session_id || metadata.sessionId || source,
+    attributes: {
+      ...metadata,
+      content,
+      source,
+    },
+  };
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+  let response;
+  try {
+    response = await fetch(`${cfg.endpoint}/api/graphql`, {
+      method: "POST",
+      headers: buildHostedHeaders(cfg),
+      body: JSON.stringify({
+        query: CREATE_MODULE_EVENT_MUTATION,
+        variables: {
+          moduleId: "deep-memory",
+          input: { eventType: "STORE_MEMORY", data },
+        },
+      }),
+      signal: controller.signal,
+    });
+  } catch (err) {
+    clearTimeout(timer);
+    return {
+      ok: false,
+      skipped: err.name === "AbortError" ? "tes_timeout" : "tes_unreachable",
+    };
+  }
+  clearTimeout(timer);
+
+  if (!response.ok) {
+    return { ok: false, skipped: `tes_http_${response.status}` };
+  }
+
+  let body;
+  try {
+    body = await response.json();
+  } catch {
+    return { ok: false, skipped: "tes_invalid_json" };
+  }
+
+  if (body.errors?.length) {
+    return {
+      ok: false,
+      skipped: `tes_graphql:${shortenReason(body.errors[0].message)}`,
+    };
+  }
+
+  return {
+    ok: !!body.data?.createModuleEvent?.success,
+    eventId: body.data?.createModuleEvent?.eventId,
+  };
+}
+
+function shortenReason(msg) {
+  if (typeof msg !== "string") return "unknown";
+  return msg
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "_")
+    .slice(0, 60);
+}
+
+// Re-export the system-message injector so callers that import the
+// hosted module get the full memory-augmentation surface in one place.
+// Keeping the implementation in `./inject.js` lets non-hosted consumers
+// (e.g. a future "augment a request body" helper that doesn't talk to
+// TES) reuse it without pulling in the GraphQL surface.
+export { injectMemories } from "./inject.js";

package/packages/memory/src/inject.js

@@ -0,0 +1,83 @@
+/**
+ * Memory injection — formats retrieved memories as a system-message preamble
+ * and merges them into the upstream request body.
+ *
+ * Why a preamble (not a separate user-turn or tool-result):
+ *   - Customer's existing system prompt is preserved verbatim, just appended.
+ *   - Anthropic and OpenAI both treat system content as cache-friendly.
+ *   - No conversation-history mutation — replays remain reproducible.
+ *
+ * Format:
+ *   <tes:context>
+ *     [1] (similarity 0.82) memory text...
+ *     [2] (similarity 0.71) memory text...
+ *   </tes:context>
+ *
+ * The XML-ish wrapper makes it trivial for the model to ignore on demand
+ * and trivial for an evaluator to strip when measuring quality deltas.
+ */
+
+const MAX_CHARS_PER_MEMORY = 1200;
+
+/**
+ * @param {object} body                 — upstream request body, mutated copy returned
+ * @param {Array<{id, content, similarity}>} memories
+ * @param {"anthropic"|"openai"} provider
+ * @returns {object} new body
+ */
+export function injectMemories(body, memories, provider) {
+  if (!memories || memories.length === 0) return body;
+
+  const preamble = formatPreamble(memories);
+
+  if (provider === "anthropic") {
+    return injectAnthropic(body, preamble);
+  }
+  return injectOpenAI(body, preamble);
+}
+
+function formatPreamble(memories) {
+  const lines = ["<tes:context>"];
+  memories.forEach((m, i) => {
+    const sim =
+      typeof m.similarity === "number" ? m.similarity.toFixed(2) : "?";
+    const content = (m.content || "").slice(0, MAX_CHARS_PER_MEMORY);
+    lines.push(`[${i + 1}] (similarity ${sim}) ${content}`);
+  });
+  lines.push("</tes:context>");
+  return lines.join("\n");
+}
+
+function injectAnthropic(body, preamble) {
+  // Anthropic accepts `system` as either a string OR an array of content
+  // blocks. Preserve whichever shape the customer sent.
+  const next = { ...body };
+  if (typeof body.system === "string") {
+    next.system = `${preamble}\n\n${body.system}`;
+  } else if (Array.isArray(body.system)) {
+    next.system = [{ type: "text", text: preamble }, ...body.system];
+  } else {
+    next.system = preamble;
+  }
+  return next;
+}
+
+function injectOpenAI(body, preamble) {
+  // OpenAI carries the system prompt as the first message with role:'system'.
+  // If one exists we prepend; otherwise we insert a fresh one at index 0.
+  const messages = Array.isArray(body.messages) ? [...body.messages] : [];
+  if (messages.length > 0 && messages[0].role === "system") {
+    const existing = messages[0];
+    const existingContent =
+      typeof existing.content === "string"
+        ? existing.content
+        : JSON.stringify(existing.content);
+    messages[0] = {
+      ...existing,
+      content: `${preamble}\n\n${existingContent}`,
+    };
+  } else {
+    messages.unshift({ role: "system", content: preamble });
+  }
+  return { ...body, messages };
+}

package/packages/memory/src/openclaw/index.js

@@ -38,6 +38,40 @@
 import pg from "pg";
 import { createMemorySystem } from "../index.js";
 import { createContextEngine } from "./context-engine.js";
+import { sanitizeMemoryContent } from "../sanitize.js";
+import {
+  hostedSearch as _hostedSearch,
+  hostedEmitChatTurn as _hostedEmitChatTurn,
+  hostedStoreMemory as _hostedStoreMemory,
+} from "../hosted.js";
+
+// --- Hosted-mode adapters ---
+//
+// The OpenClaw plugin predates the public hosted-helper API (`packages/
+// memory/src/hosted.js`). The wrappers below adapt the plugin's existing
+// call shape to the public API so other consumers (the LLM proxy worker,
+// custom integrations) hit the same code path. Adapters are tiny — they
+// translate args and unwrap the result envelope. New code should import
+// from `@pentatonic-ai/ai-agent-sdk/memory/hosted` directly.
+
+async function hostedSearch(config, query, limit = 5, minScore = 0.3) {
+  const { memories } = await _hostedSearch(config, query, { limit, minScore });
+  return memories;
+}
+
+async function hostedEmitChatTurn(config, sessionId, turn) {
+  return _hostedEmitChatTurn(
+    config,
+    { ...turn, sessionId },
+    { source: "openclaw-plugin" }
+  );
+}
+
+async function hostedStore(config, content, metadata = {}) {
+  return _hostedStoreMemory(config, content, metadata, {
+    source: metadata.source || "openclaw-plugin",
+  });
+}
 
 const { Pool } = pg;
 
@@ -74,139 +108,6 @@ function getLocalMemory(config) {
   return memory;
 }
 
-// --- Hosted mode helpers ---
-
-function tesHeaders(config) {
-  const headers = {
-    "Content-Type": "application/json",
-    "x-client-id": config.tes_client_id,
-  };
-  if (config.tes_api_key?.startsWith("tes_")) {
-    headers["Authorization"] = `Bearer ${config.tes_api_key}`;
-  } else {
-    headers["x-service-key"] = config.tes_api_key;
-  }
-  return headers;
-}
-
-async function hostedSearch(config, query, limit = 5, minScore = 0.3) {
-  try {
-    const response = await fetch(`${config.tes_endpoint}/api/graphql`, {
-      method: "POST",
-      headers: tesHeaders(config),
-      body: JSON.stringify({
-        query: `query($clientId: String!, $query: String!, $limit: Int, $minScore: Float) {
-          semanticSearchMemories(clientId: $clientId, query: $query, limit: $limit, minScore: $minScore) {
-            id content similarity
-          }
-        }`,
-        variables: {
-          clientId: config.tes_client_id,
-          query,
-          limit,
-          minScore,
-        },
-      }),
-      signal: AbortSignal.timeout(5000),
-    });
-    if (!response.ok) return [];
-    const json = await response.json();
-    return json.data?.semanticSearchMemories || [];
-  } catch {
-    return [];
-  }
-}
-
-/**
- * Emit a CHAT_TURN event to TES so the conversation-analytics dashboard
- * (Token Universe + Tools tabs) can render. Without this, the dashboard
- * filters on eventType=CHAT_TURN and shows nothing for OpenClaw users
- * because the only events emitted are STORE_MEMORY.
- *
- * Anything missing from the message metadata is omitted rather than
- * defaulted to zero — that way the dashboard can distinguish "no data"
- * from "zero usage".
- */
-async function hostedEmitChatTurn(config, sessionId, turn) {
-  const attributes = {
-    source: "openclaw-plugin",
-    user_message: turn.userMessage,
-    assistant_response: turn.assistantResponse,
-  };
-  if (turn.model) attributes.model = turn.model;
-  if (turn.usage) attributes.usage = turn.usage;
-  if (turn.toolCalls?.length) attributes.tool_calls = turn.toolCalls;
-  if (turn.turnNumber !== undefined) attributes.turn_number = turn.turnNumber;
-  if (turn.systemPrompt) attributes.system_prompt = turn.systemPrompt;
-
-  try {
-    const response = await fetch(`${config.tes_endpoint}/api/graphql`, {
-      method: "POST",
-      headers: tesHeaders(config),
-      // Route through createModuleEvent on the conversation-analytics
-      // module rather than the top-level emitEvent. The latter requires
-      // a permission most client API keys don't have ("Access denied:
-      // You don't have permission to update emitEvent"), but the
-      // module's manifest declares CHAT_TURN as a registered event
-      // type, so the module-scoped path is both authorised and
-      // consistent with how STORE_MEMORY is emitted.
-      body: JSON.stringify({
-        query: `mutation Cme($moduleId: String!, $input: ModuleEventInput!) {
-          createModuleEvent(moduleId: $moduleId, input: $input) { success eventId }
-        }`,
-        variables: {
-          moduleId: "conversation-analytics",
-          input: {
-            eventType: "CHAT_TURN",
-            data: {
-              entity_id: sessionId,
-              attributes,
-            },
-          },
-        },
-      }),
-      signal: AbortSignal.timeout(10000),
-    });
-    if (!response.ok) return null;
-    return response.json();
-  } catch {
-    return null;
-  }
-}
-
-async function hostedStore(config, content, metadata = {}) {
-  try {
-    const response = await fetch(`${config.tes_endpoint}/api/graphql`, {
-      method: "POST",
-      headers: tesHeaders(config),
-      body: JSON.stringify({
-        query: `mutation CreateModuleEvent($moduleId: String!, $input: ModuleEventInput!) {
-          createModuleEvent(moduleId: $moduleId, input: $input) { success eventId }
-        }`,
-        variables: {
-          moduleId: "deep-memory",
-          input: {
-            eventType: "STORE_MEMORY",
-            data: {
-              entity_id: metadata.session_id || "openclaw",
-              attributes: {
-                ...metadata,
-                content,
-                source: "openclaw-plugin",
-              },
-            },
-          },
-        },
-      }),
-      signal: AbortSignal.timeout(10000),
-    });
-    if (!response.ok) return null;
-    return response.json();
-  } catch {
-    return null;
-  }
-}
-
 // --- Hosted context engine ---
 
 // Per-session turn buffer. Holds the user message until the matching
@@ -440,7 +341,7 @@ function createHostedContextEngine(config, opts = {}) {
         const memoryText = results
           .map(
             (m) =>
-              `- [${Math.round((m.similarity || 0) * 100)}%] ${m.content}`
+              `- [${Math.round((m.similarity || 0) * 100)}%] ${sanitizeMemoryContent(m.content)}`
           )
           .join("\n");
 
@@ -638,7 +539,7 @@ Tell the user to run step 1 first, then help them fill in the config with the cr
           return results
             .map(
               (m, i) =>
-                `${i + 1}. [${Math.round((m.similarity || 0) * 100)}%] ${m.content}`
+                `${i + 1}. [${Math.round((m.similarity || 0) * 100)}%] ${sanitizeMemoryContent(m.content)}`
             )
             .join("\n\n");
         },
@@ -705,7 +606,7 @@ Tell the user to run step 1 first, then help them fill in the config with the cr
           return results
             .map(
               (m, i) =>
-                `${i + 1}. [${Math.round((m.similarity || 0) * 100)}%] ${m.content}`
+                `${i + 1}. [${Math.round((m.similarity || 0) * 100)}%] ${sanitizeMemoryContent(m.content)}`
             )
             .join("\n\n");
         },