@pentatonic-ai/ai-agent-sdk 0.4.9 → 0.5.0

package/packages/doctor/src/checks/local-memory.js

@@ -0,0 +1,290 @@
+/**
+ * Local Memory path checks.
+ *
+ * Targets the stack started by `npx @pentatonic-ai/ai-agent-sdk memory`:
+ *   - PostgreSQL with pgvector
+ *   - Ollama (or any OpenAI-compatible embedding + chat endpoint)
+ *   - Memory MCP server on PORT (default 3333)
+ *
+ * Configuration is read from env vars used by packages/memory/src/server.js
+ * (DATABASE_URL, EMBEDDING_URL/MODEL, LLM_URL/MODEL, PORT, API_KEY) so this
+ * stays drift-free with the actual server.
+ */
+
+import { SEVERITY } from "../index.js";
+
+async function fetchWithTimeout(url, opts = {}, timeoutMs = 5000) {
+  return await fetch(url, {
+    ...opts,
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+}
+
+function checkPostgres() {
+  return {
+    name: "postgres reachable",
+    severity: SEVERITY.CRITICAL,
+    run: async () => {
+      const dsn = process.env.DATABASE_URL;
+      if (!dsn) {
+        return {
+          ok: false,
+          msg: "DATABASE_URL not set",
+        };
+      }
+      // Lazy-import pg so users on hosted/platform paths don't pay the cost.
+      let pg;
+      try {
+        pg = (await import("pg")).default;
+      } catch {
+        return {
+          ok: false,
+          msg: "'pg' not installed — run `npm install pg`",
+        };
+      }
+      const client = new pg.Client({ connectionString: dsn });
+      try {
+        await client.connect();
+        const v = await client.query("SELECT version()");
+        return {
+          ok: true,
+          msg: v.rows[0].version.split(",")[0],
+          detail: { version: v.rows[0].version },
+        };
+      } catch (err) {
+        return {
+          ok: false,
+          msg: err.message,
+        };
+      } finally {
+        await client.end().catch(() => {});
+      }
+    },
+  };
+}
+
+function checkPgvector() {
+  return {
+    name: "pgvector extension",
+    severity: SEVERITY.CRITICAL,
+    run: async () => {
+      const dsn = process.env.DATABASE_URL;
+      if (!dsn) return { ok: false, msg: "DATABASE_URL not set" };
+      let pg;
+      try {
+        pg = (await import("pg")).default;
+      } catch {
+        return { ok: false, msg: "'pg' not installed" };
+      }
+      const client = new pg.Client({ connectionString: dsn });
+      try {
+        await client.connect();
+        const r = await client.query(
+          "SELECT extversion FROM pg_extension WHERE extname='vector'"
+        );
+        if (!r.rowCount) {
+          return {
+            ok: false,
+            msg: "pgvector not installed — run CREATE EXTENSION vector",
+          };
+        }
+        return {
+          ok: true,
+          msg: `pgvector ${r.rows[0].extversion}`,
+          detail: { version: r.rows[0].extversion },
+        };
+      } catch (err) {
+        return { ok: false, msg: err.message };
+      } finally {
+        await client.end().catch(() => {});
+      }
+    },
+  };
+}
+
+function checkMigrations() {
+  return {
+    name: "schema migrations applied",
+    severity: SEVERITY.WARNING,
+    run: async () => {
+      const dsn = process.env.DATABASE_URL;
+      if (!dsn) return { ok: false, msg: "DATABASE_URL not set" };
+      let pg;
+      try {
+        pg = (await import("pg")).default;
+      } catch {
+        return { ok: false, msg: "'pg' not installed" };
+      }
+      const client = new pg.Client({ connectionString: dsn });
+      try {
+        await client.connect();
+        // The migration runner creates schema_migrations on first apply.
+        const r = await client.query(
+          "SELECT count(*) AS n FROM schema_migrations"
+        );
+        const n = parseInt(r.rows[0].n, 10);
+        if (n === 0) {
+          return {
+            ok: false,
+            msg: "schema_migrations is empty — start the memory server to run migrations",
+          };
+        }
+        return { ok: true, msg: `${n} migrations applied`, detail: { n } };
+      } catch (err) {
+        if (/relation .* does not exist/.test(err.message)) {
+          return {
+            ok: false,
+            msg: "schema_migrations table missing — start the memory server first",
+          };
+        }
+        return { ok: false, msg: err.message };
+      } finally {
+        await client.end().catch(() => {});
+      }
+    },
+  };
+}
+
+function checkEmbeddingEndpoint() {
+  return {
+    name: "embedding endpoint",
+    severity: SEVERITY.CRITICAL,
+    run: async () => {
+      const url = process.env.EMBEDDING_URL;
+      const model = process.env.EMBEDDING_MODEL;
+      if (!url || !model) {
+        return {
+          ok: false,
+          msg: "EMBEDDING_URL or EMBEDDING_MODEL not set",
+        };
+      }
+      // Probe with a 1-token embed call against the OpenAI-compatible API.
+      try {
+        const headers = { "Content-Type": "application/json" };
+        if (process.env.API_KEY) {
+          headers.Authorization = `Bearer ${process.env.API_KEY}`;
+        }
+        const res = await fetchWithTimeout(
+          `${url.replace(/\/$/, "")}/embeddings`,
+          {
+            method: "POST",
+            headers,
+            body: JSON.stringify({ model, input: "ping" }),
+          }
+        );
+        if (!res.ok) {
+          const body = await res.text().catch(() => "");
+          return {
+            ok: false,
+            msg: `HTTP ${res.status}: ${body.slice(0, 120)}`,
+          };
+        }
+        const data = await res.json();
+        const dim = data.data?.[0]?.embedding?.length;
+        if (!dim) {
+          return {
+            ok: false,
+            msg: "endpoint responded but returned no embedding",
+          };
+        }
+        return {
+          ok: true,
+          msg: `${model} ok (${dim}-dim)`,
+          detail: { url, model, dim },
+        };
+      } catch (err) {
+        return { ok: false, msg: err.message };
+      }
+    },
+  };
+}
+
+function checkLlmEndpoint() {
+  return {
+    name: "llm endpoint",
+    severity: SEVERITY.CRITICAL,
+    run: async () => {
+      const url = process.env.LLM_URL;
+      const model = process.env.LLM_MODEL;
+      if (!url || !model) {
+        return {
+          ok: false,
+          msg: "LLM_URL or LLM_MODEL not set",
+        };
+      }
+      // /models is cheap and present on every OpenAI-compatible server.
+      try {
+        const headers = {};
+        if (process.env.API_KEY) {
+          headers.Authorization = `Bearer ${process.env.API_KEY}`;
+        }
+        const res = await fetchWithTimeout(
+          `${url.replace(/\/$/, "")}/models`,
+          { headers }
+        );
+        if (!res.ok) {
+          return { ok: false, msg: `HTTP ${res.status}` };
+        }
+        const data = await res.json();
+        const ids = (data.data || []).map((m) => m.id);
+        if (model && !ids.includes(model)) {
+          return {
+            ok: false,
+            msg: `${model} not loaded; available: ${ids.slice(0, 3).join(", ")}`,
+            detail: { url, requested: model, available: ids },
+          };
+        }
+        return {
+          ok: true,
+          msg: `${model} loaded`,
+          detail: { url, model },
+        };
+      } catch (err) {
+        return { ok: false, msg: err.message };
+      }
+    },
+  };
+}
+
+function checkMemoryServer() {
+  return {
+    name: "memory server",
+    severity: SEVERITY.WARNING,
+    run: async () => {
+      // The MCP server uses stdio by default but exposes PORT for HTTP/SSE.
+      // If PORT isn't bound we can't probe — that's not an error, just info.
+      const port = process.env.PORT || "3333";
+      const url = `http://127.0.0.1:${port}/`;
+      try {
+        const res = await fetchWithTimeout(url, {}, 2000);
+        return {
+          ok: true,
+          msg: `port ${port} reachable (HTTP ${res.status})`,
+          detail: { url, status: res.status },
+        };
+      } catch (err) {
+        // Connection refused is the common case when the server is run
+        // via stdio only — surface as info so users aren't alarmed.
+        if (/ECONNREFUSED|fetch failed/.test(err.message)) {
+          return {
+            ok: true,
+            msg: `port ${port} not bound (running via stdio? — skipped)`,
+            detail: { url },
+          };
+        }
+        return { ok: false, msg: err.message };
+      }
+    },
+  };
+}
+
+export function localMemoryChecks() {
+  return [
+    checkPostgres(),
+    checkPgvector(),
+    checkMigrations(),
+    checkEmbeddingEndpoint(),
+    checkLlmEndpoint(),
+    checkMemoryServer(),
+  ];
+}

package/packages/doctor/src/checks/platform.js

@@ -0,0 +1,170 @@
+/**
+ * Self-hosted Pentatonic platform checks.
+ *
+ * The full platform layers HybridRAG + Qdrant + Neo4j + a vLLM/Ollama stack
+ * on top of the Local-Memory pieces. URLs are entirely env-driven — no
+ * container names hardcoded — so this works whether the user runs Pip,
+ * Machinegenie, or any other instance with a different docker-compose
+ * naming scheme.
+ *
+ * Required env (all optional individually; check is skipped if missing):
+ *   HYBRIDRAG_URL    — e.g. http://hybridrag:8031
+ *   QDRANT_URL       — e.g. http://qdrant:6333
+ *   NEO4J_HTTP       — e.g. http://neo4j:7474
+ *   NEO4J_USER       — defaults to 'neo4j'
+ *   NEO4J_PASSWORD   — required if NEO4J_HTTP set
+ *   VLLM_URL         — e.g. http://host.docker.internal:8001
+ */
+
+import { SEVERITY } from "../index.js";
+
+async function fetchWithTimeout(url, opts = {}, timeoutMs = 5000) {
+  return await fetch(url, {
+    ...opts,
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+}
+
+function checkHybridrag() {
+  return {
+    name: "hybridrag reachable",
+    severity: SEVERITY.CRITICAL,
+    run: async () => {
+      const url = process.env.HYBRIDRAG_URL;
+      if (!url) {
+        return { ok: true, msg: "HYBRIDRAG_URL not set (skipped)" };
+      }
+      try {
+        const res = await fetchWithTimeout(`${url.replace(/\/$/, "")}/health`);
+        if (res.ok) return { ok: true, msg: `${url} healthy` };
+        // Some deployments don't expose /health — fall back to a search probe.
+        const probe = await fetchWithTimeout(
+          `${url.replace(/\/$/, "")}/v1/search`,
+          {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ query: "ping", limit: 1 }),
+          }
+        );
+        if (probe.ok) return { ok: true, msg: `${url} healthy (search probe)` };
+        return { ok: false, msg: `HTTP ${probe.status}` };
+      } catch (err) {
+        return { ok: false, msg: err.message };
+      }
+    },
+  };
+}
+
+function checkQdrant() {
+  return {
+    name: "qdrant reachable",
+    severity: SEVERITY.WARNING,
+    run: async () => {
+      const url = process.env.QDRANT_URL;
+      if (!url) {
+        return { ok: true, msg: "QDRANT_URL not set (skipped)" };
+      }
+      try {
+        const res = await fetchWithTimeout(
+          `${url.replace(/\/$/, "")}/collections`
+        );
+        if (!res.ok) return { ok: false, msg: `HTTP ${res.status}` };
+        const data = await res.json();
+        const cols = (data.result?.collections || []).map((c) => c.name);
+        return {
+          ok: true,
+          msg: `${cols.length} collections: ${cols.slice(0, 5).join(", ")}${cols.length > 5 ? ", ..." : ""}`,
+          detail: { collections: cols },
+        };
+      } catch (err) {
+        return { ok: false, msg: err.message };
+      }
+    },
+  };
+}
+
+function checkNeo4j() {
+  return {
+    name: "neo4j reachable",
+    severity: SEVERITY.WARNING,
+    run: async () => {
+      const url = process.env.NEO4J_HTTP;
+      if (!url) {
+        return { ok: true, msg: "NEO4J_HTTP not set (skipped)" };
+      }
+      const user = process.env.NEO4J_USER || "neo4j";
+      const pw = process.env.NEO4J_PASSWORD || process.env.NEO4J_PW;
+      if (!pw) {
+        return {
+          ok: false,
+          msg: "NEO4J_PASSWORD not set (NEO4J_HTTP requires auth)",
+        };
+      }
+      try {
+        const auth = Buffer.from(`${user}:${pw}`).toString("base64");
+        const res = await fetchWithTimeout(
+          `${url.replace(/\/$/, "")}/db/neo4j/tx/commit`,
+          {
+            method: "POST",
+            headers: {
+              "Content-Type": "application/json",
+              Authorization: `Basic ${auth}`,
+            },
+            body: JSON.stringify({
+              statements: [{ statement: "RETURN 1 AS ok" }],
+            }),
+          }
+        );
+        if (res.status === 401) {
+          return { ok: false, msg: "auth rejected — check NEO4J_PASSWORD" };
+        }
+        if (!res.ok) return { ok: false, msg: `HTTP ${res.status}` };
+        const data = await res.json();
+        if (data.errors?.length) {
+          return {
+            ok: false,
+            msg: `query error: ${data.errors[0].message?.slice(0, 80)}`,
+          };
+        }
+        return { ok: true, msg: "ok" };
+      } catch (err) {
+        return { ok: false, msg: err.message };
+      }
+    },
+  };
+}
+
+function checkVllm() {
+  return {
+    name: "vllm reachable",
+    severity: SEVERITY.WARNING,
+    run: async () => {
+      const url = process.env.VLLM_URL;
+      if (!url) {
+        return { ok: true, msg: "VLLM_URL not set (skipped)" };
+      }
+      try {
+        const res = await fetchWithTimeout(
+          `${url.replace(/\/$/, "")}/v1/models`
+        );
+        if (!res.ok) return { ok: false, msg: `HTTP ${res.status}` };
+        const data = await res.json();
+        const ids = (data.data || []).map((m) => m.id);
+        if (!ids.length) {
+          return { ok: false, msg: "no models loaded" };
+        }
+        return {
+          ok: true,
+          msg: `serving ${ids.join(", ")}`,
+          detail: { models: ids },
+        };
+      } catch (err) {
+        return { ok: false, msg: err.message };
+      }
+    },
+  };
+}
+
+export function platformChecks() {
+  return [checkHybridrag(), checkQdrant(), checkNeo4j(), checkVllm()];
+}

package/packages/doctor/src/checks/universal.js

@@ -0,0 +1,121 @@
+/**
+ * Universal checks — apply regardless of install path.
+ *
+ * Kept deliberately small: things that any SDK user benefits from
+ * regardless of which path they're on.
+ */
+
+import { statfsSync, statSync } from "fs";
+import { join } from "path";
+import { homedir, tmpdir } from "os";
+import { existsSync } from "fs";
+import { SEVERITY } from "../index.js";
+
+function checkNodeVersion() {
+  return {
+    name: "node version",
+    severity: SEVERITY.WARNING,
+    run: async () => {
+      const v = process.versions.node;
+      const major = parseInt(v.split(".")[0], 10);
+      // The SDK's package.json doesn't pin engines, but the memory subsystem
+      // uses fetch and top-level await — needs ≥ 18.
+      if (major < 18) {
+        return {
+          ok: false,
+          msg: `Node ${v} — SDK needs ≥18`,
+          detail: { version: v, major },
+        };
+      }
+      return { ok: true, msg: `Node ${v}`, detail: { version: v } };
+    },
+  };
+}
+
+function checkDiskSpace() {
+  return {
+    name: "disk space",
+    severity: SEVERITY.WARNING,
+    run: async () => {
+      const targets = [homedir(), tmpdir()];
+      const detail = {};
+      const tight = [];
+      for (const p of targets) {
+        try {
+          const s = statfsSync(p);
+          const free = Number(s.bavail) * Number(s.bsize);
+          const total = Number(s.blocks) * Number(s.bsize);
+          if (!total) continue;
+          const pctFree = (free / total) * 100;
+          detail[p] = `${pctFree.toFixed(1)}% free`;
+          if (pctFree < 10) {
+            tight.push(`${p}: ${pctFree.toFixed(1)}% free`);
+          }
+        } catch {
+          // statfsSync can be missing on older Node; skip silently
+        }
+      }
+      if (tight.length) {
+        return {
+          ok: false,
+          msg: tight.join("; "),
+          detail,
+        };
+      }
+      const summary = Object.entries(detail)
+        .map(([k, v]) => `${k}=${v}`)
+        .join("; ");
+      return { ok: true, msg: summary || "skipped", detail };
+    },
+  };
+}
+
+function checkConfigPerms() {
+  return {
+    name: "config file perms",
+    severity: SEVERITY.CRITICAL,
+    run: async () => {
+      // Files most likely to contain credentials. Each is optional;
+      // we only fail if a file exists with overly-permissive mode.
+      const candidates = [
+        join(homedir(), ".claude", "tes-memory.local.md"),
+        join(homedir(), ".claude-pentatonic", "tes-memory.local.md"),
+        join(homedir(), ".config", "pentatonic-ai", "config.json"),
+      ];
+      const bad = [];
+      const checked = [];
+      for (const f of candidates) {
+        if (!existsSync(f)) continue;
+        checked.push(f);
+        const mode = statSync(f).mode & 0o777;
+        // Anything readable by group/other on a credential file is too open.
+        if (mode & 0o077) {
+          bad.push(`${f}: mode ${mode.toString(8)}`);
+        }
+      }
+      if (bad.length) {
+        return {
+          ok: false,
+          msg: `${bad.length} config file(s) world-readable; chmod 600`,
+          detail: { offenders: bad },
+        };
+      }
+      if (!checked.length) {
+        return {
+          ok: true,
+          msg: "no SDK config files present (skipped)",
+          detail: { checked: [] },
+        };
+      }
+      return {
+        ok: true,
+        msg: `${checked.length} config file(s) ok`,
+        detail: { checked },
+      };
+    },
+  };
+}
+
+export function universalChecks() {
+  return [checkNodeVersion(), checkDiskSpace(), checkConfigPerms()];
+}

package/packages/doctor/src/detect.js

@@ -0,0 +1,102 @@
+/**
+ * Install-path detection.
+ *
+ * The SDK supports three deployment paths (see README "Overview"). Doctor
+ * needs to know which one this user is on so it only runs relevant checks.
+ *
+ * Detection signals (in priority order):
+ *  1. Explicit override via opts.path or PENTATONIC_DOCTOR_PATH env var.
+ *  2. Hosted TES — TES_ENDPOINT + TES_API_KEY both set in env.
+ *  3. Self-hosted platform — HYBRIDRAG_URL set, OR a Pentatonic platform
+ *     config file present (~/.openclaw/openclaw.json).
+ *  4. Local memory — DATABASE_URL points at a memory-shaped DSN, OR
+ *     ~/.claude/tes-memory.local.md exists, OR Local-Memory env vars set.
+ *  5. Fallback: 'unknown' — only universal checks run.
+ *
+ * Multiple paths can be active at once (e.g. an Optimus install runs both
+ * the platform stack AND has a hosted TES key). detectPaths() returns the
+ * full set; detectPath() returns the primary one for human-friendly output.
+ */
+
+import { existsSync as realExistsSync } from "fs";
+import { join } from "path";
+import { homedir as realHomedir } from "os";
+
+export const PATHS = Object.freeze({
+  LOCAL: "local",
+  HOSTED: "hosted",
+  PLATFORM: "platform",
+  UNKNOWN: "unknown",
+});
+
+const VALID = new Set(Object.values(PATHS));
+
+/**
+ * @param {object} opts
+ * @param {object} [opts.env] - process.env override; if set, filesystem
+ *   detection is also disabled so tests get deterministic results without
+ *   needing to mock the real homedir.
+ * @param {string} [opts.path] - explicit path or 'auto'
+ * @param {Function} [opts.fileExists] - test seam for filesystem probes
+ * @param {string} [opts.homedir] - test seam for homedir
+ */
+export function detectPaths(opts = {}) {
+  const env = opts.env || process.env;
+  const usingFakeEnv = Boolean(opts.env);
+  const fileExists = opts.fileExists ||
+    (usingFakeEnv ? () => false : realExistsSync);
+  const home = opts.homedir || realHomedir();
+
+  // Explicit override wins.
+  const override = opts.path || env.PENTATONIC_DOCTOR_PATH;
+  if (override && override !== "auto") {
+    if (!VALID.has(override)) {
+      throw new Error(
+        `Unknown path '${override}'. Valid: ${[...VALID].join(", ")}, auto`
+      );
+    }
+    return new Set([override]);
+  }
+
+  const found = new Set();
+
+  if (env.TES_ENDPOINT && env.TES_API_KEY) {
+    found.add(PATHS.HOSTED);
+  }
+
+  const platformConfig = join(home, ".openclaw", "openclaw.json");
+  if (env.HYBRIDRAG_URL || fileExists(platformConfig)) {
+    found.add(PATHS.PLATFORM);
+  }
+
+  const localConfig = join(home, ".claude", "tes-memory.local.md");
+  const looksLocal =
+    (env.DATABASE_URL && env.EMBEDDING_URL && env.LLM_URL) ||
+    fileExists(localConfig);
+  if (looksLocal) {
+    found.add(PATHS.LOCAL);
+  }
+
+  if (!found.size) {
+    found.add(PATHS.UNKNOWN);
+  }
+
+  return found;
+}
+
+/**
+ * @returns the primary detected path for display purposes.
+ */
+export function detectPath(opts = {}) {
+  const paths = detectPaths(opts);
+  // Priority: platform > hosted > local > unknown.
+  for (const p of [
+    PATHS.PLATFORM,
+    PATHS.HOSTED,
+    PATHS.LOCAL,
+    PATHS.UNKNOWN,
+  ]) {
+    if (paths.has(p)) return p;
+  }
+  return PATHS.UNKNOWN;
+}