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

package/packages/doctor/src/index.js

@@ -0,0 +1,33 @@
+/**
+ * @pentatonic-ai/ai-agent-sdk/doctor
+ *
+ * Generic health check runner for SDK installations.
+ *
+ * Auto-detects the install path (local memory / hosted TES / self-hosted
+ * platform), runs the appropriate built-in checks, plus any plugins the
+ * user has dropped into ~/.config/pentatonic-ai/doctor-plugins/.
+ *
+ * Each check is a small descriptor:
+ *   { name, severity: 'critical'|'warning'|'info', run: async () => result }
+ * where result is { ok, msg, detail? }.
+ *
+ * @example
+ * import { runDoctor } from '@pentatonic-ai/ai-agent-sdk/doctor';
+ * const report = await runDoctor({ path: 'auto' });
+ * console.log(report.summary);
+ */
+
+export { runDoctor } from "./runner.js";
+export { detectPath, PATHS } from "./detect.js";
+export { loadPlugins, PLUGIN_DIR } from "./plugins.js";
+export { renderHuman, renderJson } from "./output.js";
+export { universalChecks } from "./checks/universal.js";
+export { localMemoryChecks } from "./checks/local-memory.js";
+export { hostedTesChecks } from "./checks/hosted-tes.js";
+export { platformChecks } from "./checks/platform.js";
+
+export const SEVERITY = Object.freeze({
+  CRITICAL: "critical",
+  WARNING: "warning",
+  INFO: "info",
+});

package/packages/doctor/src/output.js

@@ -0,0 +1,55 @@
+/**
+ * Output renderers for doctor reports.
+ *
+ * Two formats: human (table-ish, emoji per result) and JSON (machine).
+ * Both consume the report shape from runner.js.
+ */
+
+import { SEVERITY } from "./index.js";
+
+const EMOJI = {
+  ok: "✓",
+  critical: "✗",
+  warning: "!",
+  info: "i",
+};
+
+function emojiFor(result) {
+  if (result.ok) return EMOJI.ok;
+  if (result.severity === SEVERITY.CRITICAL) return EMOJI.critical;
+  return EMOJI.warning;
+}
+
+function pad(s, width) {
+  if (s.length >= width) return s;
+  return s + " ".repeat(width - s.length);
+}
+
+export function renderHuman(report) {
+  if (!report.checks.length) {
+    return "no checks were run";
+  }
+  const width = Math.min(
+    40,
+    report.checks.reduce((m, c) => Math.max(m, c.name.length), 0)
+  );
+  const lines = [];
+  lines.push(`paths detected: ${report.paths.join(", ")}`);
+  if (report.pluginCount) {
+    lines.push(`plugins loaded: ${report.pluginCount}`);
+  }
+  lines.push("");
+  for (const r of report.checks) {
+    lines.push(`${emojiFor(r)}  ${pad(r.name, width)}  ${r.msg}`);
+  }
+  lines.push("");
+  const { ok, warning, critical, total } = report.summary;
+  lines.push(
+    `summary: ${ok} ok, ${warning} warning, ${critical} critical (of ${total})`
+  );
+  return lines.join("\n");
+}
+
+export function renderJson(report, { pretty = true } = {}) {
+  return JSON.stringify(report, null, pretty ? 2 : 0);
+}

package/packages/doctor/src/plugins.js

@@ -0,0 +1,81 @@
+/**
+ * Plugin loader for doctor.
+ *
+ * Looks in ~/.config/pentatonic-ai/doctor-plugins/ (overridable) for
+ * .mjs files and dynamically imports each one. (.js is intentionally
+ * not supported — without a sibling package.json setting "type":"module",
+ * Node treats .js as CommonJS, which can't use `export default`. Forcing
+ * .mjs sidesteps that whole class of confusion.) The default export
+ * must look like:
+ *
+ *   export default {
+ *     name: 'my-plugin',
+ *     checks: [
+ *       { name: 'thing reachable', severity: 'warning',
+ *         run: async () => ({ ok: true, msg: '...' }) },
+ *     ],
+ *   };
+ *
+ * This is how downstream agents (e.g. Optimus on the Machinegenie stack)
+ * register their own checks without forking the SDK.
+ *
+ * Bad plugins are skipped with a warning rather than aborting the run —
+ * a broken plugin should never block a doctor pass.
+ */
+
+import { existsSync, readdirSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+import { pathToFileURL } from "url";
+
+export const PLUGIN_DIR = join(
+  homedir(),
+  ".config",
+  "pentatonic-ai",
+  "doctor-plugins"
+);
+
+function isValidPlugin(mod) {
+  if (!mod || typeof mod !== "object") return false;
+  if (typeof mod.name !== "string" || !mod.name) return false;
+  if (!Array.isArray(mod.checks)) return false;
+  for (const c of mod.checks) {
+    if (!c || typeof c.name !== "string" || typeof c.run !== "function") {
+      return false;
+    }
+  }
+  return true;
+}
+
+export async function loadPlugins({ dir = PLUGIN_DIR, onError } = {}) {
+  if (!existsSync(dir)) return [];
+
+  const warn = onError || (() => {});
+
+  let entries;
+  try {
+    entries = readdirSync(dir);
+  } catch (err) {
+    warn(`could not read plugin dir ${dir}: ${err.message}`);
+    return [];
+  }
+
+  const plugins = [];
+  for (const entry of entries) {
+    if (!entry.endsWith(".mjs")) continue;
+    const filePath = join(dir, entry);
+    try {
+      const mod = await import(pathToFileURL(filePath).href);
+      const plugin = mod.default || mod;
+      if (!isValidPlugin(plugin)) {
+        warn(`${entry}: not a valid plugin (missing name/checks)`);
+        continue;
+      }
+      plugins.push(plugin);
+    } catch (err) {
+      warn(`${entry}: failed to load — ${err.message}`);
+    }
+  }
+
+  return plugins;
+}

package/packages/doctor/src/runner.js

@@ -0,0 +1,136 @@
+/**
+ * Doctor runner.
+ *
+ * Composes the active check set from detected paths + plugins, runs each
+ * check (catching its own failures so one bad check can't take the rest
+ * down), and aggregates results into a single report.
+ *
+ * Each check is shaped:
+ *   {
+ *     name: string,
+ *     severity: 'critical' | 'warning' | 'info',
+ *     run: async () => { ok: boolean, msg: string, detail?: object }
+ *   }
+ *
+ * The runner does not print anything itself — pass the returned report to
+ * renderHuman or renderJson. This keeps the runner usable from tests, MCP
+ * servers, dashboards, etc.
+ */
+
+import { detectPaths, PATHS } from "./detect.js";
+import { universalChecks } from "./checks/universal.js";
+import { localMemoryChecks } from "./checks/local-memory.js";
+import { hostedTesChecks } from "./checks/hosted-tes.js";
+import { platformChecks } from "./checks/platform.js";
+import { loadPlugins } from "./plugins.js";
+import { SEVERITY } from "./index.js";
+
+const DEFAULT_TIMEOUT_MS = 10_000;
+
+function pathChecks(path) {
+  switch (path) {
+    case PATHS.LOCAL:
+      return localMemoryChecks();
+    case PATHS.HOSTED:
+      return hostedTesChecks();
+    case PATHS.PLATFORM:
+      return platformChecks();
+    default:
+      return [];
+  }
+}
+
+async function runOne(check, timeoutMs) {
+  const start = Date.now();
+  try {
+    const result = await Promise.race([
+      Promise.resolve().then(() => check.run()),
+      new Promise((_, reject) =>
+        setTimeout(
+          () => reject(new Error(`timed out after ${timeoutMs}ms`)),
+          timeoutMs
+        )
+      ),
+    ]);
+    if (!result || typeof result.ok !== "boolean") {
+      throw new Error("check returned invalid result (missing ok:boolean)");
+    }
+    return {
+      name: check.name,
+      severity: check.severity || SEVERITY.WARNING,
+      ok: result.ok,
+      msg: result.msg || (result.ok ? "ok" : "failed"),
+      detail: result.detail || {},
+      durationMs: Date.now() - start,
+    };
+  } catch (err) {
+    return {
+      name: check.name,
+      severity: check.severity || SEVERITY.WARNING,
+      ok: false,
+      msg: `check itself failed: ${err.message}`,
+      detail: {},
+      durationMs: Date.now() - start,
+    };
+  }
+}
+
+function summarise(results) {
+  let ok = 0;
+  let warning = 0;
+  let critical = 0;
+  for (const r of results) {
+    if (r.ok) ok += 1;
+    else if (r.severity === SEVERITY.CRITICAL) critical += 1;
+    else warning += 1;
+  }
+  return { ok, warning, critical, total: results.length };
+}
+
+export async function runDoctor(opts = {}) {
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const paths = detectPaths(opts);
+
+  // Universal checks always run.
+  const checks = [...universalChecks()];
+  for (const p of paths) {
+    checks.push(...pathChecks(p));
+  }
+
+  // Plugins — opt-out via opts.plugins === false.
+  let pluginCount = 0;
+  if (opts.plugins !== false) {
+    const plugins = await loadPlugins({ dir: opts.pluginDir });
+    pluginCount = plugins.length;
+    for (const plugin of plugins) {
+      for (const check of plugin.checks || []) {
+        checks.push({
+          ...check,
+          name: `${plugin.name}: ${check.name}`,
+        });
+      }
+    }
+  }
+
+  // Allow extra checks to be passed in directly (used by tests).
+  if (Array.isArray(opts.extraChecks)) {
+    checks.push(...opts.extraChecks);
+  }
+
+  // Run sequentially to keep network probes from contending on the same
+  // hosts; a parallel mode can be added later behind opts.concurrency.
+  const results = [];
+  for (const check of checks) {
+    results.push(await runOne(check, timeoutMs));
+  }
+
+  return {
+    timestamp: new Date().toISOString(),
+    // Serialise as array so JSON.stringify produces something useful;
+    // detection logic still uses a Set internally for membership checks.
+    paths: [...paths],
+    pluginCount,
+    summary: summarise(results),
+    checks: results,
+  };
+}

package/packages/memory/migrations/005-atomic-memories.sql

@@ -0,0 +1,16 @@
+-- Migration 005: Atomic (distilled) memories
+--
+-- Adds source_id column to memory_nodes, linking distilled atomic facts
+-- back to their source (raw) memory. Raw messages go in episodic, extracted
+-- facts go in semantic with source_id pointing to the raw.
+--
+-- Atoms are searchable in the same table; source_id gives provenance
+-- and allows filtering (atoms-only vs. raw-only retrieval).
+
+ALTER TABLE memory_nodes
+  ADD COLUMN IF NOT EXISTS source_id TEXT
+    REFERENCES memory_nodes(id) ON DELETE CASCADE;
+
+CREATE INDEX IF NOT EXISTS idx_memory_nodes_source_id
+  ON memory_nodes(source_id)
+  WHERE source_id IS NOT NULL;

package/packages/memory/migrations/006-fix-vector-dim.sql

@@ -0,0 +1,97 @@
+-- Migration 006: Make embedding_vec dimension-agnostic
+--
+-- The original embedding_vec column was declared as vector(4096) assuming
+-- TES's NV-Embed-v2 model. But users running with different embedding models
+-- (e.g. nomic-embed-text at 768 dims) silently get NULL embedding_vec because
+-- the trigger's cast fails on dimension mismatch.
+--
+-- Fix: use vector without a fixed dimension so any size fits. We lose the
+-- ability to use HNSW indexes (which require fixed dims) but vector search
+-- still works via sequential scan, which is fine for local/self-hosted setups
+-- with <100k memories.
+--
+-- For TES production (4096d with HNSW), this migration is a no-op if the
+-- column is already correctly sized.
+
+-- Strategy: detect existing column definition and only resize if the
+-- configured dimension doesn't match what the running memory server will
+-- actually produce. We can't know the runtime embedding size from a SQL
+-- migration, so we pick a simple heuristic:
+--
+--   * If any rows already have a non-NULL embedding_vec, the column dim
+--     matches what's been inserted — leave it (and the HNSW index) alone.
+--   * If all embedding_vec values are NULL but JSONB embeddings exist,
+--     the cast has been failing silently. Check the JSONB dimension:
+--       - If it matches the current column dim, repopulate and keep HNSW.
+--       - If it differs, resize to dimensionless vector (loses HNSW,
+--         gains compatibility with any model).
+
+DO $$
+DECLARE
+  jsonb_dim INTEGER;
+  col_has_data BOOLEAN;
+BEGIN
+  IF NOT EXISTS (SELECT 1 FROM pg_extension WHERE extname = 'vector') THEN
+    RETURN;
+  END IF;
+
+  IF NOT EXISTS (
+    SELECT 1 FROM information_schema.columns
+    WHERE table_schema = current_schema()
+      AND table_name = 'memory_nodes'
+      AND column_name = 'embedding_vec'
+  ) THEN
+    RETURN;
+  END IF;
+
+  -- Is the column already working (any populated rows)?
+  SELECT EXISTS (SELECT 1 FROM memory_nodes WHERE embedding_vec IS NOT NULL LIMIT 1)
+    INTO col_has_data;
+
+  IF col_has_data THEN
+    -- Column + HNSW are fine as-is. Just try to repopulate anything missing.
+    UPDATE memory_nodes
+    SET embedding_vec = embedding::text::vector
+    WHERE embedding IS NOT NULL
+      AND embedding != 'null'::jsonb
+      AND embedding != '[]'::jsonb
+      AND embedding_vec IS NULL;
+    RETURN;
+  END IF;
+
+  -- Column is empty. Check JSONB dim to decide if we need to resize.
+  SELECT jsonb_array_length(embedding) INTO jsonb_dim
+  FROM memory_nodes
+  WHERE embedding IS NOT NULL AND embedding != 'null'::jsonb AND embedding != '[]'::jsonb
+  LIMIT 1;
+
+  IF jsonb_dim IS NULL THEN
+    -- No data yet; leave column as-is, nothing to repopulate
+    RETURN;
+  END IF;
+
+  -- We have JSONB data but no vector data. Try a sample cast to see if
+  -- it works against the current column type.
+  BEGIN
+    UPDATE memory_nodes
+    SET embedding_vec = embedding::text::vector
+    WHERE id = (SELECT id FROM memory_nodes WHERE embedding IS NOT NULL LIMIT 1);
+    -- Cast succeeded — column dim matches, repopulate everything else
+    UPDATE memory_nodes
+    SET embedding_vec = embedding::text::vector
+    WHERE embedding IS NOT NULL
+      AND embedding != 'null'::jsonb
+      AND embedding != '[]'::jsonb
+      AND embedding_vec IS NULL;
+  EXCEPTION WHEN OTHERS THEN
+    -- Dimension mismatch. Resize to dimensionless to unblock local setups.
+    RAISE NOTICE 'Dimension mismatch detected (JSONB is %d); resizing embedding_vec to dimensionless', jsonb_dim;
+    DROP INDEX IF EXISTS idx_memory_nodes_embedding_vec;
+    ALTER TABLE memory_nodes ALTER COLUMN embedding_vec TYPE vector USING NULL;
+    UPDATE memory_nodes
+    SET embedding_vec = embedding::text::vector
+    WHERE embedding IS NOT NULL
+      AND embedding != 'null'::jsonb
+      AND embedding != '[]'::jsonb;
+  END;
+END $$;

package/packages/memory/openclaw-plugin/__tests__/chat-turn.test.js

@@ -0,0 +1,208 @@
+/**
+ * Tests for CHAT_TURN emission + envelope handling on the PUBLISHED
+ * OpenClaw plugin (`packages/memory/openclaw-plugin/`). This is the
+ * file OpenClaw actually installs via `openclaw plugins install
+ * @pentatonic-ai/openclaw-memory-plugin`, so these tests cover the
+ * runtime path the dashboard depends on.
+ */
+
+import plugin, { _resetTurnBuffersForTest } from "../index.js";
+
+const realFetch = globalThis.fetch;
+
+function captureFetch() {
+  const calls = [];
+  globalThis.fetch = async (url, init) => {
+    const body = init?.body ? JSON.parse(init.body) : null;
+    calls.push({ url, body });
+    return {
+      ok: true,
+      status: 200,
+      json: async () => ({ data: { createModuleEvent: { success: true, eventId: "e" } } }),
+    };
+  };
+  return calls;
+}
+
+// Build a hosted engine via the plugin's register hook. The published
+// plugin reads config from api.pluginConfig (newer OpenClaw) or
+// api.config.plugins.entries[...].config (older), whichever is set.
+function makeEngine(extraConfig = {}) {
+  let factory;
+  plugin.register({
+    pluginConfig: {
+      tes_endpoint: "https://x.test",
+      tes_client_id: "c",
+      tes_api_key: "tes_c_xyz",
+      ...extraConfig,
+    },
+    registerTool: () => {},
+    registerContextEngine: (_name, fn) => {
+      factory = fn;
+    },
+  });
+  if (!factory) throw new Error("plugin did not register a context engine");
+  return factory();
+}
+
+afterEach(() => {
+  globalThis.fetch = realFetch;
+  _resetTurnBuffersForTest();
+});
+
+describe("openclaw-memory-plugin — hosted CHAT_TURN via afterTurn", () => {
+  it("emits CHAT_TURN when afterTurn is called with user+assistant messages", async () => {
+    const calls = captureFetch();
+    const engine = makeEngine();
+
+    await engine.afterTurn({
+      sessionId: "sess-1",
+      messages: [
+        { role: "user", content: "hi" },
+        {
+          role: "assistant",
+          content: "hello",
+          model: "claude-3-5",
+          usage: { input_tokens: 10, output_tokens: 5 },
+        },
+      ],
+      prePromptMessageCount: 0,
+    });
+
+    const turn = calls.find(
+      (c) =>
+        c.body?.variables?.moduleId === "conversation-analytics" &&
+        c.body?.variables?.input?.eventType === "CHAT_TURN"
+    );
+    expect(turn).toBeDefined();
+    const attrs = turn.body.variables.input.data.attributes;
+    expect(attrs.user_message).toBe("hi");
+    expect(attrs.assistant_response).toBe("hello");
+    expect(attrs.model).toBe("claude-3-5");
+    expect(attrs.usage).toEqual({ input_tokens: 10, output_tokens: 5 });
+    expect(attrs.turn_number).toBe(1);
+    expect(attrs.source).toBe("openclaw-plugin");
+  });
+
+  it("also emits STORE_MEMORY for retrieval (both events fire)", async () => {
+    const calls = captureFetch();
+    const engine = makeEngine();
+
+    await engine.afterTurn({
+      sessionId: "sess-2",
+      messages: [
+        { role: "user", content: "question" },
+        { role: "assistant", content: "answer" },
+      ],
+      prePromptMessageCount: 0,
+    });
+
+    const storeMemory = calls.filter(
+      (c) => c.body?.variables?.moduleId === "deep-memory"
+    );
+    const chatTurn = calls.filter(
+      (c) => c.body?.variables?.moduleId === "conversation-analytics"
+    );
+    expect(storeMemory.length).toBeGreaterThan(0);
+    expect(chatTurn.length).toBe(1);
+  });
+
+  it("handles content-block arrays (Anthropic-style) correctly", async () => {
+    const calls = captureFetch();
+    const engine = makeEngine();
+
+    await engine.afterTurn({
+      sessionId: "sess-blocks",
+      messages: [
+        { role: "user", content: [{ type: "text", text: "what do i like?" }] },
+        { role: "assistant", content: [{ type: "text", text: "coffee" }] },
+      ],
+      prePromptMessageCount: 0,
+    });
+
+    const attrs = calls.find(
+      (c) => c.body?.variables?.moduleId === "conversation-analytics"
+    ).body.variables.input.data.attributes;
+    expect(attrs.user_message).toBe("what do i like?");
+    expect(attrs.assistant_response).toBe("coffee");
+  });
+
+  it("extracts tool_calls from wrapped Anthropic raw response", async () => {
+    const calls = captureFetch();
+    const engine = makeEngine();
+
+    await engine.afterTurn({
+      sessionId: "sess-tools",
+      messages: [
+        { role: "user", content: "search" },
+        {
+          role: "assistant",
+          content: "looking",
+          raw: {
+            content: [
+              { type: "text", text: "looking" },
+              { type: "tool_use", name: "search", input: { q: "cheese" } },
+            ],
+          },
+        },
+      ],
+      prePromptMessageCount: 0,
+    });
+
+    const attrs = calls.find(
+      (c) => c.body?.variables?.moduleId === "conversation-analytics"
+    ).body.variables.input.data.attributes;
+    expect(attrs.tool_calls).toEqual([
+      { tool: "search", args: { q: "cheese" } },
+    ]);
+  });
+
+  it("increments turn_number across multiple afterTurn invocations in the same session", async () => {
+    const calls = captureFetch();
+    const engine = makeEngine();
+
+    for (let i = 0; i < 3; i++) {
+      await engine.afterTurn({
+        sessionId: "sess-multi",
+        messages: [
+          { role: "user", content: `q${i}` },
+          { role: "assistant", content: `a${i}` },
+        ],
+        prePromptMessageCount: 0,
+      });
+    }
+
+    const turnNumbers = calls
+      .filter(
+        (c) => c.body?.variables?.moduleId === "conversation-analytics"
+      )
+      .map((c) => c.body.variables.input.data.attributes.turn_number);
+    expect(turnNumbers).toEqual([1, 2, 3]);
+  });
+
+  it("only uses prePromptMessageCount=N to slice new messages", async () => {
+    const calls = captureFetch();
+    const engine = makeEngine();
+
+    await engine.afterTurn({
+      sessionId: "sess-slice",
+      messages: [
+        { role: "user", content: "old-user" },
+        { role: "assistant", content: "old-asst" },
+        { role: "user", content: "new-user" },
+        { role: "assistant", content: "new-asst" },
+      ],
+      prePromptMessageCount: 2,
+    });
+
+    const turn = calls.find(
+      (c) => c.body?.variables?.moduleId === "conversation-analytics"
+    );
+    expect(turn.body.variables.input.data.attributes.user_message).toBe(
+      "new-user"
+    );
+    expect(turn.body.variables.input.data.attributes.assistant_response).toBe(
+      "new-asst"
+    );
+  });
+});