@agent-play/cli 3.0.1 → 3.2.0

package/dist/cli.js

@@ -1,134 +1,564 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { mkdir, readFile, unlink, writeFile } from "fs/promises";
+import { existsSync as existsSync2 } from "fs";
+import { mkdir as mkdir2, unlink, writeFile as writeFile2 } from "fs/promises";
 import { homedir } from "os";
-import { join } from "path";
+import { join as join2, resolve as resolve2 } from "path";
 import { createInterface } from "readline/promises";
 import { stdin as input, stdout as output } from "process";
-function credentialsPath() {
-  return join(homedir(), ".agent-play", "credentials.json");
+import {
+  createNodeCredentialFromPassw,
+  deriveNodeIdFromPassword,
+  generateNodePassw,
+  hashNodePassword,
+  loadAgentPlayCredentialsFileFromPath,
+  loadRootKey
+} from "@agent-play/node-tools";
+
+// src/initialize.ts
+import { existsSync } from "fs";
+import { mkdir, readdir, readFile, writeFile } from "fs/promises";
+import { dirname, join, resolve } from "path";
+import { fileURLToPath } from "url";
+function resolveServerUrlForEnvironment(environment) {
+  if (environment === "test") {
+    return "https://test-agent-play.com";
+  }
+  if (environment === "production") {
+    return "https://agent-play.com";
+  }
+  return "http://127.0.0.1:3000";
 }
-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") {
+var TEMPLATE_ROOT = fileURLToPath(
+  new URL("../templates/agent-starter/langchain", import.meta.url)
+);
+function parseInitializeArgs(argv) {
+  const out = {
+    template: "langchain",
+    yes: false,
+    force: false
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i];
+    if (token === "--dir" && typeof argv[i + 1] === "string") {
+      out.dir = argv[++i];
+      continue;
+    }
+    if (token === "--name" && typeof argv[i + 1] === "string") {
+      out.name = argv[++i];
+      continue;
+    }
+    if (token === "--template" && typeof argv[i + 1] === "string") {
+      const template = argv[++i];
+      if (template !== "langchain") {
+        return null;
+      }
+      out.template = template;
+      continue;
+    }
+    if (token === "--yes") {
+      out.yes = true;
+      continue;
+    }
+    if (token === "--force") {
+      out.force = true;
+      continue;
+    }
+    if (token === "--bootstrap-nodes") {
+      out.bootstrapNodes = true;
+      continue;
+    }
+    if (token === "--agent-count" && typeof argv[i + 1] === "string") {
+      const raw = Number(argv[++i]);
+      if (raw !== 1 && raw !== 2) {
+        return null;
+      }
+      out.agentCount = raw;
+      continue;
+    }
+    if (token === "--environment" && typeof argv[i + 1] === "string") {
+      const value = argv[++i].trim().toLowerCase();
+      if (value === "development" || value === "test" || value === "production") {
+        out.environment = value;
+        continue;
+      }
+      return null;
+    }
+    if (token === "--server-type" && typeof argv[i + 1] === "string") {
+      const value = argv[++i].trim().toLowerCase();
+      if (value === "bare" || value === "express") {
+        out.serverType = value;
+        continue;
+      }
       return null;
     }
-    return { serverUrl: o.serverUrl.replace(/\/$/, ""), token: o.token };
-  } catch {
     return null;
   }
+  return out;
+}
+function normalizeProjectName(raw) {
+  if (typeof raw !== "string") {
+    return "agent-play-agent-starter";
+  }
+  const normalized = raw.trim().toLowerCase().replace(/[^a-z0-9-_]+/g, "-");
+  if (normalized.length === 0) {
+    return "agent-play-agent-starter";
+  }
+  return normalized;
+}
+async function listTemplateFiles(dir) {
+  const entries = await readdir(dir, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      const nested = await listTemplateFiles(full);
+      files.push(...nested.map((path) => join(entry.name, path)));
+      continue;
+    }
+    files.push(entry.name);
+  }
+  return files;
+}
+async function ensureSafeTarget(options) {
+  const targetExists = existsSync(options.targetDir);
+  if (!targetExists) {
+    await mkdir(options.targetDir, { recursive: true });
+    return;
+  }
+  if (options.force) {
+    return;
+  }
+  const existing = await readdir(options.targetDir);
+  if (existing.length > 0) {
+    throw new Error(
+      `Target directory is not empty: ${options.targetDir}. Re-run with --force to overwrite scaffold-managed files.`
+    );
+  }
+}
+function patchEnvContent(options) {
+  const lines = options.envContent.split(/\r?\n/);
+  const updates = /* @__PURE__ */ new Map([
+    ["AGENT_PLAY_WEB_UI_URL", options.serverUrl],
+    ["AGENT_PLAY_MAIN_NODE_ID", options.mainNodeId],
+    ["AGENT_PLAY_AGENT_NODE_ID_1", options.agentNodeIds[0] ?? ""],
+    ["AGENT_PLAY_AGENT_NODE_ID_2", options.agentNodeIds[1] ?? ""]
+  ]);
+  const seen = /* @__PURE__ */ new Set();
+  const next = lines.map((line) => {
+    const eqIndex = line.indexOf("=");
+    if (eqIndex <= 0) {
+      return line;
+    }
+    const key = line.slice(0, eqIndex);
+    const update = updates.get(key);
+    if (update === void 0) {
+      return line;
+    }
+    seen.add(key);
+    return `${key}=${update}`;
+  });
+  for (const [key, value] of updates.entries()) {
+    if (!seen.has(key)) {
+      next.push(`${key}=${value}`);
+    }
+  }
+  return next.join("\n");
+}
+async function renderTemplate(options) {
+  const files = await listTemplateFiles(TEMPLATE_ROOT);
+  for (const relativePath of files) {
+    const templatePath = join(TEMPLATE_ROOT, relativePath);
+    const targetPath = join(options.targetDir, relativePath);
+    if (!options.force && existsSync(targetPath)) {
+      continue;
+    }
+    await mkdir(dirname(targetPath), { recursive: true });
+    const source = await readFile(templatePath, "utf8");
+    const serverModule = options.serverType === "express" ? "./express-server.js" : "./bare-server.js";
+    const content = source.replaceAll("__PROJECT_NAME__", options.projectName).replaceAll("__AGENT_NAME__", "Starter Agent").replaceAll("__SERVER_MODULE__", serverModule);
+    await writeFile(targetPath, content, "utf8");
+  }
+}
+async function cmdInitialize(options) {
+  const parsed = parseInitializeArgs(options.argv);
+  if (parsed === null) {
+    throw new Error(
+      "Usage: agent-play initialize [--dir <path>] [--name <project-name>] [--template langchain] [--environment <development|test|production>] [--server-type <bare|express>] [--yes] [--force] [--bootstrap-nodes] [--agent-count <1|2>]"
+    );
+  }
+  const targetDir = resolve(parsed.dir ?? process.cwd());
+  const projectName = normalizeProjectName(parsed.name ?? basenameFromPath(targetDir));
+  const environment = parsed.environment ?? (parsed.yes ? "development" : await options.promptApi.askEnvironment());
+  const serverType = parsed.serverType ?? (parsed.yes ? "bare" : await options.promptApi.askServerType());
+  const serverUrl = resolveServerUrlForEnvironment(environment);
+  const agentCount = parsed.agentCount ?? (parsed.yes ? 1 : await options.promptApi.askAgentCount());
+  const bootstrapNodes = parsed.bootstrapNodes ?? (parsed.yes ? false : await options.promptApi.askBootstrapNodes());
+  await ensureSafeTarget({ targetDir, force: parsed.force });
+  await renderTemplate({
+    targetDir,
+    projectName,
+    serverType,
+    force: parsed.force
+  });
+  const envExamplePath = join(targetDir, ".env.example");
+  const envPath = join(targetDir, ".env");
+  if (!existsSync(envPath) && existsSync(envExamplePath)) {
+    await writeFile(envPath, await readFile(envExamplePath, "utf8"), "utf8");
+  }
+  if (bootstrapNodes) {
+    const bootstrapped = await options.runtimeApi.bootstrapNodeIds({
+      agentCount,
+      serverUrl
+    });
+    const envContent = existsSync(envPath) ? await readFile(envPath, "utf8") : "";
+    const nextEnv = patchEnvContent({
+      envContent,
+      serverUrl,
+      mainNodeId: bootstrapped.mainNodeId,
+      agentNodeIds: bootstrapped.agentNodeIds
+    });
+    await writeFile(envPath, nextEnv, "utf8");
+    console.log(`Bootstrapped main node id: ${bootstrapped.mainNodeId}`);
+    for (const [index, nodeId] of bootstrapped.agentNodeIds.entries()) {
+      console.log(`Bootstrapped agent node ${String(index + 1)} id: ${nodeId}`);
+    }
+  } else if (existsSync(envPath)) {
+    const envContent = await readFile(envPath, "utf8");
+    const nextEnv = patchEnvContent({
+      envContent,
+      serverUrl,
+      mainNodeId: "",
+      agentNodeIds: []
+    });
+    await writeFile(envPath, nextEnv, "utf8");
+  }
+  console.log("");
+  console.log("Agent starter scaffold created.");
+  console.log(`Location: ${targetDir}`);
+  console.log("Next steps:");
+  console.log(`  cd "${targetDir}"`);
+  console.log("  npm install");
+  if (!bootstrapNodes) {
+    console.log("  npx agent-play create-main-node");
+    console.log("  npx agent-play create-agent-node");
+    if (agentCount === 2) {
+      console.log("  npx agent-play create-agent-node");
+    }
+    console.log("  copy node ids into .env");
+  }
+  console.log("  npm run dev");
+}
+function basenameFromPath(pathValue) {
+  const split = pathValue.split(/[\\/]/).filter((part) => part.length > 0);
+  return split[split.length - 1] ?? "agent-play-agent-starter";
+}
+
+// src/cli.ts
+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 join2(homedir(), ".agent-play", "credentials.json");
+}
+async function loadCredentials() {
+  return loadAgentPlayCredentialsFileFromPath(credentialsPath());
 }
 async function saveCredentials(c) {
-  const dir = join(homedir(), ".agent-play");
-  await mkdir(dir, { recursive: true });
-  await writeFile(
+  const dir = join2(homedir(), ".agent-play");
+  await mkdir2(dir, { recursive: true });
+  await writeFile2(
     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";
+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;
+  }
+  if (t === "2") {
+    return BOOTSTRAP_ENVIRONMENTS[1].url;
+  }
+  if (t === "3") {
+    return BOOTSTRAP_ENVIRONMENTS[2].url;
+  }
+  for (const e of BOOTSTRAP_ENVIRONMENTS) {
+    if (t === e.id) {
+      return e.url;
+    }
+  }
+  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 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;
+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(/\/$/, "");
+    }
+    console.log(
+      "Invalid choice. Enter 1, 2, or 3, or one of: local-server, test-server, main-server."
+    );
   }
-  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;
+}
+function parseInitializeBootstrapAnswer(raw) {
+  const trimmed = raw.trim().toLowerCase();
+  if (trimmed === "" || trimmed === "y" || trimmed === "yes") {
+    return true;
   }
-  let lookupJson;
-  try {
-    lookupJson = JSON.parse(lookupText);
-  } catch {
-    rl.close();
-    console.error("Invalid JSON from server.");
-    process.exitCode = 1;
-    return;
+  if (trimmed === "n" || trimmed === "no") {
+    return false;
   }
-  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;
+  return null;
+}
+async function promptInitializeBootstrapChoice(rl) {
+  for (; ; ) {
+    const answer = await rl.question("Create node identities now? [Y/n]: ");
+    const parsed = parseInitializeBootstrapAnswer(answer);
+    if (parsed !== null) {
+      return parsed;
     }
-    const loginJson = JSON.parse(loginText);
-    if (typeof loginJson.token !== "string") {
-      console.error("Missing token in response.");
-      process.exitCode = 1;
-      return;
+    console.log("Please answer yes or no.");
+  }
+}
+function parseInitializeAgentCount(raw) {
+  const trimmed = raw.trim();
+  if (trimmed === "" || trimmed === "1") {
+    return 1;
+  }
+  if (trimmed === "2") {
+    return 2;
+  }
+  return null;
+}
+async function promptInitializeAgentCount(rl) {
+  for (; ; ) {
+    const answer = await rl.question("How many agents do you want to deploy? (1-2) [1]: ");
+    const parsed = parseInitializeAgentCount(answer);
+    if (parsed !== null) {
+      return parsed;
     }
-    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 value. Enter 1 or 2.");
+  }
+}
+function parseInitializeEnvironmentAnswer(raw) {
+  const trimmed = raw.trim().toLowerCase();
+  if (trimmed === "" || trimmed === "1" || trimmed === "development" || trimmed === "dev") {
+    return "development";
+  }
+  if (trimmed === "2" || trimmed === "test") {
+    return "test";
+  }
+  if (trimmed === "3" || trimmed === "production" || trimmed === "prod") {
+    return "production";
+  }
+  return null;
+}
+async function promptInitializeEnvironment(rl) {
+  const lines = [
+    "Choose environment for initialization:",
+    "  1) development \u2192 http://127.0.0.1:3000",
+    "  2) test        \u2192 https://test-agent-play.com",
+    "  3) production  \u2192 https://agent-play.com",
+    "Enter 1-3, or development/test/production [1]: "
+  ].join("\n");
+  for (; ; ) {
+    const answer = await rl.question(lines);
+    const parsed = parseInitializeEnvironmentAnswer(answer);
+    if (parsed !== null) {
+      return parsed;
     }
-    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;
+    console.log("Invalid choice. Enter 1, 2, 3, development, test, or production.");
+  }
+}
+function parseInitializeServerTypeAnswer(raw) {
+  const trimmed = raw.trim().toLowerCase();
+  if (trimmed === "" || trimmed === "1" || trimmed === "bare") {
+    return "bare";
+  }
+  if (trimmed === "2" || trimmed === "express") {
+    return "express";
+  }
+  return null;
+}
+async function promptInitializeServerType(rl) {
+  const lines = [
+    "Choose server runtime:",
+    "  1) bare    \u2192 simple process entrypoint (minimal)",
+    "  2) express \u2192 deployable HTTP server with /health endpoint",
+    "Enter 1-2, or bare/express [1]: "
+  ].join("\n");
+  for (; ; ) {
+    const answer = await rl.question(lines);
+    const parsed = parseInitializeServerTypeAnswer(answer);
+    if (parsed !== null) {
+      return parsed;
     }
-    const regJson = JSON.parse(regText);
-    if (typeof regJson.token !== "string") {
-      console.error("Missing token in response.");
-      process.exitCode = 1;
-      return;
+    console.log("Invalid choice. Enter 1, 2, bare, or express.");
+  }
+}
+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];
+    }
+  }
+  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;
+    }
+    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 resolve2(options.rootFilePath.trim());
+  }
+  const fromEnv = process.env.AGENT_PLAY_ROOT_FILE_PATH;
+  if (typeof fromEnv === "string" && fromEnv.trim().length > 0) {
+    return resolve2(fromEnv.trim());
+  }
+  const homeRoot = join2(homedir(), ".agent-play", ".root");
+  if (existsSync2(homeRoot)) {
+    return homeRoot;
+  }
+  const cwdRoot = resolve2(process.cwd(), ".root");
+  if (existsSync2(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 = join2(homedir(), ".agent-play");
+  await mkdir2(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 +566,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 +578,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 +619,116 @@ 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
+  });
+  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 ensureMainCredentialsForInitialize(serverUrl) {
+  const existing = await loadCredentials();
+  if (existing !== null && existing.serverUrl.replace(/\/$/, "") === serverUrl.replace(/\/$/, "")) {
+    return existing;
+  }
+  const rootKey = loadRootKey(resolveAgentPlayRootPath({}));
+  const generatedPassw = generateNodePassw();
+  const hashedPassw = hashNodePassword(generatedPassw);
+  const credential = createNodeCredentialFromPassw({ passw: hashedPassw, rootKey });
+  await registerNodeOnServer(serverUrl, hashedPassw, credential.nodeId);
+  const created = {
+    serverUrl,
+    nodeId: credential.nodeId,
+    passw: generatedPassw
+  };
+  await saveCredentials(created);
+  return created;
+}
+async function createAgentNodeForInitialize(cred) {
+  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: {
+      "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) {
-    console.error(`view-keys failed (${res.status}): ${text}`);
-    process.exitCode = 1;
-    return;
+    throw new Error(`Create failed (${String(res.status)}): ${text}`);
   }
   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).");
+  if (typeof json.agentId !== "string" || json.agentId !== agentNodeId) {
+    throw new Error("Invalid agent creation response.");
   }
+  const nextAgentNodes = [
+    ...(cred.agentNodes ?? []).filter((n) => n.nodeId !== agentNodeId),
+    {
+      nodeId: agentNodeId,
+      passw: agentPassw,
+      createdAt: (/* @__PURE__ */ new Date()).toISOString()
+    }
+  ];
+  await saveCredentials({
+    ...cred,
+    agentNodes: nextAgentNodes
+  });
+  return agentNodeId;
 }
-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 +738,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 +811,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 +861,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 +873,261 @@ 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 cmdInitialize2(argv) {
+  const rl = createInterface({ input, output });
+  try {
+    await cmdInitialize({
+      argv,
+      promptApi: {
+        askEnvironment: () => promptInitializeEnvironment(rl),
+        askServerType: () => promptInitializeServerType(rl),
+        askBootstrapNodes: () => promptInitializeBootstrapChoice(rl),
+        askAgentCount: () => promptInitializeAgentCount(rl)
+      },
+      runtimeApi: {
+        bootstrapNodeIds: async (options) => {
+          const mainCred = await ensureMainCredentialsForInitialize(options.serverUrl);
+          const agentNodeIds = [];
+          for (let i = 0; i < options.agentCount; i++) {
+            const refreshedCred = await loadCredentials() ?? mainCred;
+            const nodeId = await createAgentNodeForInitialize(refreshedCred);
+            agentNodeIds.push(nodeId);
+          }
+          return {
+            mainNodeId: mainCred.nodeId,
+            agentNodeIds
+          };
+        }
+      }
+    });
+  } finally {
+    rl.close();
+  }
+}
 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 === "list-agent-nodes" || cmd === "list") {
+    await cmdListAgentNodes();
     return;
   }
-  if (cmd === "logout") {
-    await cmdLogout();
+  if (cmd === "delete-agent-node" || cmd === "delete" || cmd === "remove") {
+    await cmdDeleteAgentNode(process.argv.slice(3));
     return;
   }
-  if (cmd === "create") {
-    await cmdCreate();
+  if (cmd === "delete-main-node") {
+    await cmdDeleteMainNode();
     return;
   }
-  if (cmd === "create-key" || cmd === "generate-key") {
-    await cmdCreateKey();
+  if (cmd === "validate-main-node") {
+    await cmdValidateMainNode();
     return;
   }
-  if (cmd === "view-keys") {
-    await cmdViewKeys();
+  if (cmd === "validate-agent-node") {
+    await cmdValidateAgentNode(process.argv.slice(3));
     return;
   }
-  if (cmd === "delete" || cmd === "remove") {
-    await cmdDelete();
+  if (cmd === "initialize" || cmd === "init") {
+    await cmdInitialize2(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 initialize | init [--dir <path>] [--name <project-name>] [--template langchain] [--environment <development|test|production>] [--server-type <bare|express>] [--yes] [--force] [--bootstrap-nodes] [--agent-count <1|2>]",
+      "  agent-play clear-node-credentials"
+    ].join("\n")
   );
   process.exitCode = 1;
 }