@pentatonic-ai/ai-agent-sdk 0.5.11 → 0.7.0

package/bin/commands/config.js

@@ -0,0 +1,251 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync, copyFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const DEFAULT_ENGINE_URL = "http://localhost:8099";
+
+/**
+ * Top-level dispatcher for `tes config <sub>`.
+ *
+ * Subcommands:
+ *   local  — write `mode: local` + memory_url to the plugin config; print
+ *            bring-up instructions for the engine docker stack.
+ *   hosted — run the SDK login flow (writes ~/.config/tes/credentials.json
+ *            and updates the plugin config to hosted mode).
+ *   show   — read the plugin config + credentials and print what's
+ *            currently configured.
+ *
+ * Future:
+ *   set <key> <value> — tweak engine env vars (EMBED_MODEL, EMBED_DIM, …)
+ *                        and reload docker-compose.
+ *
+ * @param {object} opts
+ * @param {string} opts.sub - subcommand name
+ * @param {string} [opts.endpoint] - default TES endpoint (forwarded to login)
+ * @param {string} [opts.engineUrl] - override for `local`
+ * @param {string} [opts.configDir] - override config-file dir (test hook)
+ * @param {Function} [opts.log]
+ * @param {Function} [opts.errLog]
+ */
+export async function runConfigCommand(opts = {}) {
+  const log = opts.log || ((m) => process.stdout.write(m + "\n"));
+  const errLog = opts.errLog || ((m) => process.stderr.write(m + "\n"));
+  const sub = opts.sub;
+
+  switch (sub) {
+    case "local":
+      return runConfigLocal(opts);
+    case "hosted":
+      return runConfigHosted(opts);
+    case "show":
+      return runConfigShow(opts);
+    case undefined:
+    case "":
+    case "help":
+    case "--help":
+    case "-h":
+      printHelp(log);
+      return { exitCode: sub === undefined ? 1 : 0 };
+    default:
+      errLog(`Unknown subcommand: ${sub}`);
+      printHelp(errLog);
+      return { exitCode: 2 };
+  }
+}
+
+function printHelp(out) {
+  out("Usage: tes config <subcommand>");
+  out("");
+  out("Subcommands:");
+  out("  local           Point Claude Code's plugin at a local memory engine");
+  out("  hosted          Sign in with TES (browser flow); writes credentials");
+  out("  show            Print the current plugin config + memory backend");
+  out("");
+  out("Flags (subcommand-specific):");
+  out("  --engine-url <url>   For 'local'; default http://localhost:8099");
+}
+
+// ----------------------------------------------------------------------
+// `tes config local`
+// ----------------------------------------------------------------------
+
+async function runConfigLocal(opts) {
+  const log = opts.log || ((m) => process.stdout.write(m + "\n"));
+  const errLog = opts.errLog || ((m) => process.stderr.write(m + "\n"));
+  const engineUrl = opts.engineUrl || DEFAULT_ENGINE_URL;
+
+  const configDir = opts.configDir || resolveConfigDir();
+  const configPath = join(configDir, "tes-memory.local.md");
+
+  try {
+    mkdirSync(configDir, { recursive: true });
+  } catch (err) {
+    errLog(`Error: cannot create config dir ${configDir}: ${err.message}`);
+    return { exitCode: 1 };
+  }
+
+  // Preserve any existing hosted config as comments so the user can
+  // flip back without re-running login.
+  let preserved = "";
+  if (existsSync(configPath)) {
+    try {
+      const fm = parseFrontmatter(readFileSync(configPath, "utf-8"));
+      if (fm && fm.tes_endpoint) {
+        copyFileSync(configPath, configPath + ".bak");
+        preserved = formatPreservedHosted(fm);
+        log(`  Existing hosted config backed up to ${configPath}.bak`);
+      }
+    } catch {
+      // best-effort
+    }
+  }
+
+  const body =
+    `---\n` +
+    `mode: local\n` +
+    `memory_url: ${engineUrl}\n` +
+    preserved +
+    `---\n`;
+
+  try {
+    writeFileSync(configPath, body, { mode: 0o600 });
+  } catch (err) {
+    errLog(`Error: cannot write config ${configPath}: ${err.message}`);
+    return { exitCode: 1 };
+  }
+
+  log("");
+  log(`✓ Plugin config written: ${configPath}`);
+  log(`  → Claude Code's tes-memory plugin now points at ${engineUrl}`);
+  log("");
+  log("Next steps to bring up the engine:");
+  log("");
+  log("  1. Make sure Ollama is running and bound to all interfaces");
+  log("     (so docker containers can reach it via host.docker.internal):");
+  log("");
+  log("       sudo mkdir -p /etc/systemd/system/ollama.service.d");
+  log("       echo -e '[Service]\\nEnvironment=\"OLLAMA_HOST=0.0.0.0:11434\"' \\");
+  log("         | sudo tee /etc/systemd/system/ollama.service.d/override.conf");
+  log("       sudo systemctl daemon-reload && sudo systemctl restart ollama");
+  log("       ollama pull nomic-embed-text     # if not already pulled");
+  log("");
+  log("  2. Bring up the engine docker stack:");
+  log("");
+  log("       cd packages/memory-engine");
+  log("       cp .env.example .env             # if no .env yet");
+  log("       # edit .env if you want a different embedding model/dim");
+  log("       docker compose up -d --scale nv-embed=0");
+  log("");
+  log("  3. Verify it's healthy:");
+  log("");
+  log(`       curl -s ${engineUrl}/health | jq`);
+  log("");
+  log("  4. Reload Claude Code (close + reopen, or /reload-plugins).");
+  log("");
+  log("     Verify with /tes-memory:tes-status — should report:");
+  log("     ✓ Connected to local memory engine");
+  log("");
+  return { exitCode: 0, configPath };
+}
+
+// ----------------------------------------------------------------------
+// `tes config hosted`
+// ----------------------------------------------------------------------
+
+async function runConfigHosted(opts) {
+  const { runLoginCommand } = await import("./login.js");
+  return runLoginCommand({ endpoint: opts.endpoint });
+}
+
+// ----------------------------------------------------------------------
+// `tes config show`
+// ----------------------------------------------------------------------
+
+function runConfigShow(opts) {
+  const log = opts.log || ((m) => process.stdout.write(m + "\n"));
+  const configDir = opts.configDir || resolveConfigDir();
+  const configPath = join(configDir, "tes-memory.local.md");
+
+  log("");
+  log(`Plugin config: ${configPath}`);
+  if (!existsSync(configPath)) {
+    log("  (file does not exist — run `tes config local` or `tes config hosted`)");
+    return { exitCode: 1 };
+  }
+
+  const fm = parseFrontmatter(readFileSync(configPath, "utf-8"));
+  if (!fm) {
+    log("  (file exists but couldn't parse frontmatter)");
+    return { exitCode: 1 };
+  }
+
+  const mode = fm.mode || (fm.tes_endpoint ? "hosted" : "?");
+  log(`  Mode: ${mode}`);
+  if (mode === "local") {
+    log(`  memory_url: ${fm.memory_url || "(missing)"}`);
+  } else if (mode === "hosted") {
+    log(`  endpoint: ${fm.tes_endpoint}`);
+    log(`  client_id: ${fm.tes_client_id}`);
+    log(`  user_id: ${fm.tes_user_id || "(unset)"}`);
+  }
+
+  // Also surface ~/.config/tes/credentials.json if present
+  const credPath = join(
+    process.env.XDG_CONFIG_HOME || join(homedir(), ".config"),
+    "tes",
+    "credentials.json"
+  );
+  if (existsSync(credPath)) {
+    try {
+      const c = JSON.parse(readFileSync(credPath, "utf-8"));
+      log("");
+      log(`Credentials: ${credPath}`);
+      log(`  endpoint: ${c.endpoint}`);
+      log(`  clientId: ${c.clientId}`);
+    } catch {
+      log(`  (${credPath} unreadable)`);
+    }
+  }
+
+  log("");
+  return { exitCode: 0 };
+}
+
+// ----------------------------------------------------------------------
+// Helpers
+// ----------------------------------------------------------------------
+
+function resolveConfigDir() {
+  const candidates = [
+    process.env.CLAUDE_CONFIG_DIR,
+    join(homedir(), ".claude-pentatonic"),
+    join(homedir(), ".claude"),
+  ].filter(Boolean);
+  for (const c of candidates) {
+    if (existsSync(c)) return c;
+  }
+  return candidates[candidates.length - 1];
+}
+
+function parseFrontmatter(content) {
+  const m = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!m) return null;
+  const out = {};
+  for (const line of m[1].split("\n")) {
+    const kv = line.match(/^(\w+):\s*(.+)$/);
+    if (kv) out[kv[1]] = kv[2].trim();
+  }
+  return out;
+}
+
+function formatPreservedHosted(fm) {
+  const keys = ["tes_endpoint", "tes_client_id", "tes_api_key", "tes_user_id"];
+  const present = keys.filter((k) => fm[k]);
+  if (!present.length) return "";
+  return (
+    `# Hosted config preserved — uncomment + remove the local block above\n` +
+    `# to switch back. Original saved as <this-file>.bak.\n` +
+    present.map((k) => `# ${k}: ${fm[k]}`).join("\n") +
+    `\n`
+  );
+}

package/bin/commands/login.js

@@ -0,0 +1,219 @@
+import { generatePKCE } from "../lib/pkce.js";
+import { startCallbackServer } from "../lib/callback-server.js";
+import { writeCredentials } from "../lib/credentials.js";
+import { hostname } from "node:os";
+import { execFileSync } from "node:child_process";
+import { Buffer } from "node:buffer";
+
+/**
+ * Run the SDK login flow.
+ *
+ * Steps: PKCE → start localhost server → open browser → wait for code
+ *        → exchange code for access_token → mint tes_* via GraphQL
+ *        → write credentials.
+ *
+ * Exits non-zero (and returns { exitCode }) on any failure rather than
+ * throwing — caller (cli.js) maps exitCode to process.exit().
+ *
+ * @param {object} opts
+ * @param {string} opts.endpoint    - e.g. https://api.pentatonic.com
+ * @param {Function} [opts.openBrowser] - injectable for tests
+ * @param {Function} [opts.log]     - injectable for tests
+ * @param {Function} [opts.errLog]  - injectable for tests
+ */
+export async function runLoginCommand(opts = {}) {
+  const endpoint = opts.endpoint;
+  const log = opts.log || ((msg) => process.stdout.write(msg + "\n"));
+  const errLog = opts.errLog || ((msg) => process.stderr.write(msg + "\n"));
+  const openBrowser = opts.openBrowser || defaultOpenBrowser;
+
+  if (!endpoint) {
+    errLog("Error: endpoint is required");
+    return { exitCode: 1 };
+  }
+
+  const { verifier, challenge, state } = generatePKCE();
+
+  let server;
+  try {
+    server = await startCallbackServer({
+      ports: [14171, 14172, 14173, 0],
+      state,
+      timeoutMs: 5 * 60_000,
+    });
+  } catch (err) {
+    errLog(`Failed to start localhost callback listener: ${err.message}`);
+    return { exitCode: 2 };
+  }
+
+  const initUrl = new URL(`${endpoint}/cli-init`);
+  initUrl.searchParams.set("cb", `http://localhost:${server.port}/callback`);
+  initUrl.searchParams.set("state", state);
+  initUrl.searchParams.set("code_challenge", challenge);
+  initUrl.searchParams.set("code_challenge_method", "S256");
+
+  log("");
+  log("  Hosted TES Setup");
+  log(`  Opening ${initUrl.toString()} in your browser…`);
+  log(`  Listening on http://localhost:${server.port} for the callback (5 min timeout)`);
+
+  try {
+    openBrowser(initUrl.toString());
+  } catch (err) {
+    log(`  (Could not auto-open browser: ${err.message})`);
+    log(`  Please open this URL manually:`);
+    log(`    ${initUrl.toString()}`);
+  }
+
+  let callback;
+  try {
+    callback = await server.result;
+  } catch (err) {
+    errLog(`Login failed: ${err.message}`);
+    return { exitCode: 3 };
+  }
+
+  // Exchange code for access_token at /oauth/token. The CLI POSTs to
+  // the same platform-level endpoint it was given — /oauth/token
+  // validates the verifier against the code regardless of which
+  // tenant subdomain issued it.
+  let accessToken;
+  try {
+    const tokenRes = await fetch(`${endpoint}/oauth/token`, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({
+        grant_type: "authorization_code",
+        code: callback.code,
+        redirect_uri: `http://localhost:${server.port}/callback`,
+        code_verifier: verifier,
+      }).toString(),
+    });
+    if (!tokenRes.ok) {
+      const body = await tokenRes.json().catch(() => ({}));
+      // Surface error_description if present — `invalid_grant` alone
+      // is ambiguous (could be expired code, PKCE mismatch, redirect_uri
+      // mismatch, replay, etc.). The description names the actual cause.
+      const detail = body.error_description
+        ? `${body.error}: ${body.error_description}`
+        : body.error || "unknown";
+      errLog(`Token exchange failed (${tokenRes.status}): ${detail}`);
+      return { exitCode: 4 };
+    }
+    const tokenBody = await tokenRes.json();
+    accessToken = tokenBody.access_token;
+    if (!accessToken) {
+      errLog("Token exchange returned no access_token");
+      return { exitCode: 4 };
+    }
+  } catch (err) {
+    errLog(`Token exchange request failed: ${err.message}`);
+    return { exitCode: 4 };
+  }
+
+  // Decode JWT claims (unverified) to extract clientId. The token came
+  // from /oauth/token over TLS so it's trusted; verification happens
+  // server-side on every subsequent API call.
+  const claims = decodeJwtClaims(accessToken);
+  const clientId = claims?.client_id || claims?.clientId;
+  if (!clientId) {
+    errLog("Access token missing clientId claim");
+    return { exitCode: 5 };
+  }
+
+  // Mint long-lived tes_* via GraphQL.
+  let plainTextToken;
+  try {
+    const graphqlRes = await fetch(`${endpoint}/api/graphql`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${accessToken}`,
+        "x-client-id": clientId,
+      },
+      body: JSON.stringify({
+        query: `mutation Mint($clientId: String!, $input: CreateApiTokenInput!) {
+          createClientApiToken(clientId: $clientId, input: $input) {
+            success
+            plainTextToken
+          }
+        }`,
+        variables: {
+          clientId,
+          input: {
+            name: `ai-events-sdk · ${hostname()}`,
+            role: "agent-events",
+          },
+        },
+      }),
+    });
+    const body = await graphqlRes.json();
+    if (body.errors?.length) {
+      errLog(`API key mint failed: ${body.errors[0].message}`);
+      return { exitCode: 6 };
+    }
+    plainTextToken = body?.data?.createClientApiToken?.plainTextToken;
+    if (!plainTextToken) {
+      errLog("API key mint returned no plainTextToken");
+      return { exitCode: 6 };
+    }
+  } catch (err) {
+    errLog(`API key mint request failed: ${err.message}`);
+    return { exitCode: 6 };
+  }
+
+  // Write the long-lived credentials. Endpoint becomes the tenant
+  // subdomain so subsequent SDK calls hit the right OAuth realm.
+  const tenantEndpoint =
+    endpoint === "https://api.pentatonic.com"
+      ? `https://${clientId}.api.pentatonic.com`
+      : endpoint;
+
+  await writeCredentials({
+    endpoint: tenantEndpoint,
+    clientId,
+    apiKey: plainTextToken,
+  });
+
+  log("");
+  log(`  ✓ Connected as ${claims.email || "user"} on tenant \`${clientId}\``);
+  log(`  ✓ Credentials written to ~/.config/tes/credentials.json`);
+  log("");
+  log("  Claude Code's tes-memory plugin and the OpenClaw pentatonic-memory");
+  log("  plugin will pick these credentials up automatically — restart them");
+  log("  if they're already running.");
+  log("");
+
+  return { exitCode: 0, clientId };
+}
+
+/**
+ * `init` alias — deprecated for one major release. Emits a stderr
+ * warning then delegates to runLoginCommand. Removed in the next
+ * major version.
+ */
+export async function runInitAlias(opts = {}) {
+  const errLog = opts.errLog || ((m) => process.stderr.write(m + "\n"));
+  errLog("  Notice: `init` is deprecated, use `login` instead. (This alias will be removed in the next major release.)");
+  return runLoginCommand(opts);
+}
+
+function defaultOpenBrowser(url) {
+  const opener =
+    process.platform === "darwin"
+      ? "open"
+      : process.platform === "win32"
+        ? "start"
+        : "xdg-open";
+  execFileSync(opener, [url], { stdio: "ignore" });
+}
+
+function decodeJwtClaims(jwt) {
+  try {
+    const [, payload] = jwt.split(".");
+    const json = Buffer.from(payload.replace(/-/g, "+").replace(/_/g, "/"), "base64").toString("utf8");
+    return JSON.parse(json);
+  } catch {
+    return null;
+  }
+}

package/bin/commands/whoami.js

@@ -0,0 +1,41 @@
+import { readCredentials, pingTes } from "../lib/credentials.js";
+
+/**
+ * Run the SDK whoami command. Prints "logged in as X on tenant Y" or
+ * "not logged in" / "creds invalid" depending on the state of
+ * ~/.config/tes/credentials.json and a GraphQL ping.
+ *
+ * Originally named `status` in the design spec; renamed because the
+ * corpus subcommand `tes status` already exists (shows tracked repos).
+ * `whoami` matches the standard CLI convention for "who am I logged
+ * in as" and avoids the conflict.
+ */
+export async function runWhoamiCommand(opts = {}) {
+  const log = opts.log || ((m) => process.stdout.write(m + "\n"));
+  const errLog = opts.errLog || ((m) => process.stderr.write(m + "\n"));
+
+  const creds = await readCredentials();
+  if (!creds) {
+    log("");
+    log("  Not logged in. Run `npx @pentatonic-ai/ai-agent-sdk login` to connect.");
+    log("");
+    return { exitCode: 1 };
+  }
+
+  const ping = await pingTes(creds);
+  if (!ping.ok) {
+    if (ping.status === 401) {
+      errLog("  Credentials invalid (revoked or expired).");
+      errLog("  Run `npx @pentatonic-ai/ai-agent-sdk login` to refresh.");
+      return { exitCode: 2 };
+    }
+    errLog(`  Could not verify credentials: ${ping.error}`);
+    return { exitCode: 3 };
+  }
+
+  log("");
+  log(`  ✓ Logged in to tenant \`${creds.clientId}\` (${ping.clientName})`);
+  log(`  Endpoint: ${creds.endpoint}`);
+  log("");
+  return { exitCode: 0 };
+}

package/bin/lib/callback-server.js

@@ -0,0 +1,137 @@
+import { createServer } from "node:http";
+import { URL } from "node:url";
+
+const SUCCESS_HTML = `<!DOCTYPE html>
+<html><head><meta charset="utf-8"><title>Connected</title>
+<style>body{font-family:system-ui,sans-serif;max-width:480px;margin:80px auto;padding:24px;color:#1a1a1a;line-height:1.5}h1{font-size:1.4em}</style>
+</head><body>
+<h1>✓ Connected</h1>
+<p>The CLI now has a token. You can close this tab.</p>
+</body></html>`;
+
+const ERROR_HTML = (msg) => `<!DOCTYPE html>
+<html><head><meta charset="utf-8"><title>Error</title></head><body>
+<h1>Connection failed</h1><p>${msg.replace(/</g, "&lt;")}</p>
+<p>Return to the terminal and re-run the command.</p>
+</body></html>`;
+
+/**
+ * Start an HTTP server that listens for the OAuth localhost callback.
+ *
+ * Returns:
+ *   - port (number): the bound port (resolved before any callback hits)
+ *   - result (Promise<{code, state}>): resolves on first valid /callback
+ *     hit; rejects on state mismatch, malformed query, or timeout.
+ *   - cancel (function): close the server early without resolving.
+ *
+ * The server serves a tiny "you can close this tab" HTML page on the
+ * successful callback and closes itself after sending the response.
+ *
+ * @param {object} opts
+ * @param {number[]} opts.ports - Ordered list of ports to try; 0 means
+ *   "let the OS pick". The first port that binds wins.
+ * @param {string} opts.state - The expected state value; callback must
+ *   carry exactly this for resolution to fire.
+ * @param {number} [opts.timeoutMs=300000] - Default 5 min.
+ */
+export async function startCallbackServer({ ports, state, timeoutMs = 300_000 }) {
+  if (!Array.isArray(ports) || ports.length === 0) {
+    throw new Error("startCallbackServer: ports[] required");
+  }
+  if (typeof state !== "string" || state.length === 0) {
+    throw new Error("startCallbackServer: state required");
+  }
+
+  const server = createServer();
+  await tryBind(server, ports);
+  const boundPort = server.address().port;
+
+  let resolveResult, rejectResult;
+  const result = new Promise((res, rej) => {
+    resolveResult = res;
+    rejectResult = rej;
+  });
+  // Attach a no-op catch so cancelling without awaiting result doesn't
+  // raise an unhandled-rejection (kills the Node process under
+  // --unhandled-rejections=strict, the default in modern Node). Real
+  // callers can still attach .catch() later — promises support multiple
+  // handlers and only the LAST unhandled state matters.
+  result.catch(() => {});
+
+  const timer = setTimeout(() => {
+    rejectResult(new Error(`Login timed out after ${Math.round(timeoutMs / 1000)}s`));
+    server.close();
+  }, timeoutMs);
+
+  server.on("request", (req, res) => {
+    try {
+      const url = new URL(req.url, `http://localhost:${boundPort}`);
+      if (url.pathname !== "/callback") {
+        res.writeHead(404).end("Not Found");
+        return;
+      }
+      const code = url.searchParams.get("code");
+      const gotState = url.searchParams.get("state");
+      if (!code || !gotState) {
+        res.writeHead(400, { "Content-Type": "text/html" }).end(ERROR_HTML("Missing code or state"));
+        rejectResult(new Error("Callback missing code or state"));
+        clearTimeout(timer);
+        server.close();
+        return;
+      }
+      if (gotState !== state) {
+        res.writeHead(400, { "Content-Type": "text/html" }).end(ERROR_HTML("State mismatch"));
+        rejectResult(new Error("Callback state mismatch (CSRF / replay protection)"));
+        clearTimeout(timer);
+        server.close();
+        return;
+      }
+      res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" }).end(SUCCESS_HTML);
+      resolveResult({ code, state: gotState });
+      clearTimeout(timer);
+      server.close();
+    } catch (err) {
+      rejectResult(err);
+      clearTimeout(timer);
+      try { res.writeHead(500).end(); } catch {}
+      server.close();
+    }
+  });
+
+  return {
+    port: boundPort,
+    result,
+    cancel() {
+      clearTimeout(timer);
+      try { rejectResult(new Error("cancelled")); } catch {}
+      server.close();
+    },
+  };
+}
+
+function tryBind(server, ports) {
+  return new Promise((resolve, reject) => {
+    const tryNext = (i) => {
+      if (i >= ports.length) {
+        reject(new Error(`Could not bind to any of ports: ${ports.join(", ")}`));
+        return;
+      }
+      const onError = (err) => {
+        server.removeListener("listening", onListening);
+        if (err.code === "EADDRINUSE" || err.code === "EACCES") {
+          tryNext(i + 1);
+        } else {
+          reject(err);
+        }
+      };
+      const onListening = () => {
+        server.removeListener("error", onError);
+        resolve();
+      };
+      server.once("error", onError);
+      server.once("listening", onListening);
+      server.listen(ports[i], "127.0.0.1");
+    };
+    tryNext(0);
+  });
+}