@pentatonic-ai/ai-agent-sdk 0.4.1 → 0.4.3

package/README.md

@@ -171,7 +171,7 @@ Works with both local and hosted setups. Just tell OpenClaw to set it up.
 ### Install
 
 ```bash
-openclaw plugins install -l ./packages/memory/src/openclaw
+openclaw plugins install @pentatonic-ai/ai-agent-sdk
 ```
 
 ### Set up

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pentatonic-ai/ai-agent-sdk",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "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",
@@ -51,6 +51,10 @@
     "mcp",
     "model-context-protocol"
   ],
+  "openclaw": {
+    "extensions": ["./packages/memory/src/openclaw/index.js"],
+    "hooks": {}
+  },
   "license": "MIT",
   "homepage": "https://thingeventsystem.ai",
   "repository": {

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

@@ -6,7 +6,7 @@
  *   - Hosted: routes through TES GraphQL API
  *
  * Install:
- *   openclaw plugins install -l ./packages/memory/src/openclaw
+ *   openclaw plugins install @pentatonic-ai/ai-agent-sdk
  *
  * Config in openclaw.json:
  * {
@@ -36,47 +36,38 @@
  */
 
 import pg from "pg";
-import { execFileSync } from "child_process";
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
-import { join } from "path";
-import { homedir } from "os";
 import { createMemorySystem } from "../index.js";
 import { createContextEngine } from "./context-engine.js";
 
 const { Pool } = pg;
 
-const TELEMETRY_URL = "https://sdk-telemetry.philip-134.workers.dev";
-
 let memory = null;
 
 function isHostedMode(config) {
   return !!(config.tes_endpoint && config.tes_api_key);
 }
 
-function getLocalMemory(config = {}) {
+function getLocalMemory(config) {
   if (memory) return memory;
 
-  const dbUrl =
-    config.database_url ||
-    process.env.DATABASE_URL ||
-    "postgres://memory:memory@localhost:5433/memory";
-  const embUrl =
-    config.embedding_url ||
-    process.env.EMBEDDING_URL ||
-    "http://localhost:11435/v1";
-  const embModel =
-    config.embedding_model ||
-    process.env.EMBEDDING_MODEL ||
-    "nomic-embed-text";
-  const llmUrl =
-    config.llm_url || process.env.LLM_URL || "http://localhost:11435/v1";
-  const llmModel =
-    config.llm_model || process.env.LLM_MODEL || "llama3.2:3b";
+  if (!config.database_url) {
+    throw new Error(
+      "pentatonic-memory: database_url is required in plugin config for local mode. " +
+      "Run `npx @pentatonic-ai/ai-agent-sdk memory` first to start the Docker stack, " +
+      "then add the database_url to your openclaw.json plugin config."
+    );
+  }
 
   memory = createMemorySystem({
-    db: new Pool({ connectionString: dbUrl }),
-    embedding: { url: embUrl, model: embModel },
-    llm: { url: llmUrl, model: llmModel },
+    db: new Pool({ connectionString: config.database_url }),
+    embedding: {
+      url: config.embedding_url || "http://localhost:11435/v1",
+      model: config.embedding_model || "nomic-embed-text",
+    },
+    llm: {
+      url: config.llm_url || "http://localhost:11435/v1",
+      model: config.llm_model || "llama3.2:3b",
+    },
     logger: (msg) => process.stderr.write(`[pentatonic-memory] ${msg}\n`),
   });
 
@@ -242,240 +233,6 @@ function createHostedContextEngine(config, opts = {}) {
   };
 }
 
-// --- Telemetry ---
-
-function emitTelemetry(mode) {
-  if (process.env.PENTATONIC_TELEMETRY === "0") return;
-  const raw = `${process.env.USER || "u"}:${process.platform}:${process.arch}`;
-  let h = 0;
-  for (let i = 0; i < raw.length; i++)
-    h = ((h << 5) - h + raw.charCodeAt(i)) | 0;
-  const mid = (h >>> 0).toString(16).padStart(8, "0");
-  fetch(TELEMETRY_URL, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({
-      machine_id: mid,
-      sdk_version: "0.4.0",
-      node_version: process.version,
-      platform: process.platform,
-      arch: process.arch,
-      mode: `openclaw-${mode}`,
-    }),
-    signal: AbortSignal.timeout(5000),
-  }).catch(() => {});
-}
-
-// --- Setup helpers ---
-
-function getConfigPath() {
-  const candidates = [
-    join(homedir(), ".openclaw", "pentatonic-memory.json"),
-    join(homedir(), ".claude-pentatonic", "tes-memory.local.md"),
-    join(homedir(), ".claude", "tes-memory.local.md"),
-  ];
-  return candidates.find((p) => existsSync(p)) || candidates[0];
-}
-
-function writeOpenClawConfig(mode, settings) {
-  const configDir = join(homedir(), ".openclaw");
-  if (!existsSync(configDir)) mkdirSync(configDir, { recursive: true });
-
-  const configPath = join(configDir, "pentatonic-memory.json");
-  writeFileSync(configPath, JSON.stringify({ mode, ...settings }, null, 2));
-  return configPath;
-}
-
-async function runLocalSetup() {
-  // Check Docker
-  try {
-    execFileSync("docker", ["info"], { stdio: "pipe" });
-  } catch {
-    return { success: false, error: "Docker is required but not running. Install from https://docker.com" };
-  }
-
-  // Find the memory package directory
-  let memoryDir;
-  try {
-    const pkgRoot = new URL("../../..", import.meta.url).pathname;
-    memoryDir = existsSync(join(pkgRoot, "docker-compose.yml"))
-      ? pkgRoot
-      : null;
-  } catch { memoryDir = null; }
-
-  if (!memoryDir) {
-    // Fallback: try via npm package location
-    try {
-      const resolved = new URL("../../../../packages/memory", import.meta.url).pathname;
-      if (existsSync(join(resolved, "docker-compose.yml"))) memoryDir = resolved;
-    } catch { /* */ }
-  }
-
-  if (!memoryDir) {
-    return {
-      success: false,
-      error: "Could not find memory package. Run: npx @pentatonic-ai/ai-agent-sdk memory",
-    };
-  }
-
-  // Start Docker stack
-  try {
-    execFileSync("docker", ["compose", "up", "-d", "memory", "postgres", "ollama"], {
-      cwd: memoryDir,
-      stdio: "pipe",
-    });
-  } catch (err) {
-    return { success: false, error: `Docker compose failed: ${err.message}` };
-  }
-
-  // Pull models
-  const embModel = process.env.EMBEDDING_MODEL || "nomic-embed-text";
-  const llmModel = process.env.LLM_MODEL || "llama3.2:3b";
-  const pulled = [];
-  for (const model of [embModel, llmModel]) {
-    try {
-      execFileSync("docker", ["compose", "exec", "ollama", "ollama", "pull", model], {
-        cwd: memoryDir,
-        stdio: "pipe",
-      });
-      pulled.push(model);
-    } catch { /* non-fatal */ }
-  }
-
-  const configPath = writeOpenClawConfig("local", {
-    memory_url: "http://localhost:3333",
-  });
-
-  return {
-    success: true,
-    mode: "local",
-    configPath,
-    models: pulled,
-    message: "Local memory stack running. PostgreSQL + pgvector + Ollama + memory server started.",
-  };
-}
-
-async function runHostedSetup(email, clientId, password, region) {
-  const endpoint = "https://api.pentatonic.com";
-
-  // Try login first
-  let accessToken = null;
-  try {
-    const res = await fetch(`${endpoint}/api/enrollment/login`, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ email, password, clientId }),
-    });
-    if (res.ok) {
-      const data = await res.json();
-      if (data.tokens?.accessToken) accessToken = data.tokens.accessToken;
-    }
-  } catch { /* */ }
-
-  // If not logged in, enroll
-  if (!accessToken) {
-    try {
-      const res = await fetch(`${endpoint}/api/enrollment/submit`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({
-          clientId,
-          companyName: clientId,
-          industryType: "technology",
-          authProvider: "native",
-          adminEmail: email,
-          adminPassword: password,
-          region: (region || "eu").toLowerCase(),
-        }),
-      });
-      const data = await res.json();
-      if (!res.ok) {
-        const errors = data.errors || {};
-        if (errors.clientId?.includes("already registered")) {
-          return { success: false, error: "Client ID already registered. Ask your admin to invite you, then run setup again." };
-        }
-        return { success: false, error: data.message || Object.values(errors).join(", ") || "Enrollment failed" };
-      }
-    } catch (err) {
-      return { success: false, error: `Failed to connect: ${err.message}` };
-    }
-
-    // Poll for verification (up to 5 minutes)
-    const start = Date.now();
-    while (Date.now() - start < 300000) {
-      await new Promise((r) => setTimeout(r, 3000));
-      try {
-        const res = await fetch(`${endpoint}/api/enrollment/login`, {
-          method: "POST",
-          headers: { "Content-Type": "application/json" },
-          body: JSON.stringify({ email, password, clientId }),
-        });
-        if (res.ok) {
-          const data = await res.json();
-          if (data.tokens?.accessToken) {
-            accessToken = data.tokens.accessToken;
-            break;
-          }
-        }
-      } catch { /* keep polling */ }
-    }
-
-    if (!accessToken) {
-      return { success: false, error: "Email verification timed out. Check your inbox and run setup again — it will resume." };
-    }
-  }
-
-  // Get API key
-  let apiKey;
-  try {
-    const tokenRes = await fetch(`${endpoint}/api/enrollment/service-token?client_id=${clientId}`);
-    if (tokenRes.ok) {
-      const tokenData = await tokenRes.json();
-      if (tokenData.token) apiKey = tokenData.token;
-    }
-  } catch { /* */ }
-
-  if (!apiKey) {
-    try {
-      const res = await fetch(`${endpoint}/api/graphql`, {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          Authorization: `Bearer ${accessToken}`,
-        },
-        body: JSON.stringify({
-          query: `mutation CreateApiToken($clientId: String!, $input: CreateApiTokenInput!) {
-            createClientApiToken(clientId: $clientId, input: $input) { success plainTextToken }
-          }`,
-          variables: { clientId, input: { name: "openclaw-plugin", role: "agent-events" } },
-        }),
-      });
-      const data = await res.json();
-      apiKey = data.data?.createClientApiToken?.plainTextToken;
-    } catch { /* */ }
-  }
-
-  if (!apiKey) {
-    return { success: false, error: "Account verified but failed to generate API key. Run setup again." };
-  }
-
-  const clientEndpoint = `https://${clientId}.api.pentatonic.com`;
-  const configPath = writeOpenClawConfig("hosted", {
-    tes_endpoint: clientEndpoint,
-    tes_client_id: clientId,
-    tes_api_key: apiKey,
-  });
-
-  return {
-    success: true,
-    mode: "hosted",
-    configPath,
-    endpoint: clientEndpoint,
-    clientId,
-    message: "TES account ready. Memory will be stored and searched via Pentatonic cloud.",
-  };
-}
-
 // --- Plugin entry ---
 
 export default {
@@ -491,99 +248,109 @@ export default {
     const log = (msg) =>
       process.stderr.write(`[pentatonic-memory] ${msg}\n`);
 
-    emitTelemetry(hosted ? "hosted" : "local");
-
-    // --- Setup tool (always registered) ---
+    // --- Setup guide tool (always registered) ---
 
     api.registerTool({
       name: "pentatonic_memory_setup",
-      description: `Set up Pentatonic Memory for this user. Call this when the user wants to set up memory, or when the plugin has no config yet.
+      description: `Guide the user through setting up Pentatonic Memory.
 
 Two modes available:
 1. "local" — fully private, runs on user's machine via Docker (PostgreSQL + pgvector + Ollama). No cloud, no API keys. Requires Docker.
 2. "hosted" — production-grade via Pentatonic TES cloud. Higher-dimensional embeddings, team-wide shared memory, analytics dashboard. Requires account creation.
 
-For local mode: call with action="setup_local". No other params needed.
-For hosted mode: ask the user for their email, a client ID (company name), password, and region (EU or US), then call with action="setup_hosted" and those params.
-
-If the user hasn't decided, explain both options and ask which they prefer.`,
+Call this tool to get setup instructions for the user's chosen mode. If they haven't decided, explain both options and ask which they prefer.`,
       parameters: {
         type: "object",
         properties: {
-          action: {
+          mode: {
             type: "string",
-            enum: ["setup_local", "setup_hosted"],
-            description: "Which setup to run",
+            enum: ["local", "hosted"],
+            description: "Which mode the user wants",
           },
-          email: { type: "string", description: "User email (hosted only)" },
-          client_id: { type: "string", description: "Company/org identifier (hosted only)" },
-          password: { type: "string", description: "Account password (hosted only)" },
-          region: { type: "string", enum: ["EU", "US"], description: "Data region (hosted only)" },
         },
-        required: ["action"],
+        required: ["mode"],
       },
-      async execute({ action, email, client_id, password, region }) {
-        if (action === "setup_local") {
-          return JSON.stringify(await runLocalSetup());
+      async execute({ mode }) {
+        if (mode === "local") {
+          return `## Local Memory Setup
+
+The user needs to run these commands in their terminal:
+
+1. Start the memory stack:
+   \`\`\`
+   npx @pentatonic-ai/ai-agent-sdk memory
+   \`\`\`
+   This starts PostgreSQL + pgvector, Ollama, and the memory server via Docker.
+
+2. Then add this to their openclaw.json:
+   \`\`\`json
+   {
+     "plugins": {
+       "slots": { "contextEngine": "pentatonic-memory" },
+       "entries": {
+         "pentatonic-memory": {
+           "enabled": true,
+           "config": {
+             "database_url": "postgres://memory:memory@localhost:5433/memory",
+             "embedding_url": "http://localhost:11435/v1",
+             "embedding_model": "nomic-embed-text",
+             "llm_url": "http://localhost:11435/v1",
+             "llm_model": "llama3.2:3b"
+           }
+         }
+       }
+     }
+   }
+   \`\`\`
+
+3. Restart OpenClaw to activate the context engine.
+
+Tell the user to run step 1 first, then help them with the config.`;
         }
-        if (action === "setup_hosted") {
-          if (!email || !client_id || !password) {
-            return JSON.stringify({
-              success: false,
-              error: "Missing required fields: email, client_id, and password are all required for hosted setup.",
-            });
-          }
-          return JSON.stringify(await runHostedSetup(email, client_id, password, region));
+
+        if (mode === "hosted") {
+          return `## Hosted TES Setup
+
+The user needs to run this command in their terminal:
+
+1. Create a TES account:
+   \`\`\`
+   npx @pentatonic-ai/ai-agent-sdk init
+   \`\`\`
+   This walks through account creation, email verification, and API key generation.
+   They'll receive credentials like:
+   - TES_ENDPOINT=https://their-company.api.pentatonic.com
+   - TES_CLIENT_ID=their-company
+   - TES_API_KEY=tes_their-company_xxxxx
+
+2. Then add this to their openclaw.json:
+   \`\`\`json
+   {
+     "plugins": {
+       "slots": { "contextEngine": "pentatonic-memory" },
+       "entries": {
+         "pentatonic-memory": {
+           "enabled": true,
+           "config": {
+             "tes_endpoint": "https://their-company.api.pentatonic.com",
+             "tes_client_id": "their-company",
+             "tes_api_key": "tes_their-company_xxxxx"
+           }
+         }
+       }
+     }
+   }
+   \`\`\`
+
+3. Restart OpenClaw to activate the context engine.
+
+Tell the user to run step 1 first, then help them fill in the config with the credentials they receive.`;
         }
-        return JSON.stringify({ success: false, error: "Unknown action" });
+
+        return "Unknown mode. Choose 'local' or 'hosted'.";
       },
     });
 
-    // --- CLI subcommand ---
-
-    if (api.registerCli) {
-      api.registerCli(
-        async ({ program }) => {
-          program
-            .command("pentatonic-memory")
-            .description("Set up Pentatonic Memory (local or hosted)")
-            .argument("[mode]", "Setup mode: local or hosted")
-            .action(async (mode) => {
-              if (mode === "local") {
-                console.log("\nSetting up local memory stack...\n");
-                const result = await runLocalSetup();
-                if (result.success) {
-                  console.log(`✓ ${result.message}`);
-                  console.log(`  Config: ${result.configPath}`);
-                  console.log(`  Models: ${result.models.join(", ")}\n`);
-                  console.log("Restart OpenClaw to activate the context engine.\n");
-                } else {
-                  console.error(`✗ ${result.error}\n`);
-                  process.exit(1);
-                }
-              } else if (mode === "hosted") {
-                console.log("\nHosted setup — use the interactive agent instead:");
-                console.log('  Tell OpenClaw: "set up pentatonic memory"\n');
-              } else {
-                console.log("\nPentatonic Memory Setup\n");
-                console.log("  openclaw pentatonic-memory local    Set up local memory (Docker)");
-                console.log("  openclaw pentatonic-memory hosted   Set up hosted TES (cloud)\n");
-                console.log('Or just tell OpenClaw: "set up pentatonic memory"\n');
-              }
-            });
-        },
-        {
-          descriptors: [
-            {
-              name: "pentatonic-memory",
-              description: "Set up Pentatonic Memory (local Docker stack or hosted TES cloud)",
-              hasSubcommands: false,
-            },
-          ],
-        }
-      );
-    }
-
     if (hosted) {
       // --- Hosted mode: TES GraphQL ---
       log("Hosted mode — routing through TES");
@@ -640,7 +407,7 @@ If the user hasn't decided, explain both options and ask which they prefer.`,
           return result ? "Memory stored." : "Failed to store memory.";
         },
       });
-    } else {
+    } else if (config.database_url) {
       // --- Local mode: direct PostgreSQL ---
       const mem = getLocalMemory(config);
       log("Local mode — direct PostgreSQL");
@@ -723,8 +490,11 @@ If the user hasn't decided, explain both options and ask which they prefer.`,
             .join("\n");
         },
       });
+    } else {
+      // --- No config: setup-only mode ---
+      log("No memory config found — setup tool available. Tell OpenClaw: 'set up pentatonic memory'");
     }
 
-    log(`Plugin registered (${hosted ? "hosted" : "local"} mode)`);
+    log(`Plugin registered (${hosted ? "hosted" : config.database_url ? "local" : "unconfigured"} mode)`);
   },
 };