@agent-play/cli 3.0.1 → 3.1.0

package/README.md

@@ -1,11 +1,13 @@
 # @agent-play/cli
 
-Command-line tool for **Agent Play**: sign in to the web app, create account API keys, and register agents (up to two per account) when the server uses a Redis-backed repository.
+Command-line tool for **Agent Play**: create a **main developer node** (platform signup), add **agent nodes**, **validate** those identities against the server, and manage agent registrations. The server must use a **Redis**-backed agent repository (`REDIS_URL` on the server).
+
+Authentication uses **`x-node-id`** and **`x-node-passw`** on every request **except** main-node creation, which sends hashed passphrase material in the JSON body to **`POST /api/nodes**.
 
 ## Documentation
 
 - **[Repository](https://github.com/wilforlan/agent-play)**  
-- **[CLI guide](https://github.com/wilforlan/agent-play/blob/main/docs/cli.md)** — `login`, `create-key`, `create`, `delete`  
+- **[CLI guide](https://github.com/wilforlan/agent-play/blob/main/docs/cli.md)** — full **Node setup** and **Node validation** sections  
 - **[API reference](https://wilforlan.github.io/agent-play/)** — TypeDoc  
 
 ## Install
@@ -15,3 +17,62 @@ npm install -g @agent-play/cli
 ```
 
 Binary name: **`agent-play`**.
+
+Default server URL: **`http://127.0.0.1:3000`**, or override with **`AGENT_PLAY_SERVER_URL`**.
+
+Root key for derivation: **`--root-file`**, **`AGENT_PLAY_ROOT_FILE_PATH`**, or a **`.root`** file under **`~/.agent-play/`** or the current working directory (must match the server’s `.root`).
+
+## Node setup
+
+1. **Server:** Redis (`REDIS_URL`) and a deployed web UI/API the CLI can reach (`AGENT_PLAY_SERVER_URL`).
+2. **Local `.root`:** Must match the server genesis root key (see resolution order above).
+3. **`create-main-node`** (`bootstrap-node`): prompts for server URL, generates a passphrase, registers **`POST /api/nodes`**, writes **`~/.agent-play/credentials.json`** with **`serverUrl`**, **`nodeId`**, and the human passphrase.
+4. **`create-agent-node`**: derives an agent node under your main node, **`POST /api/nodes/agent-node`**, appends to **`credentials.json` → `agentNodes`**.
+5. **`inspect-node`**, **`list-agent-nodes`**, **`delete-*`**, **`clear-node-credentials`**: inspect or tear down registrations; see **`docs/cli.md`** for the full table.
+
+> **@deprecated** **`POST /api/agents`** does not create agent **node** identity. Use **`POST /api/nodes/agent-node`**, then attach runtime data with **`world.addPlayer`**.
+
+## Node validation
+
+- **`validate-main-node`** — calls **`POST /api/nodes/validate`** for your main node id (uses **`credentials.json`** + **`.root`**).
+- **`validate-agent-node --all`** — validates every id in **`credentials.json` → `agentNodes`** (includes **`mainNodeId`** in the validate body).
+- **`validate-agent-node --agent-node-ids id1,id2`** — same for explicit ids.
+
+For Redis-direct checks (ops/CI), use **`node-tools`** script **`scripts/validate-node-derivative.mjs`**; details in **`docs/cli.md`** and **`docs/notes/node-id-v1-migration.md`**.
+
+## Commands
+
+| Command | Aliases | What it does |
+|--------|---------|----------------|
+| **`create-main-node`** | `bootstrap-node` | Sign up a **main** node: **`POST /api/nodes`** (no node headers), save **`~/.agent-play/credentials.json`**. Optional **`--root-file`**. |
+| **`inspect-node`** | — | **GET /api/nodes** — genesis id, main node, **agent node ids** (`create-agent-node`), and **runtime** agent rows (SDK metadata) if present. |
+| **`create-agent-node`** | `create` | **POST /api/nodes/agent-node** — new agent node under your main node. |
+| **`list-agent-nodes`** | `list` | **GET /api/agents** — lists registered agents. |
+| **`delete-agent-node`** | `delete`, `remove` | **DELETE /api/agents** — optional **`[agent-id]`**; if omitted, prompts. |
+| **`delete-main-node`** | — | **DELETE /api/nodes** — confirm by typing main node id; cascades. |
+| **`validate-main-node`** | — | **POST /api/nodes/validate** for main node id. |
+| **`validate-agent-node`** | — | **`--all`** or **`--agent-node-ids id1,id2,...`** — validate agent node ids. |
+| **`clear-node-credentials`** | — | Removes **`~/.agent-play/credentials.json`**. |
+
+## Genesis and main node
+
+Every **main node id** is derived from passphrase material and the platform **root key** (the **genesis** identity). **`inspect-node`** and **`create-main-node`** output should agree with **`.root`** when both sides use the same key.
+
+Node kinds: **`root` → `main` → `agent`**. Root has no passphrase; main and agent persist hashed material server-side.
+
+## Usage examples
+
+```bash
+npx agent-play create-main-node
+npx agent-play validate-main-node
+npx agent-play inspect-node
+npx agent-play create-agent-node
+npx agent-play validate-agent-node --all
+npx agent-play list-agent-nodes
+npx agent-play delete-agent-node
+npx agent-play delete-agent-node <agent-uuid>
+npx agent-play delete-main-node
+npx agent-play clear-node-credentials
+```
+
+For SDK usage after bootstrap, use **`RemotePlayWorld`** and register players with **`mainNodeId`** and **`agentId`** from the CLI output.

package/dist/.root

@@ -0,0 +1 @@
+87b6637b010478e48a83a8d445041ae4df5d607df7932153cdfee5c601e8e39e

package/dist/cli.js

@@ -1,134 +1,227 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { mkdir, readFile, unlink, writeFile } from "fs/promises";
+import { existsSync } from "fs";
+import { mkdir, unlink, writeFile } from "fs/promises";
 import { homedir } from "os";
-import { join } from "path";
+import { join, resolve } from "path";
 import { createInterface } from "readline/promises";
 import { stdin as input, stdout as output } from "process";
+import {
+  createNodeCredentialFromPassw,
+  deriveNodeIdFromPassword,
+  generateNodePassw,
+  hashNodePassword,
+  loadAgentPlayCredentialsFileFromPath,
+  loadRootKey
+} from "@agent-play/node-tools";
+function nodeAuthHeaders(cred) {
+  return {
+    "x-node-id": cred.nodeId,
+    "x-node-passw": hashNodePassword(cred.passw)
+  };
+}
+function parseAgentRows(agentsRaw) {
+  if (!Array.isArray(agentsRaw)) {
+    return [];
+  }
+  const agents = [];
+  for (const a of agentsRaw) {
+    if (typeof a !== "object" || a === null) continue;
+    const o = a;
+    if (typeof o.agentId === "string" && typeof o.name === "string") {
+      agents.push({ agentId: o.agentId, name: o.name });
+    }
+  }
+  return agents;
+}
 function credentialsPath() {
   return join(homedir(), ".agent-play", "credentials.json");
 }
 async function loadCredentials() {
-  try {
-    const raw = await readFile(credentialsPath(), "utf8");
-    const json = JSON.parse(raw);
-    if (typeof json !== "object" || json === null) return null;
-    const o = json;
-    if (typeof o.serverUrl !== "string" || typeof o.token !== "string") {
-      return null;
-    }
-    return { serverUrl: o.serverUrl.replace(/\/$/, ""), token: o.token };
-  } catch {
-    return null;
-  }
+  return loadAgentPlayCredentialsFileFromPath(credentialsPath());
 }
 async function saveCredentials(c) {
   const dir = join(homedir(), ".agent-play");
   await mkdir(dir, { recursive: true });
   await writeFile(
     credentialsPath(),
-    JSON.stringify({ serverUrl: c.serverUrl, token: c.token }, null, 2),
+    JSON.stringify(c, null, 2),
     "utf8"
   );
 }
-function defaultServerUrl() {
-  return process.env.AGENT_PLAY_SERVER_URL ?? "http://127.0.0.1:3000";
-}
-async function cmdLogin() {
-  const rl = createInterface({ input, output });
-  const serverUrl = ((await rl.question(
-    `Server URL [${defaultServerUrl()}]: `
-  )).trim() || defaultServerUrl()).replace(/\/$/, "");
-  const email = (await rl.question("Email: ")).trim();
-  if (email.length === 0) {
-    rl.close();
-    console.error("Email is required.");
-    process.exitCode = 1;
-    return;
+var BOOTSTRAP_ENVIRONMENTS = [
+  { id: "local-server", url: "http://127.0.0.1:3000" },
+  { id: "test-server", url: "https://test-agent-play.com" },
+  { id: "main-server", url: "https://agent-play.com" }
+];
+function parseBootstrapEnvironmentAnswer(raw) {
+  const t = raw.trim().toLowerCase();
+  if (t === "" || t === "1") {
+    return BOOTSTRAP_ENVIRONMENTS[0].url;
   }
-  const lookupRes = await fetch(`${serverUrl}/api/auth/lookup`, {
-    method: "POST",
-    headers: { "content-type": "application/json" },
-    body: JSON.stringify({ email })
-  });
-  const lookupText = await lookupRes.text();
-  if (!lookupRes.ok) {
-    rl.close();
-    console.error(`Lookup failed (${lookupRes.status}): ${lookupText}`);
-    process.exitCode = 1;
-    return;
+  if (t === "2") {
+    return BOOTSTRAP_ENVIRONMENTS[1].url;
   }
-  let lookupJson;
-  try {
-    lookupJson = JSON.parse(lookupText);
-  } catch {
-    rl.close();
-    console.error("Invalid JSON from server.");
-    process.exitCode = 1;
-    return;
+  if (t === "3") {
+    return BOOTSTRAP_ENVIRONMENTS[2].url;
   }
-  const exists = typeof lookupJson === "object" && lookupJson !== null && lookupJson.exists === true;
-  let token;
-  if (exists) {
-    const password = (await rl.question("Password: ")).trim();
-    rl.close();
-    const loginRes = await fetch(`${serverUrl}/api/auth/login`, {
-      method: "POST",
-      headers: { "content-type": "application/json" },
-      body: JSON.stringify({ email, password })
-    });
-    const loginText = await loginRes.text();
-    if (!loginRes.ok) {
-      console.error(`Login failed (${loginRes.status}): ${loginText}`);
-      process.exitCode = 1;
-      return;
+  for (const e of BOOTSTRAP_ENVIRONMENTS) {
+    if (t === e.id) {
+      return e.url;
     }
-    const loginJson = JSON.parse(loginText);
-    if (typeof loginJson.token !== "string") {
-      console.error("Missing token in response.");
-      process.exitCode = 1;
-      return;
+  }
+  if (t === "local") {
+    return BOOTSTRAP_ENVIRONMENTS[0].url;
+  }
+  if (t === "test") {
+    return BOOTSTRAP_ENVIRONMENTS[1].url;
+  }
+  if (t === "main") {
+    return BOOTSTRAP_ENVIRONMENTS[2].url;
+  }
+  return null;
+}
+async function promptBootstrapEnvironment(rl) {
+  const lines = [
+    "Choose environment (sets server URL):",
+    `  1) ${BOOTSTRAP_ENVIRONMENTS[0].id}  \u2192 ${BOOTSTRAP_ENVIRONMENTS[0].url}`,
+    `  2) ${BOOTSTRAP_ENVIRONMENTS[1].id}   \u2192 ${BOOTSTRAP_ENVIRONMENTS[1].url}`,
+    `  3) ${BOOTSTRAP_ENVIRONMENTS[2].id}   \u2192 ${BOOTSTRAP_ENVIRONMENTS[2].url}`,
+    "Enter 1\u20133, or local-server / test-server / main-server [1]: "
+  ].join("\n");
+  for (; ; ) {
+    const answer = await rl.question(lines);
+    const url = parseBootstrapEnvironmentAnswer(answer);
+    if (url !== null) {
+      return url.replace(/\/$/, "");
     }
-    token = loginJson.token;
-  } else {
-    const name = (await rl.question("Your name: ")).trim() || "User";
-    const password = (await rl.question("Choose a password (min 8 chars): ")).trim();
-    if (password.length < 8) {
-      rl.close();
-      console.error("Password must be at least 8 characters.");
-      process.exitCode = 1;
-      return;
+    console.log(
+      "Invalid choice. Enter 1, 2, or 3, or one of: local-server, test-server, main-server."
+    );
+  }
+}
+function parseBootstrapNodeArgs(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--root-file" && typeof argv[i + 1] === "string") {
+      out.rootFilePath = argv[++i];
     }
-    rl.close();
-    const regRes = await fetch(`${serverUrl}/api/auth/register`, {
-      method: "POST",
-      headers: { "content-type": "application/json" },
-      body: JSON.stringify({ email, name, password })
-    });
-    const regText = await regRes.text();
-    if (!regRes.ok) {
-      console.error(`Sign up failed (${regRes.status}): ${regText}`);
-      process.exitCode = 1;
-      return;
+  }
+  return out;
+}
+function parseValidateAgentNodeArgs(argv) {
+  let wantsAll = false;
+  let ids = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--all") {
+      wantsAll = true;
+      continue;
     }
-    const regJson = JSON.parse(regText);
-    if (typeof regJson.token !== "string") {
-      console.error("Missing token in response.");
-      process.exitCode = 1;
-      return;
+    if (a === "--agent-node-ids" && typeof argv[i + 1] === "string") {
+      const raw = argv[++i].trim();
+      ids = raw.split(",").map((x) => x.trim()).filter((x) => x.length > 0);
+      continue;
+    }
+    return null;
+  }
+  if (wantsAll) {
+    return { mode: "all" };
+  }
+  if (ids.length > 0) {
+    return { mode: "ids", agentNodeIds: ids };
+  }
+  return null;
+}
+function resolveAgentPlayRootPath(options) {
+  if (typeof options.rootFilePath === "string" && options.rootFilePath.trim().length > 0) {
+    return resolve(options.rootFilePath.trim());
+  }
+  const fromEnv = process.env.AGENT_PLAY_ROOT_FILE_PATH;
+  if (typeof fromEnv === "string" && fromEnv.trim().length > 0) {
+    return resolve(fromEnv.trim());
+  }
+  const homeRoot = join(homedir(), ".agent-play", ".root");
+  if (existsSync(homeRoot)) {
+    return homeRoot;
+  }
+  const cwdRoot = resolve(process.cwd(), ".root");
+  if (existsSync(cwdRoot)) {
+    return cwdRoot;
+  }
+  throw new Error(
+    "Agent Play root key not found. Pass --root-file <path>, set AGENT_PLAY_ROOT_FILE_PATH, or place .root in ~/.agent-play/ or the project directory."
+  );
+}
+async function registerNodeOnServer(serverUrl, passw, expectedNodeId) {
+  const res = await fetch(`${serverUrl}/api/nodes`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ kind: "main", passw })
+  });
+  const text = await res.text();
+  if (res.status === 409) {
+    return;
+  }
+  if (!res.ok) {
+    let msg = text;
+    try {
+      const err = JSON.parse(text);
+      if (typeof err.error === "string") {
+        msg = err.error;
+      }
+    } catch {
     }
-    token = regJson.token;
+    throw new Error(
+      `Node registration failed (${String(res.status)}): ${msg}`
+    );
+  }
+  const json = JSON.parse(text);
+  if (typeof json.nodeId !== "string") {
+    throw new Error("Invalid response from server.");
+  }
+  if (json.nodeId !== expectedNodeId) {
+    console.log("json", json);
+    console.log("expectedNodeId", expectedNodeId);
+    throw new Error(
+      "Server node id does not match local derivation; check root file and server configuration."
+    );
   }
-  await saveCredentials({ serverUrl, token });
-  console.log(`Signed in. Credentials saved to ${credentialsPath()}`);
 }
-async function cmdLogout() {
+async function cmdBootstrapNode(argv) {
+  const opts = parseBootstrapNodeArgs(argv);
+  const rl = createInterface({ input, output });
+  const serverUrl = await promptBootstrapEnvironment(rl);
+  rl.close();
+  console.log(`Using server: ${serverUrl}`);
+  const rootPath = resolveAgentPlayRootPath(opts);
+  const rootKey = loadRootKey(rootPath);
+  const dir = join(homedir(), ".agent-play");
+  await mkdir(dir, { recursive: true });
+  const generatedPassw = generateNodePassw();
+  const hashedPassw = hashNodePassword(generatedPassw);
+  const credential = createNodeCredentialFromPassw({ passw: hashedPassw, rootKey });
+  await registerNodeOnServer(serverUrl, hashedPassw, credential.nodeId);
+  await saveCredentials({
+    serverUrl,
+    nodeId: credential.nodeId,
+    passw: generatedPassw
+  });
+  console.log(
+    `genesisNodeId (platform root key from .root; all main nodes derive under this): ${rootKey}`
+  );
+  console.log(`mainNodeId (your developer node): ${credential.nodeId}`);
+  console.log(`passw: ${generatedPassw}`);
+  console.log("Keep this material safe. Losing it means losing access.");
+}
+async function cmdClearNodeCredentials() {
   try {
     await unlink(credentialsPath());
-    console.log("Logged out.");
+    console.log("Credentials removed.");
   } catch {
-    console.log("No saved session.");
+    console.log("No saved credentials.");
   }
 }
 function printAgentPlayIntegrationGuide() {
@@ -136,7 +229,7 @@ function printAgentPlayIntegrationGuide() {
   console.log("How your agent appears on the play world");
   console.log("\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
   console.log(
-    "  \u2022 One account API key: run `agent-play create-key` (after login) if you do not have one yet."
+    "  \u2022 Use ~/.agent-play/credentials.json + .root with RemotePlayWorld({ nodeCredentials })."
   );
   console.log(
     "  \u2022 LangChain: use langchainRegistration(agent) and pass agent.toolNames to addPlayer."
@@ -148,22 +241,38 @@ function printAgentPlayIntegrationGuide() {
     "  \u2022 Structures on the map are derived from those tool names \u2014 keep them aligned with your real tools."
   );
   console.log(
-    "  \u2022 RemotePlayWorld({ apiKey: <account key> }) and addPlayer({ ..., agentId: <id below> })."
+    "  \u2022 RemotePlayWorld({ nodeCredentials: { rootKey, passw } }) and addAgent({ nodeId, ... })."
   );
   console.log("");
 }
-async function cmdCreateKey() {
+async function cmdCreateAgentNode() {
   const cred = await loadCredentials();
   if (cred === null) {
-    console.error("Run `agent-play login` first.");
+    console.error(
+      "Run `agent-play create-main-node` (or `bootstrap-node`) first."
+    );
     process.exitCode = 1;
     return;
   }
-  const res = await fetch(`${cred.serverUrl}/api/agents/api-key`, {
+  const rootKey = loadRootKey(resolveAgentPlayRootPath({}));
+  const agentPassw = generateNodePassw();
+  const hashedAgentPassw = hashNodePassword(agentPassw);
+  const agentNodeId = deriveNodeIdFromPassword({
+    password: hashedAgentPassw,
+    rootKey
+  });
+  const res = await fetch(`${cred.serverUrl}/api/nodes/agent-node`, {
     method: "POST",
     headers: {
-      authorization: `Bearer ${cred.token}`
-    }
+      "content-type": "application/json",
+      ...nodeAuthHeaders(cred)
+    },
+    body: JSON.stringify({
+      kind: "agent",
+      parentNodeId: cred.nodeId,
+      agentNodeId,
+      agentNodePassw: hashedAgentPassw
+    })
   });
   const text = await res.text();
   if (!res.ok) {
@@ -173,65 +282,55 @@ async function cmdCreateKey() {
       if (typeof err.error === "string") msg = err.error;
     } catch {
     }
-    console.error(`create-key failed (${res.status}): ${msg}`);
+    console.error(`Create failed (${res.status}): ${msg}`);
     process.exitCode = 1;
     return;
   }
   const json = JSON.parse(text);
-  if (typeof json.plainApiKey !== "string") {
+  if (typeof json.agentId !== "string") {
     console.error("Invalid response from server.");
     process.exitCode = 1;
     return;
   }
-  console.log("API key (store securely; shown once):");
-  console.log(json.plainApiKey);
-  console.log("");
-}
-async function cmdViewKeys() {
-  const cred = await loadCredentials();
-  if (cred === null) {
-    console.error("Run `agent-play login` first.");
+  if (json.agentId !== agentNodeId) {
+    console.error(
+      "Server returned a different agent node id than the locally derived one."
+    );
     process.exitCode = 1;
     return;
   }
-  const res = await fetch(`${cred.serverUrl}/api/agents/api-key`, {
-    headers: { authorization: `Bearer ${cred.token}` }
+  const nextAgentNodes = [
+    ...(cred.agentNodes ?? []).filter((n) => n.nodeId !== agentNodeId),
+    {
+      nodeId: agentNodeId,
+      passw: agentPassw,
+      createdAt: (/* @__PURE__ */ new Date()).toISOString()
+    }
+  ];
+  await saveCredentials({
+    ...cred,
+    agentNodes: nextAgentNodes
   });
-  const text = await res.text();
-  if (!res.ok) {
-    console.error(`view-keys failed (${res.status}): ${text}`);
-    process.exitCode = 1;
-    return;
-  }
-  const json = JSON.parse(text);
-  if (json.hasKey === true) {
-    const when = typeof json.createdAt === "string" ? json.createdAt : "unknown time";
-    console.log(`Account API key: active (created ${when}).`);
-    console.log(
-      "The secret value cannot be shown again. Use the key you saved when you ran `agent-play create-key`."
-    );
-  } else {
-    console.log("No API key for this account.");
-    console.log("Run `agent-play create-key` to generate one (shown once).");
-  }
+  printAgentPlayIntegrationGuide();
+  console.log(`Created agent node id: ${json.agentId}`);
+  console.log(`Agent node passw: ${agentPassw}`);
+  console.log(
+    `Saved agent node credentials to ${credentialsPath()} (agentNodes).`
+  );
+  console.log("Keep this material safe. Losing it means losing access.");
+  console.log("");
 }
-async function cmdCreate() {
+async function cmdInspectNode() {
   const cred = await loadCredentials();
   if (cred === null) {
-    console.error("Run `agent-play login` first.");
+    console.error(
+      "Run `agent-play create-main-node` (or `bootstrap-node`) first."
+    );
     process.exitCode = 1;
     return;
   }
-  const rl = createInterface({ input, output });
-  const name = (await rl.question("Agent name: ")).trim() || "agent";
-  rl.close();
-  const res = await fetch(`${cred.serverUrl}/api/agents`, {
-    method: "POST",
-    headers: {
-      "content-type": "application/json",
-      authorization: `Bearer ${cred.token}`
-    },
-    body: JSON.stringify({ name })
+  const res = await fetch(`${cred.serverUrl}/api/nodes`, {
+    headers: nodeAuthHeaders(cred)
   });
   const text = await res.text();
   if (!res.ok) {
@@ -241,29 +340,71 @@ async function cmdCreate() {
       if (typeof err.error === "string") msg = err.error;
     } catch {
     }
-    console.error(`Create failed (${res.status}): ${msg}`);
+    console.error(`Inspect failed (${res.status}): ${msg}`);
     process.exitCode = 1;
     return;
   }
   const json = JSON.parse(text);
-  if (typeof json.agentId !== "string") {
-    console.error("Invalid response from server.");
+  if (typeof json.genesisNodeId !== "string") {
+    console.error("Invalid inspect response.");
     process.exitCode = 1;
     return;
   }
-  printAgentPlayIntegrationGuide();
-  console.log(`Created agent id: ${json.agentId}`);
+  const main2 = json.mainNode;
+  if (typeof main2 !== "object" || main2 === null) {
+    console.error("Invalid inspect response.");
+    process.exitCode = 1;
+    return;
+  }
+  const mn = main2;
+  if (typeof mn.nodeId !== "string" || typeof mn.createdAt !== "string") {
+    console.error("Invalid inspect response.");
+    process.exitCode = 1;
+    return;
+  }
+  const agentNodeIdsFromMain = Array.isArray(mn.agentNodeIds) ? mn.agentNodeIds.filter((x) => typeof x === "string") : [];
+  const runtimeAgents = parseAgentRows(json.agentNodes);
+  console.log("Platform genesis node id (from server .root / root key):");
+  console.log(`  ${json.genesisNodeId}`);
+  console.log("");
+  console.log("Your main developer node:");
+  console.log(`  nodeId:    ${mn.nodeId}`);
+  console.log(`  createdAt: ${mn.createdAt}`);
+  console.log("");
+  console.log(
+    `Agent node identities (create-agent-node) (${String(agentNodeIdsFromMain.length)}):`
+  );
+  if (agentNodeIdsFromMain.length === 0) {
+    console.log("  (none)");
+  } else {
+    agentNodeIdsFromMain.forEach((id, i) => {
+      console.log(`  ${String(i + 1)}. ${id}`);
+    });
+  }
+  console.log("");
+  console.log(
+    `Runtime agents \u2014 SDK metadata (${String(runtimeAgents.length)}):`
+  );
+  if (runtimeAgents.length === 0) {
+    console.log("  (none)");
+  } else {
+    runtimeAgents.forEach((a, i) => {
+      console.log(`  ${String(i + 1)}. ${a.agentId} \u2014 ${a.name}`);
+    });
+  }
   console.log("");
 }
-async function cmdDelete() {
+async function cmdListAgentNodes() {
   const cred = await loadCredentials();
   if (cred === null) {
-    console.error("Run `agent-play login` first.");
+    console.error(
+      "Run `agent-play create-main-node` (or `bootstrap-node`) first."
+    );
     process.exitCode = 1;
     return;
   }
   const listRes = await fetch(`${cred.serverUrl}/api/agents`, {
-    headers: { authorization: `Bearer ${cred.token}` }
+    headers: nodeAuthHeaders(cred)
   });
   const listText = await listRes.text();
   if (!listRes.ok) {
@@ -272,30 +413,48 @@ async function cmdDelete() {
     return;
   }
   const listJson = JSON.parse(listText);
-  const agentsRaw = listJson.agents;
-  if (!Array.isArray(agentsRaw)) {
-    console.error("Invalid list response.");
-    process.exitCode = 1;
-    return;
-  }
-  const agents = [];
-  for (const a of agentsRaw) {
-    if (typeof a !== "object" || a === null) continue;
-    const o = a;
-    if (typeof o.agentId === "string" && typeof o.name === "string") {
-      agents.push({ agentId: o.agentId, name: o.name });
-    }
-  }
+  const agents = parseAgentRows(listJson.agents);
   if (agents.length === 0) {
-    console.log("No agents.");
+    console.log("No agent nodes.");
     return;
   }
   agents.forEach((a, i) => {
-    console.log(`${i + 1}. ${a.agentId} (${a.name})`);
+    console.log(`${String(i + 1)}. ${a.agentId} (${a.name})`);
   });
-  const rl = createInterface({ input, output });
-  const pick = (await rl.question("Agent id to delete (empty = cancel): ")).trim();
-  rl.close();
+}
+async function cmdDeleteAgentNode(argv) {
+  const cred = await loadCredentials();
+  if (cred === null) {
+    console.error(
+      "Run `agent-play create-main-node` (or `bootstrap-node`) first."
+    );
+    process.exitCode = 1;
+    return;
+  }
+  let pick = argv[0]?.trim() ?? "";
+  if (pick.length === 0) {
+    const listRes = await fetch(`${cred.serverUrl}/api/agents`, {
+      headers: nodeAuthHeaders(cred)
+    });
+    const listText = await listRes.text();
+    if (!listRes.ok) {
+      console.error(`List failed (${listRes.status}): ${listText}`);
+      process.exitCode = 1;
+      return;
+    }
+    const listJson = JSON.parse(listText);
+    const agents = parseAgentRows(listJson.agents);
+    if (agents.length === 0) {
+      console.log("No agents.");
+      return;
+    }
+    agents.forEach((a, i) => {
+      console.log(`${i + 1}. ${a.agentId} (${a.name})`);
+    });
+    const rl = createInterface({ input, output });
+    pick = (await rl.question("Agent id to delete (empty = cancel): ")).trim();
+    rl.close();
+  }
   if (pick.length === 0) {
     console.log("Cancelled.");
     return;
@@ -304,7 +463,7 @@ async function cmdDelete() {
     `${cred.serverUrl}/api/agents?id=${encodeURIComponent(pick)}`,
     {
       method: "DELETE",
-      headers: { authorization: `Bearer ${cred.token}` }
+      headers: nodeAuthHeaders(cred)
     }
   );
   const delText = await delRes.text();
@@ -316,34 +475,225 @@ async function cmdDelete() {
   const delJson = JSON.parse(delText);
   console.log(delJson.ok === true ? "Deleted." : "Not found.");
 }
+async function cmdDeleteMainNode() {
+  const cred = await loadCredentials();
+  if (cred === null) {
+    console.error(
+      "Run `agent-play create-main-node` (or `bootstrap-node`) first."
+    );
+    process.exitCode = 1;
+    return;
+  }
+  console.error("");
+  console.error("WARNING: You are about to delete your main developer node.");
+  console.error(
+    "The server will remove this node and cascade-delete every registered"
+  );
+  console.error(
+    "agent node (SDK agent registration) that belongs to it. This cannot be undone."
+  );
+  console.error(
+    "You will need a new passphrase and secret file to join the platform again."
+  );
+  console.error("");
+  const rl = createInterface({ input, output });
+  const typed = (await rl.question(
+    `Type your main node id exactly to confirm (${cred.nodeId}): `
+  )).trim();
+  rl.close();
+  if (typed !== cred.nodeId) {
+    console.log("Confirmation did not match. Cancelled.");
+    return;
+  }
+  const res = await fetch(`${cred.serverUrl}/api/nodes`, {
+    method: "DELETE",
+    headers: {
+      "content-type": "application/json",
+      ...nodeAuthHeaders(cred)
+    },
+    body: JSON.stringify({ confirmNodeId: cred.nodeId })
+  });
+  const text = await res.text();
+  if (!res.ok) {
+    let msg = text;
+    try {
+      const err = JSON.parse(text);
+      if (typeof err.error === "string") msg = err.error;
+    } catch {
+    }
+    console.error(`Delete main node failed (${res.status}): ${msg}`);
+    process.exitCode = 1;
+    return;
+  }
+  const json = JSON.parse(text);
+  if (json.ok !== true) {
+    console.error("Unexpected response from server.");
+    process.exitCode = 1;
+    return;
+  }
+  const n = typeof json.deletedAgentCount === "number" ? json.deletedAgentCount : 0;
+  console.log(
+    `Main node removed. Cascaded agent nodes deleted: ${String(n)}.`
+  );
+  console.log("Run `agent-play clear-node-credentials` to forget local creds.");
+}
+async function validateNodeIdentityOnServer(options) {
+  const res = await fetch(`${options.cred.serverUrl}/api/nodes/validate`, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      ...nodeAuthHeaders(options.cred)
+    },
+    body: JSON.stringify({
+      nodeId: options.nodeId,
+      rootKey: options.rootKey,
+      mainNodeId: options.mainNodeId
+    })
+  });
+  const text = await res.text();
+  let json;
+  try {
+    json = JSON.parse(text);
+  } catch {
+    throw new Error(`Validate failed (${String(res.status)}): ${text}`);
+  }
+  if (typeof json !== "object" || json === null) {
+    throw new Error(`Validate failed (${String(res.status)}): invalid response`);
+  }
+  const obj = json;
+  if (typeof obj.ok !== "boolean") {
+    const err = typeof obj.error === "string" ? obj.error : text;
+    throw new Error(`Validate failed (${String(res.status)}): ${err}`);
+  }
+  return {
+    ok: obj.ok,
+    reason: typeof obj.reason === "string" ? obj.reason : void 0,
+    nodeKind: typeof obj.nodeKind === "string" ? obj.nodeKind : void 0
+  };
+}
+async function cmdValidateMainNode() {
+  const cred = await loadCredentials();
+  if (cred === null) {
+    console.error(
+      "Run `agent-play create-main-node` (or `bootstrap-node`) first."
+    );
+    process.exitCode = 1;
+    return;
+  }
+  const rootKey = loadRootKey(resolveAgentPlayRootPath({}));
+  const result = await validateNodeIdentityOnServer({
+    cred,
+    rootKey,
+    nodeId: cred.nodeId
+  });
+  if (!result.ok) {
+    console.error(
+      `Main node validation failed: ${result.reason ?? "unknown reason"}`
+    );
+    process.exitCode = 1;
+    return;
+  }
+  console.log(`Main node validation passed: ${cred.nodeId}`);
+}
+async function cmdValidateAgentNode(argv) {
+  const cred = await loadCredentials();
+  if (cred === null) {
+    console.error(
+      "Run `agent-play create-main-node` (or `bootstrap-node`) first."
+    );
+    process.exitCode = 1;
+    return;
+  }
+  const opts = parseValidateAgentNodeArgs(argv);
+  if (opts === null) {
+    console.error(
+      "Usage: agent-play validate-agent-node --all | --agent-node-ids <id1,id2,...>"
+    );
+    process.exitCode = 1;
+    return;
+  }
+  const rootKey = loadRootKey(resolveAgentPlayRootPath({}));
+  const targetIds = opts.mode === "all" ? (cred.agentNodes ?? []).map((n) => n.nodeId) : opts.agentNodeIds;
+  const dedupedIds = Array.from(new Set(targetIds.filter((id) => id.length > 0)));
+  if (dedupedIds.length === 0) {
+    console.log("No agent node ids to validate.");
+    return;
+  }
+  let failures = 0;
+  for (const nodeId of dedupedIds) {
+    const result = await validateNodeIdentityOnServer({
+      cred,
+      rootKey,
+      nodeId,
+      mainNodeId: cred.nodeId
+    });
+    if (!result.ok) {
+      failures += 1;
+      console.error(
+        `FAIL ${nodeId}: ${result.reason ?? "unknown reason"}`
+      );
+      continue;
+    }
+    console.log(`PASS ${nodeId}`);
+  }
+  if (failures > 0) {
+    process.exitCode = 1;
+    return;
+  }
+  console.log(`Validated ${String(dedupedIds.length)} agent node(s) successfully.`);
+}
 async function main() {
   const cmd = process.argv[2];
-  if (cmd === "login") {
-    await cmdLogin();
+  if (cmd === "bootstrap-node" || cmd === "create-main-node") {
+    await cmdBootstrapNode(process.argv.slice(3));
+    return;
+  }
+  if (cmd === "clear-node-credentials") {
+    await cmdClearNodeCredentials();
+    return;
+  }
+  if (cmd === "inspect-node") {
+    await cmdInspectNode();
+    return;
+  }
+  if (cmd === "create-agent-node" || cmd === "create") {
+    await cmdCreateAgentNode();
     return;
   }
-  if (cmd === "logout") {
-    await cmdLogout();
+  if (cmd === "list-agent-nodes" || cmd === "list") {
+    await cmdListAgentNodes();
     return;
   }
-  if (cmd === "create") {
-    await cmdCreate();
+  if (cmd === "delete-agent-node" || cmd === "delete" || cmd === "remove") {
+    await cmdDeleteAgentNode(process.argv.slice(3));
     return;
   }
-  if (cmd === "create-key" || cmd === "generate-key") {
-    await cmdCreateKey();
+  if (cmd === "delete-main-node") {
+    await cmdDeleteMainNode();
     return;
   }
-  if (cmd === "view-keys") {
-    await cmdViewKeys();
+  if (cmd === "validate-main-node") {
+    await cmdValidateMainNode();
     return;
   }
-  if (cmd === "delete" || cmd === "remove") {
-    await cmdDelete();
+  if (cmd === "validate-agent-node") {
+    await cmdValidateAgentNode(process.argv.slice(3));
     return;
   }
   console.error(
-    "Usage: agent-play login | logout | create-key | view-keys | create | delete"
+    [
+      "Usage:",
+      "  agent-play create-main-node | bootstrap-node [--root-file <path>]",
+      "  agent-play inspect-node",
+      "  agent-play create-agent-node | create",
+      "  agent-play list-agent-nodes | list",
+      "  agent-play delete-agent-node | delete [agent-id]",
+      "  agent-play delete-main-node",
+      "  agent-play validate-main-node",
+      "  agent-play validate-agent-node --all",
+      "  agent-play validate-agent-node --agent-node-ids <id1,id2,...>",
+      "  agent-play clear-node-credentials"
+    ].join("\n")
   );
   process.exitCode = 1;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-play/cli",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "description": "Command-line tool for Agent Play: login, API keys, and agent registration against the web UI.",
   "private": false,
   "type": "module",
@@ -20,9 +20,11 @@
     "access": "public"
   },
   "scripts": {
-    "build": "tsup src/cli.ts --format esm --platform node --target node20 --out-dir dist --clean"
+    "build": "tsup src/cli.ts --format esm --platform node --target node20 --out-dir dist --clean --external @agent-play/node-tools && node ../../scripts/copy-root-file.mjs cli"
+  },
+  "dependencies": {
+    "@agent-play/node-tools": "1.0.0"
   },
-  "dependencies": {},
   "devDependencies": {
     "@types/node": "^22.10.0",
     "tsup": "^8.5.1",