@agent-play/cli 3.1.0 → 3.2.0

package/README.md

@@ -52,6 +52,7 @@ For Redis-direct checks (ops/CI), use **`node-tools`** script **`scripts/validat
 | **`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. |
+| **`initialize`** | `init` | Interactive scaffold for a starter agent codebase, optional node bootstrap, asks for agent count (1-2), and writes env-variable node ids into `.env` when bootstrapped. |
 | **`clear-node-credentials`** | — | Removes **`~/.agent-play/credentials.json`**. |
 
 ## Genesis and main node
@@ -68,6 +69,7 @@ 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 initialize
 npx agent-play list-agent-nodes
 npx agent-play delete-agent-node
 npx agent-play delete-agent-node <agent-uuid>
@@ -76,3 +78,14 @@ npx agent-play clear-node-credentials
 ```
 
 For SDK usage after bootstrap, use **`RemotePlayWorld`** and register players with **`mainNodeId`** and **`agentId`** from the CLI output.
+
+## Initialize quick start
+
+- `npx agent-play initialize` (or `npx agent-play init`) scaffolds starter files.
+- The flow asks whether to create nodes now and how many agent nodes to provision (max `2`).
+- If bootstrap is selected, it writes:
+  - `AGENT_PLAY_MAIN_NODE_ID`
+  - `AGENT_PLAY_AGENT_NODE_ID_1`
+  - `AGENT_PLAY_AGENT_NODE_ID_2` (when requested)
+  into generated `.env`.
+- Generated code references these env vars directly (no hardcoded ids).

package/dist/README.md

@@ -0,0 +1,91 @@
+# @agent-play/cli
+
+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)** — full **Node setup** and **Node validation** sections  
+- **[API reference](https://wilforlan.github.io/agent-play/)** — TypeDoc  
+
+## Install
+
+```bash
+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. |
+| **`initialize`** | `init` | Interactive scaffold for a starter agent codebase, optional node bootstrap, asks for agent count (1-2), and writes env-variable node ids into `.env` when bootstrapped. |
+| **`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 initialize
+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.
+
+## Initialize quick start
+
+- `npx agent-play initialize` (or `npx agent-play init`) scaffolds starter files.
+- The flow asks whether to create nodes now and how many agent nodes to provision (max `2`).
+- If bootstrap is selected, it writes:
+  - `AGENT_PLAY_MAIN_NODE_ID`
+  - `AGENT_PLAY_AGENT_NODE_ID_1`
+  - `AGENT_PLAY_AGENT_NODE_ID_2` (when requested)
+  into generated `.env`.
+- Generated code references these env vars directly (no hardcoded ids).

package/dist/cli.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { existsSync } from "fs";
-import { mkdir, 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, resolve } 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";
 import {
@@ -15,6 +15,247 @@ import {
   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";
+}
+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 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,
@@ -36,15 +277,15 @@ function parseAgentRows(agentsRaw) {
   return agents;
 }
 function credentialsPath() {
-  return join(homedir(), ".agent-play", "credentials.json");
+  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(c, null, 2),
     "utf8"
@@ -101,6 +342,102 @@ async function promptBootstrapEnvironment(rl) {
     );
   }
 }
+function parseInitializeBootstrapAnswer(raw) {
+  const trimmed = raw.trim().toLowerCase();
+  if (trimmed === "" || trimmed === "y" || trimmed === "yes") {
+    return true;
+  }
+  if (trimmed === "n" || trimmed === "no") {
+    return false;
+  }
+  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;
+    }
+    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;
+    }
+    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;
+    }
+    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;
+    }
+    console.log("Invalid choice. Enter 1, 2, bare, or express.");
+  }
+}
 function parseBootstrapNodeArgs(argv) {
   const out = {};
   for (let i = 0; i < argv.length; i++) {
@@ -137,18 +474,18 @@ function parseValidateAgentNodeArgs(argv) {
 }
 function resolveAgentPlayRootPath(options) {
   if (typeof options.rootFilePath === "string" && options.rootFilePath.trim().length > 0) {
-    return resolve(options.rootFilePath.trim());
+    return resolve2(options.rootFilePath.trim());
   }
   const fromEnv = process.env.AGENT_PLAY_ROOT_FILE_PATH;
   if (typeof fromEnv === "string" && fromEnv.trim().length > 0) {
-    return resolve(fromEnv.trim());
+    return resolve2(fromEnv.trim());
   }
-  const homeRoot = join(homedir(), ".agent-play", ".root");
-  if (existsSync(homeRoot)) {
+  const homeRoot = join2(homedir(), ".agent-play", ".root");
+  if (existsSync2(homeRoot)) {
     return homeRoot;
   }
-  const cwdRoot = resolve(process.cwd(), ".root");
-  if (existsSync(cwdRoot)) {
+  const cwdRoot = resolve2(process.cwd(), ".root");
+  if (existsSync2(cwdRoot)) {
     return cwdRoot;
   }
   throw new Error(
@@ -198,8 +535,8 @@ async function cmdBootstrapNode(argv) {
   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 dir = join2(homedir(), ".agent-play");
+  await mkdir2(dir, { recursive: true });
   const generatedPassw = generateNodePassw();
   const hashedPassw = hashNodePassword(generatedPassw);
   const credential = createNodeCredentialFromPassw({ passw: hashedPassw, rootKey });
@@ -320,6 +657,67 @@ async function cmdCreateAgentNode() {
   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) {
+    throw new Error(`Create failed (${String(res.status)}): ${text}`);
+  }
+  const json = JSON.parse(text);
+  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 cmdInspectNode() {
   const cred = await loadCredentials();
   if (cred === null) {
@@ -642,6 +1040,37 @@ async function cmdValidateAgentNode(argv) {
   }
   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 === "bootstrap-node" || cmd === "create-main-node") {
@@ -680,6 +1109,10 @@ async function main() {
     await cmdValidateAgentNode(process.argv.slice(3));
     return;
   }
+  if (cmd === "initialize" || cmd === "init") {
+    await cmdInitialize2(process.argv.slice(3));
+    return;
+  }
   console.error(
     [
       "Usage:",
@@ -692,6 +1125,7 @@ async function main() {
       "  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")
   );

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agent-play/cli",
-  "version": "3.1.0",
-  "description": "Command-line tool for Agent Play: login, API keys, and agent registration against the web UI.",
+  "version": "3.2.0",
+  "description": "Command-line tool for Agent Play: node configurations, agent starter kit, and agent registration against the web UI.",
   "private": false,
   "type": "module",
   "bin": {
@@ -9,6 +9,7 @@
   },
   "files": [
     "dist",
+    "templates",
     "README.md"
   ],
   "repository": {
@@ -20,7 +21,9 @@
     "access": "public"
   },
   "scripts": {
-    "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"
+    "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 && cp README.md dist/README.md",
+    "test": "vitest run",
+    "smoke:initialize": "node ./scripts/smoke-initialize.mjs"
   },
   "dependencies": {
     "@agent-play/node-tools": "1.0.0"
@@ -28,6 +31,7 @@
   "devDependencies": {
     "@types/node": "^22.10.0",
     "tsup": "^8.5.1",
-    "typescript": "~5.9.3"
+    "typescript": "~5.9.3",
+    "vitest": "^4.1.1"
   }
 }

package/templates/agent-starter/langchain/.env.example

@@ -0,0 +1,6 @@
+AGENT_PLAY_WEB_UI_URL=https://agent-play.com
+AGENT_PLAY_MAIN_NODE_ID=
+AGENT_PLAY_AGENT_NODE_ID_1=
+AGENT_PLAY_AGENT_NODE_ID_2=
+OPENAI_API_KEY=
+P2A_WEBRTC_ENABLED=1

package/templates/agent-starter/langchain/README.md

@@ -0,0 +1,24 @@
+# __PROJECT_NAME__
+
+Starter scaffold generated by `agent-play initialize`.
+
+## Quick start
+
+1. Install dependencies:
+   - `npm install`
+2. Prepare local env:
+   - `cp .env.example .env`
+3. If you skipped bootstrap during initialize:
+   - `npx agent-play create-main-node`
+   - `npx agent-play create-agent-node` (once or twice)
+   - copy values from `~/.agent-play/credentials.json` into `.env`
+4. Run:
+   - `npm run dev`
+
+## Node identity env contract
+
+- `AGENT_PLAY_MAIN_NODE_ID`: main developer node id.
+- `AGENT_PLAY_AGENT_NODE_ID_1`: first agent node id.
+- `AGENT_PLAY_AGENT_NODE_ID_2`: optional second agent node id.
+
+The generated runtime uses env variables for node ids; no hardcoded identities are embedded.

package/templates/agent-starter/langchain/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "__PROJECT_NAME__",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@agent-play/sdk": "^3.2.1",
+    "@langchain/openai": "^1.3.0",
+    "dotenv": "^17.3.1",
+    "express": "^4.21.2",
+    "langchain": "^1.2.36",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/node": "^22.10.0",
+    "tsx": "^4.21.0",
+    "typescript": "~5.9.3"
+  }
+}

package/templates/agent-starter/langchain/src/bare-server.ts

@@ -0,0 +1,12 @@
+import { loadEnv } from "./load-env.js";
+import { registerAgents } from "./register-agents.js";
+
+export async function startServer(): Promise<void> {
+  loadEnv();
+  const { world, registeredAgentIds } = await registerAgents();
+  console.log(`Registered ${String(registeredAgentIds.length)} agent(s):`);
+  for (const id of registeredAgentIds) {
+    console.log(`  - ${id}`);
+  }
+  await world.hold().for(30 * 60);
+}

package/templates/agent-starter/langchain/src/builtins/definitions.ts

@@ -0,0 +1,66 @@
+import { ChatOpenAI } from "@langchain/openai";
+import { createAgent } from "langchain";
+import { calculatorTools, policeReportTools } from "./toolkits/starter-tools.js";
+
+function randomAgentName(prefix: string): string {
+  return `${prefix}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+function randomSystemPrompt(prefix: string, rolePrompt: string): string {
+  const nonce = Math.random().toString(36).slice(2, 10);
+  return `${rolePrompt} Session nonce: ${nonce}. Agent label: ${prefix}.`;
+}
+
+function requiredEnv(name: string): string {
+  const value = process.env[name]?.trim();
+  if (value === undefined || value.length === 0) {
+    throw new Error(`Missing required env var: ${name}`);
+  }
+  return value;
+}
+
+export type StarterAgentDefinition = {
+  nodeId: string;
+  name: string;
+  type: "langchain";
+  agent: ReturnType<typeof createAgent>;
+};
+
+export function getStarterAgentDefinitions(agentCount: 1 | 2): StarterAgentDefinition[] {
+  const model = new ChatOpenAI({
+    apiKey: requiredEnv("OPENAI_API_KEY"),
+    model: process.env.OPENAI_MODEL?.trim() || "gpt-4.1",
+  });
+  const first = {
+    nodeId: requiredEnv("AGENT_PLAY_AGENT_NODE_ID_1"),
+    name: randomAgentName("CalculatorAgent"),
+    type: "langchain" as const,
+    agent: createAgent({
+      name: randomAgentName("lc-calculator-agent"),
+      model,
+      tools: [...calculatorTools],
+      systemPrompt: randomSystemPrompt(
+        "Calculator Agent",
+        "You are a rigorous calculator agent for production operations. Always validate the equation format, show the extracted coefficient and brief reasoning, and ask clarifying questions when equation syntax is ambiguous. Use chat_tool for conversational explanations and assist_calculate_coefficient for structured extraction."
+      ),
+    }),
+  };
+  if (agentCount === 1) {
+    return [first];
+  }
+  const second = {
+    nodeId: requiredEnv("AGENT_PLAY_AGENT_NODE_ID_2"),
+    name: randomAgentName("PoliceReportAgent"),
+    type: "langchain" as const,
+    agent: createAgent({
+      name: randomAgentName("lc-police-report-agent"),
+      model,
+      tools: [...policeReportTools],
+      systemPrompt: randomSystemPrompt(
+        "Police Report Agent",
+        "You are a police report intake agent. Collect factual, time-stamped incident details, separate witness statements from assumptions, and maintain neutral language suitable for official records. Use chat_tool for guided conversation and assist_collect_scene_details to gather structured scene data."
+      ),
+    }),
+  };
+  return [first, second];
+}

package/templates/agent-starter/langchain/src/builtins/toolkits/starter-tools.ts

@@ -0,0 +1,84 @@
+import { tool } from "langchain";
+import { z } from "zod";
+
+const calculatorChatTool = tool(
+  ({ message }: { message: string }) => `calculator:${message}`,
+  {
+    name: "chat_tool",
+    description: "Production-style calculator assistant chat tool.",
+    schema: z.object({
+      message: z.string(),
+    }),
+  }
+);
+
+const assistCalculateCoefficient = tool(
+  ({
+    equation,
+    variable,
+  }: {
+    equation: string;
+    variable: string;
+  }) => `coefficient:${equation}:${variable}`,
+  {
+    name: "assist_calculate_coefficient",
+    description:
+      "Extract the coefficient of a variable from a linear or polynomial equation string.",
+    schema: z.object({
+      equation: z.string(),
+      variable: z.string(),
+    }),
+  }
+);
+
+const policeChatTool = tool(
+  ({ message }: { message: string }) => `police:${message}`,
+  {
+    name: "chat_tool",
+    description: "Production-style police incident reporting chat tool.",
+    schema: z.object({
+      message: z.string(),
+    }),
+  }
+);
+
+const assistCollectSceneDetails = tool(
+  ({
+    location,
+    incidentType,
+    witnesses,
+    injuriesReported,
+    suspectDescription,
+    immediateRisk,
+  }: {
+    location: string;
+    incidentType: string;
+    witnesses?: string;
+    injuriesReported?: boolean;
+    suspectDescription?: string;
+    immediateRisk?: "low" | "medium" | "high";
+  }) =>
+    `scene:${location}:${incidentType}:${witnesses ?? ""}:${String(injuriesReported ?? false)}:${
+      suspectDescription ?? ""
+    }:${immediateRisk ?? "low"}`,
+  {
+    name: "assist_collect_scene_details",
+    description:
+      "Collect structured details from an incident scene report for police documentation.",
+    schema: z.object({
+      location: z.string(),
+      incidentType: z.string(),
+      witnesses: z.string().optional(),
+      injuriesReported: z.boolean().optional(),
+      suspectDescription: z.string().optional(),
+      immediateRisk: z.enum(["low", "medium", "high"]).optional(),
+    }),
+  }
+);
+
+export const calculatorTools = [
+  calculatorChatTool,
+  assistCalculateCoefficient,
+] as const;
+
+export const policeReportTools = [policeChatTool, assistCollectSceneDetails] as const;

package/templates/agent-starter/langchain/src/express-server.ts

@@ -0,0 +1,27 @@
+import express from "express";
+import { loadEnv } from "./load-env.js";
+import { registerAgents } from "./register-agents.js";
+
+export async function startServer(): Promise<void> {
+  loadEnv();
+  const port = Number(process.env.PORT ?? "3100");
+  const host = process.env.HOST ?? "0.0.0.0";
+
+  const app = express();
+  app.use(express.json());
+  app.get("/health", (_req, res) => {
+    res.json({ ok: true });
+  });
+
+  const { world, registeredAgentIds } = await registerAgents();
+  console.log(`Registered ${String(registeredAgentIds.length)} agent(s):`);
+  for (const id of registeredAgentIds) {
+    console.log(`  - ${id}`);
+  }
+
+  app.listen(port, host, () => {
+    console.log(`[starter-express] listening on http://${host}:${String(port)}`);
+  });
+
+  await world.hold().for(30 * 60);
+}

package/templates/agent-starter/langchain/src/index.ts

@@ -0,0 +1,6 @@
+import { startServer } from "__SERVER_MODULE__";
+
+void startServer().catch((error: unknown) => {
+  console.error(error);
+  process.exitCode = 1;
+});

package/templates/agent-starter/langchain/src/load-env.ts

@@ -0,0 +1,5 @@
+import { config } from "dotenv";
+
+export function loadEnv(): void {
+  config();
+}

package/templates/agent-starter/langchain/src/register/register-builtins.ts

@@ -0,0 +1,62 @@
+import {
+  langchainRegistration,
+  RemotePlayWorld,
+  type RegisteredPlayer,
+} from "@agent-play/sdk";
+import { getStarterAgentDefinitions } from "../builtins/definitions.js";
+import { executeToolCapability } from "../tool-handlers/execute-tool-capability.js";
+
+type RegisterResult = {
+  world: RemotePlayWorld;
+  registeredAgentIds: string[];
+};
+
+function requiredEnv(name: string): string {
+  const value = process.env[name]?.trim();
+  if (value === undefined || value.length === 0) {
+    throw new Error(`Missing required env var: ${name}`);
+  }
+  return value;
+}
+
+export async function registerBuiltinAgents(): Promise<RegisterResult> {
+  const mainNodeId = requiredEnv("AGENT_PLAY_MAIN_NODE_ID");
+  const world = new RemotePlayWorld({ logging: "on" });
+  const openAiApiKey = process.env.OPENAI_API_KEY?.trim();
+  if (openAiApiKey !== undefined && openAiApiKey.length > 0) {
+    world.initAudio({
+      openai: {
+        apiKey: openAiApiKey,
+      },
+    });
+  }
+  await world.connect({ mainNodeId });
+
+  const hasSecondAgent =
+    (process.env.AGENT_PLAY_AGENT_NODE_ID_2?.trim() ?? "").length > 0;
+  const definitions = getStarterAgentDefinitions(hasSecondAgent ? 2 : 1);
+  const registeredAgentIds: string[] = [];
+  const chatAgentsByPlayerId = new Map<string, unknown>();
+  const registeredPlayers: RegisteredPlayer[] = [];
+  for (const def of definitions) {
+    const registered = await world.addAgent({
+      name: def.name,
+      type: def.type,
+      agent: langchainRegistration(def.agent),
+      nodeId: def.nodeId,
+      enableP2a: "on",
+    });
+    registeredAgentIds.push(registered.id);
+    registeredPlayers.push(registered);
+  }
+  for (let i = 0; i < registeredPlayers.length; i++) {
+    chatAgentsByPlayerId.set(registeredPlayers[i].id, definitions[i].agent);
+  }
+  world.subscribeIntercomCommands({
+    playerIds: registeredPlayers.map((player) => player.id),
+    executeTool: executeToolCapability,
+    chatAgentsByPlayerId: chatAgentsByPlayerId as Map<string, never>,
+  });
+
+  return { world, registeredAgentIds };
+}

package/templates/agent-starter/langchain/src/register-agents.ts

@@ -0,0 +1 @@
+export { registerBuiltinAgents as registerAgents } from "./register/register-builtins.js";

package/templates/agent-starter/langchain/src/tool-handlers/assist-brainstorm.ts

@@ -0,0 +1,8 @@
+export function executeAssistBrainstorm(args: {
+  prompt?: string;
+}): Record<string, unknown> {
+  const prompt = typeof args.prompt === "string" ? args.prompt : "";
+  return {
+    summary: `Brainstorm starter for: ${prompt}`,
+  };
+}

package/templates/agent-starter/langchain/src/tool-handlers/assist-calculate-coefficient.ts

@@ -0,0 +1,35 @@
+function normalizeEquation(equation: string): string {
+  return equation.replace(/\s+/g, "");
+}
+
+export function executeAssistCalculateCoefficient(args: {
+  equation?: string;
+  variable?: string;
+}): Record<string, unknown> {
+  const equation = typeof args.equation === "string" ? args.equation : "";
+  const variable = typeof args.variable === "string" ? args.variable : "";
+  if (equation.length === 0 || variable.length === 0) {
+    return {
+      ok: false,
+      error: "equation and variable are required.",
+    };
+  }
+  const normalized = normalizeEquation(equation);
+  const regex = new RegExp(`([+-]?\\d*\\.?\\d*)${variable}`);
+  const match = normalized.match(regex);
+  if (match === null) {
+    return {
+      ok: false,
+      error: `No coefficient found for variable ${variable}.`,
+    };
+  }
+  const raw = match[1];
+  const coefficient =
+    raw === "" || raw === "+" ? 1 : raw === "-" ? -1 : Number(raw);
+  return {
+    ok: Number.isFinite(coefficient),
+    variable,
+    coefficient,
+    equation,
+  };
+}

package/templates/agent-starter/langchain/src/tool-handlers/assist-collect-scene-details.ts

@@ -0,0 +1,32 @@
+export function executeAssistCollectSceneDetails(args: {
+  location?: string;
+  incidentType?: string;
+  witnesses?: string;
+  injuriesReported?: boolean;
+  suspectDescription?: string;
+  immediateRisk?: "low" | "medium" | "high";
+}): Record<string, unknown> {
+  const location = typeof args.location === "string" ? args.location : "";
+  const incidentType =
+    typeof args.incidentType === "string" ? args.incidentType : "";
+  if (location.length === 0 || incidentType.length === 0) {
+    return {
+      ok: false,
+      error: "location and incidentType are required.",
+    };
+  }
+  return {
+    ok: true,
+    scene: {
+      location,
+      incidentType,
+      witnesses: typeof args.witnesses === "string" ? args.witnesses : "",
+      injuriesReported: args.injuriesReported === true,
+      suspectDescription:
+        typeof args.suspectDescription === "string"
+          ? args.suspectDescription
+          : "",
+      immediateRisk: args.immediateRisk ?? "low",
+    },
+  };
+}

package/templates/agent-starter/langchain/src/tool-handlers/chat-tool.ts

@@ -0,0 +1,6 @@
+export function executeChatTool(args: { message?: string }): Record<string, unknown> {
+  const message = typeof args.message === "string" ? args.message : "";
+  return {
+    reply: `Echo from __PROJECT_NAME__: ${message}`,
+  };
+}

package/templates/agent-starter/langchain/src/tool-handlers/execute-tool-capability.ts

@@ -0,0 +1,12 @@
+import { resolveToolCapabilityHandler } from "./tool-capability-registry.js";
+
+export async function executeToolCapability(options: {
+  toolName: string;
+  args: Record<string, unknown>;
+}): Promise<Record<string, unknown>> {
+  const handler = resolveToolCapabilityHandler(options.toolName);
+  if (handler === null) {
+    throw new Error(`unknown tool capability: ${options.toolName}`);
+  }
+  return await Promise.resolve(handler(options.args));
+}

package/templates/agent-starter/langchain/src/tool-handlers/tool-capability-registry.ts

@@ -0,0 +1,49 @@
+import { executeAssistCalculateCoefficient } from "./assist-calculate-coefficient.js";
+import { executeAssistCollectSceneDetails } from "./assist-collect-scene-details.js";
+import { executeChatTool } from "./chat-tool.js";
+
+export type ToolCapabilityHandler = (
+  args: Record<string, unknown>
+) => Record<string, unknown> | Promise<Record<string, unknown>>;
+
+const registry = new Map<string, ToolCapabilityHandler>([
+  ["chat_tool", (args) => executeChatTool({ message: String(args.message ?? "") })],
+  [
+    "assist_calculate_coefficient",
+    (args) =>
+      executeAssistCalculateCoefficient({
+        equation: String(args.equation ?? ""),
+        variable: String(args.variable ?? ""),
+      }),
+  ],
+  [
+    "assist_collect_scene_details",
+    (args) =>
+      executeAssistCollectSceneDetails({
+        location: String(args.location ?? ""),
+        incidentType: String(args.incidentType ?? ""),
+        witnesses:
+          typeof args.witnesses === "string" ? args.witnesses : undefined,
+        injuriesReported:
+          typeof args.injuriesReported === "boolean"
+            ? args.injuriesReported
+            : undefined,
+        suspectDescription:
+          typeof args.suspectDescription === "string"
+            ? args.suspectDescription
+            : undefined,
+        immediateRisk:
+          args.immediateRisk === "low" ||
+          args.immediateRisk === "medium" ||
+          args.immediateRisk === "high"
+            ? args.immediateRisk
+            : undefined,
+      }),
+  ],
+]);
+
+export function resolveToolCapabilityHandler(
+  toolName: string
+): ToolCapabilityHandler | null {
+  return registry.get(toolName) ?? null;
+}

package/templates/agent-starter/langchain/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "noEmit": false,
+    "outDir": "dist"
+  },
+  "include": ["src/**/*.ts"]
+}