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

package/README.md

@@ -31,6 +31,7 @@
 - [SDK: Wrap Your LLM Client](#sdk-wrap-your-llm-client)
 - [Supported Providers](#supported-providers)
 - [API Reference](#api-reference)
+- [Health Checks (`doctor`)](#health-checks-doctor)
 - [Architecture](#architecture)
 
 ## Overview
@@ -325,6 +326,64 @@ import { normalizeResponse } from "@pentatonic-ai/ai-agent-sdk";
 const { content, model, usage, toolCalls } = normalizeResponse(openaiResponse);
 ```
 
+## Health Checks (`doctor`)
+
+Run a full health check of your SDK install at any time:
+
+```bash
+npx @pentatonic-ai/ai-agent-sdk doctor
+```
+
+`doctor` auto-detects which install path you're on (Local Memory, Hosted
+TES, or self-hosted Pentatonic platform) and runs only the checks that
+apply. Exit code is `0` for all-clear, `1` for warnings, `2` for critical.
+
+Common flags:
+
+```bash
+npx @pentatonic-ai/ai-agent-sdk doctor --json     # machine-readable
+npx @pentatonic-ai/ai-agent-sdk doctor --alert    # silent unless issues
+npx @pentatonic-ai/ai-agent-sdk doctor --no-plugins
+npx @pentatonic-ai/ai-agent-sdk doctor --path local
+```
+
+What gets checked:
+
+- **Universal** — Node version, disk space, SDK config-file permissions
+- **Local Memory** — Postgres + pgvector + migrations, embedding/LLM
+  endpoints, memory server port
+- **Hosted TES** — endpoint reachable, API key authenticates
+- **Self-hosted platform** — HybridRAG, Qdrant, Neo4j, vLLM (each
+  optional, skipped when its env var is unset)
+
+### Plugins
+
+Drop a `.mjs` file into `~/.config/pentatonic-ai/doctor-plugins/` to add
+your own checks. Useful for app-specific things — internal APIs, ingest
+freshness, custom infrastructure — without forking the SDK.
+
+```js
+// ~/.config/pentatonic-ai/doctor-plugins/my-app.mjs
+export default {
+  name: "my-app",
+  checks: [
+    {
+      name: "internal API",
+      severity: "warning",
+      run: async () => {
+        const res = await fetch("https://internal/health");
+        return res.ok
+          ? { ok: true, msg: "200 OK" }
+          : { ok: false, msg: `HTTP ${res.status}` };
+      },
+    },
+  ],
+};
+```
+
+See [`packages/doctor/README.md`](packages/doctor/README.md) for the full
+plugin contract and programmatic API.
+
 ## Architecture
 
 ```

package/bin/cli.js

@@ -12,17 +12,58 @@ function parseArgs() {
   const args = process.argv.slice(2);
   const flags = {};
   for (let i = 0; i < args.length; i++) {
-    if (args[i] === "--endpoint" && args[i + 1]) {
-      flags.endpoint = args[i + 1];
-      i++;
-    } else if (args[i].startsWith("--endpoint=")) {
-      flags.endpoint = args[i].split("=")[1];
-    } else if (!args[i].startsWith("--")) {
-      flags.command = args[i];
+    const a = args[i];
+    if (a === "--endpoint" && args[i + 1]) {
+      flags.endpoint = args[++i];
+    } else if (a.startsWith("--endpoint=")) {
+      flags.endpoint = a.split("=")[1];
+    } else if (a === "--path" && args[i + 1]) {
+      flags.path = args[++i];
+    } else if (a.startsWith("--path=")) {
+      flags.path = a.split("=")[1];
+    } else if (a === "--timeout" && args[i + 1]) {
+      flags.timeout = parseInt(args[++i], 10);
+    } else if (a.startsWith("--timeout=")) {
+      flags.timeout = parseInt(a.split("=")[1], 10);
+    } else if (a === "--json") {
+      flags.json = true;
+    } else if (a === "--alert") {
+      flags.alert = true;
+    } else if (a === "--no-plugins") {
+      flags.noPlugins = true;
+    } else if (!a.startsWith("--")) {
+      flags.command = a;
     }
   }
   return flags;
 }
+
+async function runDoctorCommand(flags) {
+  // Lazy-load to keep doctor's pg dep optional for users who only run
+  // `npx ai-agent-sdk init` or `memory`.
+  const { runDoctor, renderHuman, renderJson } = await import(
+    "../packages/doctor/src/index.js"
+  );
+
+  const report = await runDoctor({
+    path: flags.path || "auto",
+    plugins: !flags.noPlugins,
+    timeoutMs: flags.timeout,
+  });
+
+  const hasIssues = report.summary.warning + report.summary.critical > 0;
+  if (flags.alert && !hasIssues) return 0;
+
+  if (flags.json) {
+    process.stdout.write(renderJson(report) + "\n");
+  } else {
+    process.stdout.write(renderHuman(report) + "\n");
+  }
+
+  if (report.summary.critical > 0) return 2;
+  if (report.summary.warning > 0) return 1;
+  return 0;
+}
 const POLL_INTERVAL_MS = 3000;
 const POLL_TIMEOUT_MS = 300000; // 5 minutes
 
@@ -33,13 +74,19 @@ function ask(question) {
 }
 
 function askSecret(question) {
+  // Non-TTY fallback: piped/redirected input can't use raw mode.
+  // rl.close() would discard buffered stdin, so use readline directly instead.
+  if (!process.stdin.isTTY) {
+    return new Promise((resolve) => rl.question(question, resolve));
+  }
+
   return new Promise((resolve) => {
     // Close readline so it stops echoing input
     rl.close();
 
     process.stdout.write(question);
     const stdin = process.stdin;
-    if (stdin.isTTY) stdin.setRawMode(true);
+    stdin.setRawMode(true);
     stdin.resume();
 
     let input = "";
@@ -47,7 +94,7 @@ function askSecret(question) {
       const c = ch.toString();
       if (c === "\n" || c === "\r") {
         stdin.removeListener("data", onData);
-        if (stdin.isTTY) stdin.setRawMode(false);
+        stdin.setRawMode(false);
         stdin.pause();
         process.stdout.write("\n");
         // Recreate readline for subsequent prompts
@@ -248,6 +295,12 @@ async function main() {
     return;
   }
 
+  if (flags.command === "doctor") {
+    const code = await runDoctorCommand(flags);
+    rl.close();
+    process.exit(code);
+  }
+
   if (flags.command !== "init") {
     console.log(`
 @pentatonic-ai/ai-agent-sdk
@@ -255,8 +308,16 @@ async function main() {
 Usage:
   npx @pentatonic-ai/ai-agent-sdk init                    Set up hosted TES account
   npx @pentatonic-ai/ai-agent-sdk memory                  Set up local memory stack
+  npx @pentatonic-ai/ai-agent-sdk doctor                  Run health checks (exit 0/1/2)
   npx @pentatonic-ai/ai-agent-sdk init --endpoint URL     Use a custom TES endpoint
 
+doctor flags:
+  --json                  Emit a JSON report
+  --alert                 Suppress output when all green
+  --no-plugins            Skip ~/.config/pentatonic-ai/doctor-plugins/*
+  --path local|hosted|platform|auto
+  --timeout <ms>          Per-check timeout (default 10000)
+
 For docs, see https://api.pentatonic.com
     `);
     process.exit(0);

package/dist/index.cjs

@@ -53,6 +53,16 @@ function empty() {
     toolCalls: []
   };
 }
+function extractCacheUsage(usage) {
+  const out = {};
+  if (typeof usage.cache_read_input_tokens === "number") {
+    out.cache_read_input_tokens = usage.cache_read_input_tokens;
+  }
+  if (typeof usage.cache_creation_input_tokens === "number") {
+    out.cache_creation_input_tokens = usage.cache_creation_input_tokens;
+  }
+  return out;
+}
 function normalizeOpenAI(raw) {
   const message = raw.choices?.[0]?.message || {};
   const usage = raw.usage || {};
@@ -87,7 +97,8 @@ function normalizeAnthropic(raw) {
     model: raw.model || null,
     usage: {
       prompt_tokens: usage.input_tokens || 0,
-      completion_tokens: usage.output_tokens || 0
+      completion_tokens: usage.output_tokens || 0,
+      ...extractCacheUsage(usage)
     },
     toolCalls
   };
@@ -262,18 +273,27 @@ var Session = class {
   _reset() {
     this._promptTokens = 0;
     this._completionTokens = 0;
+    this._cacheReadTokens = 0;
+    this._cacheCreateTokens = 0;
     this._rounds = 0;
     this._toolCalls = [];
     this._model = null;
     this._systemPrompt = null;
   }
   get totalUsage() {
-    return {
+    const usage = {
       prompt_tokens: this._promptTokens,
       completion_tokens: this._completionTokens,
-      total_tokens: this._promptTokens + this._completionTokens,
+      total_tokens: this._promptTokens + this._completionTokens + this._cacheReadTokens + this._cacheCreateTokens,
       ai_rounds: this._rounds
     };
+    if (this._cacheReadTokens) {
+      usage.cache_read_input_tokens = this._cacheReadTokens;
+    }
+    if (this._cacheCreateTokens) {
+      usage.cache_creation_input_tokens = this._cacheCreateTokens;
+    }
+    return usage;
   }
   get toolCalls() {
     return this._toolCalls;
@@ -283,6 +303,8 @@ var Session = class {
     const round = this._rounds;
     this._promptTokens += normalized.usage.prompt_tokens;
     this._completionTokens += normalized.usage.completion_tokens;
+    this._cacheReadTokens += normalized.usage.cache_read_input_tokens || 0;
+    this._cacheCreateTokens += normalized.usage.cache_creation_input_tokens || 0;
     this._rounds += 1;
     if (normalized.model) {
       this._model = normalized.model;

package/dist/index.js

@@ -22,6 +22,16 @@ function empty() {
     toolCalls: []
   };
 }
+function extractCacheUsage(usage) {
+  const out = {};
+  if (typeof usage.cache_read_input_tokens === "number") {
+    out.cache_read_input_tokens = usage.cache_read_input_tokens;
+  }
+  if (typeof usage.cache_creation_input_tokens === "number") {
+    out.cache_creation_input_tokens = usage.cache_creation_input_tokens;
+  }
+  return out;
+}
 function normalizeOpenAI(raw) {
   const message = raw.choices?.[0]?.message || {};
   const usage = raw.usage || {};
@@ -56,7 +66,8 @@ function normalizeAnthropic(raw) {
     model: raw.model || null,
     usage: {
       prompt_tokens: usage.input_tokens || 0,
-      completion_tokens: usage.output_tokens || 0
+      completion_tokens: usage.output_tokens || 0,
+      ...extractCacheUsage(usage)
     },
     toolCalls
   };
@@ -231,18 +242,27 @@ var Session = class {
   _reset() {
     this._promptTokens = 0;
     this._completionTokens = 0;
+    this._cacheReadTokens = 0;
+    this._cacheCreateTokens = 0;
     this._rounds = 0;
     this._toolCalls = [];
     this._model = null;
     this._systemPrompt = null;
   }
   get totalUsage() {
-    return {
+    const usage = {
       prompt_tokens: this._promptTokens,
       completion_tokens: this._completionTokens,
-      total_tokens: this._promptTokens + this._completionTokens,
+      total_tokens: this._promptTokens + this._completionTokens + this._cacheReadTokens + this._cacheCreateTokens,
       ai_rounds: this._rounds
     };
+    if (this._cacheReadTokens) {
+      usage.cache_read_input_tokens = this._cacheReadTokens;
+    }
+    if (this._cacheCreateTokens) {
+      usage.cache_creation_input_tokens = this._cacheCreateTokens;
+    }
+    return usage;
   }
   get toolCalls() {
     return this._toolCalls;
@@ -252,6 +272,8 @@ var Session = class {
     const round = this._rounds;
     this._promptTokens += normalized.usage.prompt_tokens;
     this._completionTokens += normalized.usage.completion_tokens;
+    this._cacheReadTokens += normalized.usage.cache_read_input_tokens || 0;
+    this._cacheCreateTokens += normalized.usage.cache_creation_input_tokens || 0;
     this._rounds += 1;
     if (normalized.model) {
       this._model = normalized.model;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pentatonic-ai/ai-agent-sdk",
-  "version": "0.4.9",
+  "version": "0.5.0",
   "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",
@@ -12,7 +12,8 @@
     },
     "./memory": "./packages/memory/src/index.js",
     "./memory/server": "./packages/memory/src/server.js",
-    "./memory/openclaw": "./packages/memory/src/openclaw/index.js"
+    "./memory/openclaw": "./packages/memory/src/openclaw/index.js",
+    "./doctor": "./packages/doctor/src/index.js"
   },
   "bin": {
     "ai-agent-sdk": "./bin/cli.js"
@@ -22,6 +23,7 @@
     "src",
     "bin",
     "packages/memory",
+    "packages/doctor",
     "build.js",
     "README.md",
     "LICENSE"

package/packages/doctor/README.md

@@ -0,0 +1,106 @@
+# doctor
+
+Health check subsystem for the AI Agent SDK.
+
+## Usage
+
+```bash
+npx @pentatonic-ai/ai-agent-sdk doctor
+```
+
+Auto-detects which install path you're on (Local Memory, Hosted TES, or
+self-hosted Pentatonic platform) and runs the relevant checks. Returns
+exit code `0` for all-clear, `1` for warnings, `2` for critical.
+
+### Flags
+
+| Flag | Effect |
+|---|---|
+| `--json` | Emit a JSON report to stdout instead of a human table |
+| `--alert` | Suppress output unless something is non-ok (good for cron) |
+| `--no-plugins` | Skip user-supplied plugins for this run |
+| `--path <name>` | Force a specific path: `local`, `hosted`, `platform`, `auto` |
+| `--timeout <ms>` | Per-check timeout (default 10000) |
+
+## What gets checked
+
+### Universal (always)
+- Node version ≥ 18
+- Disk space at `$HOME` and `$TMPDIR`
+- SDK config files (`~/.claude/tes-memory.local.md`, etc) are mode 0600
+
+### Local Memory path
+Triggered when `DATABASE_URL` + `EMBEDDING_URL` + `LLM_URL` are all set,
+or `~/.claude/tes-memory.local.md` exists.
+- PostgreSQL reachable
+- pgvector extension installed
+- Schema migrations applied
+- Embedding endpoint responds + serves the configured model
+- LLM endpoint responds + has the configured model loaded
+- Memory server bound on `PORT`
+
+### Hosted TES path
+Triggered when `TES_ENDPOINT` + `TES_API_KEY` are both set.
+- TES endpoint reachable
+- API key authenticates for `TES_CLIENT_ID`
+
+### Self-hosted platform path
+Triggered when `HYBRIDRAG_URL` is set or `~/.openclaw/openclaw.json`
+exists. Each individual probe is skipped if its URL env var is unset, so
+partial deployments don't false-fail.
+- HybridRAG proxy
+- Qdrant
+- Neo4j (requires `NEO4J_PASSWORD`)
+- vLLM
+
+## Plugins
+
+Drop a `.mjs` file into `~/.config/pentatonic-ai/doctor-plugins/` and
+`doctor` will load it automatically. (Use `.mjs`, not `.js` — without a
+sibling `package.json` Node treats `.js` as CommonJS.)
+
+```js
+// ~/.config/pentatonic-ai/doctor-plugins/my-app.mjs
+export default {
+  name: "my-app",
+  checks: [
+    {
+      name: "internal API reachable",
+      severity: "warning", // 'critical' | 'warning' | 'info'
+      run: async () => {
+        const res = await fetch("https://internal/health");
+        return res.ok
+          ? { ok: true, msg: "200 OK" }
+          : { ok: false, msg: `HTTP ${res.status}` };
+      },
+    },
+  ],
+};
+```
+
+Plugin checks appear in the report prefixed with the plugin name
+(`my-app: internal API reachable`).
+
+A broken plugin will not abort the run — failures are logged and the
+loader moves on.
+
+## Programmatic use
+
+```js
+import { runDoctor, renderHuman } from "@pentatonic-ai/ai-agent-sdk/doctor";
+
+const report = await runDoctor({ path: "auto" });
+console.log(renderHuman(report));
+
+if (report.summary.critical > 0) {
+  process.exit(2);
+}
+```
+
+`runDoctor` accepts:
+- `path` — `'local' | 'hosted' | 'platform' | 'auto'`
+- `plugins` — `false` to skip plugin loading
+- `pluginDir` — override the plugin directory
+- `timeoutMs` — per-check timeout
+- `extraChecks` — additional check descriptors to merge in (useful in tests)
+- `env` — override `process.env` for path detection

package/packages/doctor/__tests__/checks.test.js

@@ -0,0 +1,187 @@
+import { universalChecks } from "../src/checks/universal.js";
+import { hostedTesChecks } from "../src/checks/hosted-tes.js";
+import { platformChecks } from "../src/checks/platform.js";
+
+// fetch mocking — we don't want any real network in unit tests.
+const realFetch = globalThis.fetch;
+
+function mockFetch(handler) {
+  globalThis.fetch = async (url, opts) => handler(url, opts);
+}
+
+afterEach(() => {
+  globalThis.fetch = realFetch;
+});
+
+describe("universal checks", () => {
+  it("registers the expected names", () => {
+    const names = universalChecks().map((c) => c.name);
+    expect(names).toContain("node version");
+    expect(names).toContain("disk space");
+    expect(names).toContain("config file perms");
+  });
+
+  it("node version returns ok on Node ≥18", async () => {
+    const node = universalChecks().find((c) => c.name === "node version");
+    const r = await node.run();
+    expect(r.ok).toBe(true);
+  });
+});
+
+describe("hosted TES checks", () => {
+  beforeEach(() => {
+    delete process.env.TES_ENDPOINT;
+    delete process.env.TES_API_KEY;
+    delete process.env.TES_CLIENT_ID;
+  });
+
+  it("reports missing env clearly", async () => {
+    const reach = hostedTesChecks().find(
+      (c) => c.name === "TES endpoint reachable"
+    );
+    const r = await reach.run();
+    expect(r.ok).toBe(false);
+    expect(r.msg).toMatch(/TES_ENDPOINT/);
+  });
+
+  it("treats /api/health 200 as reachable", async () => {
+    process.env.TES_ENDPOINT = "https://example.test";
+    mockFetch(async () => ({
+      ok: true,
+      status: 200,
+      text: async () => "",
+      json: async () => ({}),
+    }));
+    const reach = hostedTesChecks().find(
+      (c) => c.name === "TES endpoint reachable"
+    );
+    const r = await reach.run();
+    expect(r.ok).toBe(true);
+  });
+
+  it("falls back to graphql when /api/health 404s", async () => {
+    process.env.TES_ENDPOINT = "https://example.test";
+    let calls = 0;
+    mockFetch(async (url) => {
+      calls++;
+      if (url.endsWith("/api/health")) {
+        return { ok: false, status: 404, text: async () => "" };
+      }
+      return { ok: true, status: 200, json: async () => ({}) };
+    });
+    const reach = hostedTesChecks().find(
+      (c) => c.name === "TES endpoint reachable"
+    );
+    const r = await reach.run();
+    expect(r.ok).toBe(true);
+    expect(calls).toBe(2);
+  });
+
+  it("rejects 401 from auth check", async () => {
+    process.env.TES_ENDPOINT = "https://example.test";
+    process.env.TES_API_KEY = "bad";
+    process.env.TES_CLIENT_ID = "c";
+    mockFetch(async () => ({ ok: false, status: 401, text: async () => "" }));
+    const auth = hostedTesChecks().find((c) => c.name === "TES API key valid");
+    const r = await auth.run();
+    expect(r.ok).toBe(false);
+    expect(r.msg).toMatch(/auth rejected/);
+  });
+
+  it("accepts 200 from auth check", async () => {
+    process.env.TES_ENDPOINT = "https://example.test";
+    process.env.TES_API_KEY = "good";
+    process.env.TES_CLIENT_ID = "c";
+    mockFetch(async () => ({
+      ok: true,
+      status: 200,
+      json: async () => ({ data: { __schema: {} } }),
+    }));
+    const auth = hostedTesChecks().find((c) => c.name === "TES API key valid");
+    const r = await auth.run();
+    expect(r.ok).toBe(true);
+  });
+});
+
+describe("platform checks", () => {
+  beforeEach(() => {
+    delete process.env.HYBRIDRAG_URL;
+    delete process.env.QDRANT_URL;
+    delete process.env.NEO4J_HTTP;
+    delete process.env.NEO4J_PASSWORD;
+    delete process.env.VLLM_URL;
+  });
+
+  it("skips each check when its URL env is unset", async () => {
+    const checks = platformChecks();
+    for (const c of checks) {
+      const r = await c.run();
+      expect(r.ok).toBe(true);
+      expect(r.msg).toMatch(/not set \(skipped\)/);
+    }
+  });
+
+  it("hybridrag falls back to search probe when /health 404s", async () => {
+    process.env.HYBRIDRAG_URL = "http://hybridrag:8031";
+    mockFetch(async (url) => {
+      if (url.endsWith("/health")) {
+        return { ok: false, status: 404, text: async () => "" };
+      }
+      return { ok: true, status: 200, json: async () => ({ results: [] }) };
+    });
+    const c = platformChecks().find((x) => x.name === "hybridrag reachable");
+    const r = await c.run();
+    expect(r.ok).toBe(true);
+  });
+
+  it("neo4j requires NEO4J_PASSWORD when NEO4J_HTTP is set", async () => {
+    process.env.NEO4J_HTTP = "http://neo4j:7474";
+    const c = platformChecks().find((x) => x.name === "neo4j reachable");
+    const r = await c.run();
+    expect(r.ok).toBe(false);
+    expect(r.msg).toMatch(/NEO4J_PASSWORD/);
+  });
+
+  it("neo4j flags 401 specifically", async () => {
+    process.env.NEO4J_HTTP = "http://neo4j:7474";
+    process.env.NEO4J_PASSWORD = "wrong";
+    mockFetch(async () => ({
+      status: 401,
+      ok: false,
+      text: async () => "",
+      json: async () => ({}),
+    }));
+    const c = platformChecks().find((x) => x.name === "neo4j reachable");
+    const r = await c.run();
+    expect(r.ok).toBe(false);
+    expect(r.msg).toMatch(/auth rejected/);
+  });
+
+  it("qdrant lists collections", async () => {
+    process.env.QDRANT_URL = "http://qdrant:6333";
+    mockFetch(async () => ({
+      ok: true,
+      status: 200,
+      json: async () => ({
+        result: { collections: [{ name: "a" }, { name: "b" }] },
+      }),
+    }));
+    const c = platformChecks().find((x) => x.name === "qdrant reachable");
+    const r = await c.run();
+    expect(r.ok).toBe(true);
+    expect(r.detail.collections).toEqual(["a", "b"]);
+  });
+
+  it("vllm flags 'no models loaded' when /v1/models is empty", async () => {
+    process.env.VLLM_URL = "http://vllm:8001";
+    mockFetch(async () => ({
+      ok: true,
+      status: 200,
+      json: async () => ({ data: [] }),
+    }));
+    const c = platformChecks().find((x) => x.name === "vllm reachable");
+    const r = await c.run();
+    expect(r.ok).toBe(false);
+    expect(r.msg).toMatch(/no models loaded/);
+  });
+});