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

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

@@ -0,0 +1,101 @@
+import { detectPath, detectPaths, PATHS } from "../src/detect.js";
+
+describe("detectPaths", () => {
+  it("returns explicit override when set", () => {
+    const paths = detectPaths({ path: PATHS.HOSTED, env: {} });
+    expect(paths).toEqual(new Set([PATHS.HOSTED]));
+  });
+
+  it("respects PENTATONIC_DOCTOR_PATH env", () => {
+    const paths = detectPaths({ env: { PENTATONIC_DOCTOR_PATH: PATHS.LOCAL } });
+    expect(paths).toEqual(new Set([PATHS.LOCAL]));
+  });
+
+  it("rejects invalid override", () => {
+    expect(() => detectPaths({ path: "fake", env: {} })).toThrow(/Unknown path/);
+  });
+
+  it("treats 'auto' as no override", () => {
+    const paths = detectPaths({ path: "auto", env: {} });
+    expect(paths).toEqual(new Set([PATHS.UNKNOWN]));
+  });
+
+  it("detects hosted from TES env vars", () => {
+    const paths = detectPaths({
+      env: { TES_ENDPOINT: "https://x", TES_API_KEY: "k" },
+    });
+    expect(paths.has(PATHS.HOSTED)).toBe(true);
+  });
+
+  it("does not detect hosted with only one TES var", () => {
+    const paths = detectPaths({ env: { TES_ENDPOINT: "https://x" } });
+    expect(paths.has(PATHS.HOSTED)).toBe(false);
+  });
+
+  it("detects platform from HYBRIDRAG_URL", () => {
+    const paths = detectPaths({
+      env: { HYBRIDRAG_URL: "http://hybridrag:8031" },
+    });
+    expect(paths.has(PATHS.PLATFORM)).toBe(true);
+  });
+
+  it("detects local from full DSN trio", () => {
+    const paths = detectPaths({
+      env: {
+        DATABASE_URL: "postgres://x",
+        EMBEDDING_URL: "http://x/v1",
+        LLM_URL: "http://x/v1",
+      },
+    });
+    expect(paths.has(PATHS.LOCAL)).toBe(true);
+  });
+
+  it("can detect multiple paths simultaneously", () => {
+    const paths = detectPaths({
+      env: {
+        TES_ENDPOINT: "https://x",
+        TES_API_KEY: "k",
+        HYBRIDRAG_URL: "http://h",
+      },
+    });
+    expect(paths.has(PATHS.HOSTED)).toBe(true);
+    expect(paths.has(PATHS.PLATFORM)).toBe(true);
+  });
+
+  it("falls back to UNKNOWN when nothing matches", () => {
+    const paths = detectPaths({ env: {} });
+    expect(paths).toEqual(new Set([PATHS.UNKNOWN]));
+  });
+});
+
+describe("detectPath", () => {
+  it("prefers platform over hosted over local", () => {
+    expect(
+      detectPath({
+        env: {
+          HYBRIDRAG_URL: "http://h",
+          TES_ENDPOINT: "x",
+          TES_API_KEY: "k",
+        },
+      })
+    ).toBe(PATHS.PLATFORM);
+  });
+
+  it("prefers hosted over local", () => {
+    expect(
+      detectPath({
+        env: {
+          TES_ENDPOINT: "x",
+          TES_API_KEY: "k",
+          DATABASE_URL: "postgres://x",
+          EMBEDDING_URL: "http://x/v1",
+          LLM_URL: "http://x/v1",
+        },
+      })
+    ).toBe(PATHS.HOSTED);
+  });
+
+  it("returns UNKNOWN with no signals", () => {
+    expect(detectPath({ env: {} })).toBe(PATHS.UNKNOWN);
+  });
+});

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

@@ -0,0 +1,92 @@
+import { renderHuman, renderJson } from "../src/output.js";
+import { SEVERITY } from "../src/index.js";
+import { PATHS } from "../src/detect.js";
+
+const sampleReport = {
+  timestamp: "2026-04-18T08:00:00.000Z",
+  paths: [PATHS.HOSTED],
+  pluginCount: 2,
+  summary: { ok: 2, warning: 1, critical: 1, total: 4 },
+  checks: [
+    {
+      name: "good",
+      severity: SEVERITY.INFO,
+      ok: true,
+      msg: "all fine",
+      detail: {},
+      durationMs: 5,
+    },
+    {
+      name: "bad",
+      severity: SEVERITY.WARNING,
+      ok: false,
+      msg: "kinda broken",
+      detail: {},
+      durationMs: 5,
+    },
+    {
+      name: "broken",
+      severity: SEVERITY.CRITICAL,
+      ok: false,
+      msg: "very broken",
+      detail: {},
+      durationMs: 5,
+    },
+    {
+      name: "good2",
+      severity: SEVERITY.INFO,
+      ok: true,
+      msg: "fine",
+      detail: {},
+      durationMs: 5,
+    },
+  ],
+};
+
+describe("renderHuman", () => {
+  it("includes detected paths line", () => {
+    const out = renderHuman(sampleReport);
+    expect(out).toMatch(/paths detected: hosted/);
+  });
+
+  it("includes plugin count when non-zero", () => {
+    const out = renderHuman(sampleReport);
+    expect(out).toMatch(/plugins loaded: 2/);
+  });
+
+  it("uses ✓ for ok checks", () => {
+    expect(renderHuman(sampleReport)).toMatch(/✓ {2}good/);
+  });
+
+  it("uses ✗ for critical failures", () => {
+    expect(renderHuman(sampleReport)).toMatch(/✗ {2}broken/);
+  });
+
+  it("uses ! for warnings", () => {
+    expect(renderHuman(sampleReport)).toMatch(/! {2}bad/);
+  });
+
+  it("includes the summary line", () => {
+    expect(renderHuman(sampleReport)).toMatch(
+      /summary: 2 ok, 1 warning, 1 critical \(of 4\)/
+    );
+  });
+
+  it("handles empty reports", () => {
+    const out = renderHuman({
+      ...sampleReport,
+      checks: [],
+      summary: { ok: 0, warning: 0, critical: 0, total: 0 },
+    });
+    expect(out).toMatch(/no checks/);
+  });
+});
+
+describe("renderJson", () => {
+  it("emits valid JSON", () => {
+    const out = renderJson(sampleReport);
+    const parsed = JSON.parse(out);
+    expect(parsed.summary.total).toBe(4);
+    expect(parsed.checks).toHaveLength(4);
+  });
+});

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

@@ -0,0 +1,111 @@
+import { mkdtempSync, writeFileSync, rmSync, mkdirSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { loadPlugins } from "../src/plugins.js";
+
+function tmpPluginDir() {
+  return mkdtempSync(join(tmpdir(), "doctor-plugins-"));
+}
+
+function writePlugin(dir, file, src) {
+  writeFileSync(join(dir, file), src);
+}
+
+describe("loadPlugins", () => {
+  let dir;
+  afterEach(() => {
+    if (dir) rmSync(dir, { recursive: true, force: true });
+    dir = null;
+  });
+
+  it("returns [] when the plugin dir doesn't exist", async () => {
+    const fake = join(tmpdir(), "doctor-does-not-exist-" + Date.now());
+    expect(await loadPlugins({ dir: fake })).toEqual([]);
+  });
+
+  it("loads a valid .mjs plugin", async () => {
+    dir = tmpPluginDir();
+    writePlugin(
+      dir,
+      "good.mjs",
+      `export default {
+        name: "good",
+        checks: [
+          { name: "c1", run: async () => ({ ok: true, msg: "ok" }) },
+        ],
+      };`
+    );
+    const plugins = await loadPlugins({ dir });
+    expect(plugins).toHaveLength(1);
+    expect(plugins[0].name).toBe("good");
+    expect(plugins[0].checks).toHaveLength(1);
+  });
+
+  it("ignores .js files (only .mjs is supported)", async () => {
+    dir = tmpPluginDir();
+    writePlugin(
+      dir,
+      "ignored.js",
+      `export default { name: "ignored", checks: [] };`
+    );
+    expect(await loadPlugins({ dir })).toHaveLength(0);
+  });
+
+  it("ignores non-js files", async () => {
+    dir = tmpPluginDir();
+    writeFileSync(join(dir, "README.md"), "# notes");
+    writeFileSync(join(dir, "data.json"), "{}");
+    expect(await loadPlugins({ dir })).toHaveLength(0);
+  });
+
+  it("skips invalid plugins via onError without throwing", async () => {
+    dir = tmpPluginDir();
+    writePlugin(dir, "bad.mjs", `export default { name: 'no checks' };`);
+    const errors = [];
+    const plugins = await loadPlugins({ dir, onError: (e) => errors.push(e) });
+    expect(plugins).toEqual([]);
+    expect(errors[0]).toMatch(/not a valid plugin/);
+  });
+
+  it("skips plugins that throw at load time", async () => {
+    // Note: syntax errors in dynamic-imported ESM crash the Jest worker
+    // (the SyntaxError isn't catchable across the module boundary), so we
+    // exercise the load-failure path with a runtime throw instead, which
+    // hits the same try/catch in loadPlugins.
+    dir = tmpPluginDir();
+    writePlugin(dir, "throws-on-load.mjs", `throw new Error("boom at load");`);
+    const errors = [];
+    const plugins = await loadPlugins({ dir, onError: (e) => errors.push(e) });
+    expect(plugins).toEqual([]);
+    expect(errors[0]).toMatch(/failed to load/);
+  });
+
+  it("loads multiple plugins from the same dir", async () => {
+    dir = tmpPluginDir();
+    writePlugin(
+      dir,
+      "a.mjs",
+      `export default { name: "a", checks: [{ name: "x", run: async () => ({ ok: true, msg: "" }) }] };`
+    );
+    writePlugin(
+      dir,
+      "b.mjs",
+      `export default { name: "b", checks: [{ name: "y", run: async () => ({ ok: true, msg: "" }) }] };`
+    );
+    const plugins = await loadPlugins({ dir });
+    expect(plugins.map((p) => p.name).sort()).toEqual(["a", "b"]);
+  });
+
+  it("rejects plugins whose checks lack run()", async () => {
+    dir = tmpPluginDir();
+    writePlugin(
+      dir,
+      "bad.mjs",
+      `export default { name: "bad", checks: [{ name: "x" }] };`
+    );
+    const errors = [];
+    const plugins = await loadPlugins({ dir, onError: (e) => errors.push(e) });
+    expect(plugins).toEqual([]);
+    expect(errors[0]).toMatch(/not a valid plugin/);
+  });
+});

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

@@ -0,0 +1,131 @@
+import { runDoctor } from "../src/runner.js";
+import { SEVERITY } from "../src/index.js";
+
+// Force UNKNOWN path so we don't pull in any built-in path checks.
+const NO_PATH = { env: {} };
+
+function ok(name) {
+  return {
+    name,
+    severity: SEVERITY.INFO,
+    run: async () => ({ ok: true, msg: "fine" }),
+  };
+}
+
+function fail(name, severity = SEVERITY.WARNING) {
+  return {
+    name,
+    severity,
+    run: async () => ({ ok: false, msg: "broken" }),
+  };
+}
+
+function crashes(name) {
+  return {
+    name,
+    severity: SEVERITY.WARNING,
+    run: async () => {
+      throw new Error("boom");
+    },
+  };
+}
+
+function hangs(name) {
+  return {
+    name,
+    severity: SEVERITY.WARNING,
+    run: () => new Promise(() => {}),
+  };
+}
+
+describe("runDoctor", () => {
+  it("includes universal checks even with no path detected", async () => {
+    const r = await runDoctor({ ...NO_PATH, plugins: false });
+    const names = r.checks.map((c) => c.name);
+    expect(names).toContain("node version");
+    expect(names).toContain("disk space");
+  });
+
+  it("runs extraChecks", async () => {
+    const r = await runDoctor({
+      ...NO_PATH,
+      plugins: false,
+      extraChecks: [ok("custom-1"), ok("custom-2")],
+    });
+    expect(r.checks.find((c) => c.name === "custom-1")).toBeDefined();
+    expect(r.checks.find((c) => c.name === "custom-2")).toBeDefined();
+  });
+
+  it("counts ok/warning/critical correctly", async () => {
+    const r = await runDoctor({
+      ...NO_PATH,
+      plugins: false,
+      extraChecks: [
+        ok("a"),
+        fail("b", SEVERITY.WARNING),
+        fail("c", SEVERITY.CRITICAL),
+      ],
+    });
+    const a = r.checks.find((c) => c.name === "a");
+    const b = r.checks.find((c) => c.name === "b");
+    const c = r.checks.find((c) => c.name === "c");
+    expect(a.ok).toBe(true);
+    expect(b.ok).toBe(false);
+    expect(c.ok).toBe(false);
+    // summary counts include the universal checks too — count just the ones we added
+    expect(r.summary.total).toBe(r.checks.length);
+  });
+
+  it("does not let a crashing check abort the run", async () => {
+    const r = await runDoctor({
+      ...NO_PATH,
+      plugins: false,
+      extraChecks: [crashes("explody"), ok("survivor")],
+    });
+    const e = r.checks.find((c) => c.name === "explody");
+    const s = r.checks.find((c) => c.name === "survivor");
+    expect(e.ok).toBe(false);
+    expect(e.msg).toMatch(/check itself failed: boom/);
+    expect(s.ok).toBe(true);
+  });
+
+  it("times out hung checks instead of hanging the runner", async () => {
+    const r = await runDoctor({
+      ...NO_PATH,
+      plugins: false,
+      timeoutMs: 100,
+      extraChecks: [hangs("hangs")],
+    });
+    const h = r.checks.find((c) => c.name === "hangs");
+    expect(h.ok).toBe(false);
+    expect(h.msg).toMatch(/timed out/);
+  }, 5000);
+
+  it("reports invalid check return values", async () => {
+    const r = await runDoctor({
+      ...NO_PATH,
+      plugins: false,
+      extraChecks: [
+        {
+          name: "lying",
+          severity: SEVERITY.WARNING,
+          run: async () => ({ msg: "nope" }), // missing 'ok'
+        },
+      ],
+    });
+    const l = r.checks.find((c) => c.name === "lying");
+    expect(l.ok).toBe(false);
+    expect(l.msg).toMatch(/invalid result/);
+  });
+
+  it("returns summary that adds up to total", async () => {
+    const r = await runDoctor({
+      ...NO_PATH,
+      plugins: false,
+      extraChecks: [ok("a"), fail("b"), fail("c", SEVERITY.CRITICAL)],
+    });
+    expect(r.summary.ok + r.summary.warning + r.summary.critical).toBe(
+      r.summary.total
+    );
+  });
+});

package/packages/doctor/package.json

@@ -0,0 +1,6 @@
+{
+  "private": true,
+  "name": "doctor",
+  "description": "Health check subsystem — imported via @pentatonic-ai/ai-agent-sdk/doctor",
+  "type": "module"
+}

package/packages/doctor/src/checks/hosted-tes.js

@@ -0,0 +1,109 @@
+/**
+ * Hosted TES path checks.
+ *
+ * Verifies that TES_ENDPOINT is reachable and TES_API_KEY is accepted
+ * for the configured TES_CLIENT_ID. Uses a tiny GraphQL probe so we
+ * exercise the same auth path the SDK uses at runtime.
+ */
+
+import { SEVERITY } from "../index.js";
+
+async function fetchWithTimeout(url, opts = {}, timeoutMs = 5000) {
+  return await fetch(url, {
+    ...opts,
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+}
+
+function checkTesReachable() {
+  return {
+    name: "TES endpoint reachable",
+    severity: SEVERITY.CRITICAL,
+    run: async () => {
+      const endpoint = process.env.TES_ENDPOINT;
+      if (!endpoint) {
+        return { ok: false, msg: "TES_ENDPOINT not set" };
+      }
+      try {
+        const res = await fetchWithTimeout(`${endpoint.replace(/\/$/, "")}/api/health`);
+        if (res.ok) {
+          return { ok: true, msg: `${endpoint} reachable` };
+        }
+        // Many TES deployments don't expose /api/health; fall back to a
+        // GraphQL introspection ping which is always available.
+        const probe = await fetchWithTimeout(
+          `${endpoint.replace(/\/$/, "")}/api/graphql`,
+          {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ query: "{ __typename }" }),
+          }
+        );
+        if (probe.ok || probe.status === 401) {
+          // 401 is fine here — it proves the server is alive; auth is
+          // a separate check below.
+          return { ok: true, msg: `${endpoint} reachable (graphql)` };
+        }
+        return { ok: false, msg: `HTTP ${probe.status}` };
+      } catch (err) {
+        return { ok: false, msg: err.message };
+      }
+    },
+  };
+}
+
+function checkTesAuth() {
+  return {
+    name: "TES API key valid",
+    severity: SEVERITY.CRITICAL,
+    run: async () => {
+      const endpoint = process.env.TES_ENDPOINT;
+      const apiKey = process.env.TES_API_KEY;
+      const clientId = process.env.TES_CLIENT_ID;
+      if (!endpoint || !apiKey || !clientId) {
+        return {
+          ok: false,
+          msg: "TES_ENDPOINT / TES_API_KEY / TES_CLIENT_ID required",
+        };
+      }
+      try {
+        // viewer / me-style query — exact name varies by deployment, so
+        // we use a generic introspection that should always require auth.
+        const res = await fetchWithTimeout(
+          `${endpoint.replace(/\/$/, "")}/api/graphql`,
+          {
+            method: "POST",
+            headers: {
+              "Content-Type": "application/json",
+              Authorization: `Bearer ${apiKey}`,
+              "x-client-id": clientId,
+            },
+            body: JSON.stringify({
+              query: "{ __schema { queryType { name } } }",
+            }),
+          }
+        );
+        if (res.status === 401 || res.status === 403) {
+          return {
+            ok: false,
+            msg: `auth rejected (HTTP ${res.status}) — check API key + client ID`,
+          };
+        }
+        if (!res.ok) {
+          return { ok: false, msg: `HTTP ${res.status}` };
+        }
+        return {
+          ok: true,
+          msg: `key accepted for ${clientId}`,
+          detail: { clientId, endpoint },
+        };
+      } catch (err) {
+        return { ok: false, msg: err.message };
+      }
+    },
+  };
+}
+
+export function hostedTesChecks() {
+  return [checkTesReachable(), checkTesAuth()];
+}