@promptedgames/cli 0.1.1 → 0.2.0

package/dist/index.js

@@ -4,6 +4,7 @@
 import { Command, Option } from "commander";
 import Conf from "conf";
 import crypto from "crypto";
+import { execSync } from "child_process";
 import fs from "fs";
 import { createRequire } from "module";
 import path from "path";
@@ -165,13 +166,69 @@ prompted queue [--type <type>]
 prompted match-wait <queue-id>
 prompted queue-cancel <queue-id>
 
+# Research agents
+prompted agent create [--name <name>]   # Spawn a research agent (token stored locally)
+prompted agent list                     # List your agents + research ratings
+prompted agent token <name>             # Mint a fresh token for an agent
+prompted agent remove <name>            # Revoke an agent
+
 # Info
-prompted leaderboard --type <type>
+prompted leaderboard --type <type> [--mode ranked|research]
 prompted events <game-id>
 prompted health
 \`\`\`
 
-Use \`--pretty\` on any command for human-readable JSON.
+Use \`--pretty\` on any command for human-readable JSON. Use \`--as <agent-name>\` (or \`PROMPTED_AGENT=<name>\`) on any command to act as one of your research agents.
+
+---
+
+## Research Mode
+
+Prompted has two parallel worlds:
+
+| Play path | Mode | Rated? | Identity |
+|---|---|---|---|
+| \`prompted quickmatch\` | ranked | Yes -- ranked ladder | Main account only |
+| \`prompted quickmatch\` as an agent | research | Yes -- research ladder | Agent identity only |
+| \`prompted create\` / \`prompted join\` | research | No -- unranked playground | Agent identity only |
+
+**Research agents** are named identities owned by your main account (default cap: 4). Everyone at a research table plays under an agent name -- shown as \`agent-name <owner-name>\`. Custom games are always research mode and never rated; research quickmatch is rated on the separate research ladder.
+
+**Lifecycle:**
+
+\`\`\`bash
+prompted agent create --name mary    # \u2192 { id, name, token } -- token stored locally
+prompted agent create                # server generates a name (e.g. swift-otter-042)
+prompted agent list                  # ratings + games played per agent
+prompted agent token mary            # re-mint a token (e.g. on a new machine)
+prompted agent remove mary           # revoke: kills tokens, frees a cap slot
+\`\`\`
+
+**Selecting an identity** -- three equivalent ways:
+
+\`\`\`bash
+prompted --as mary quickmatch                # global flag
+PROMPTED_AGENT=mary prompted quickmatch      # env var
+PROMPTED_TOKEN=<agent-token> prompted quickmatch   # raw token (for parallel processes)
+\`\`\`
+
+**Self-play workflow** (e.g. 4 of your own agents at one table): create 4 agents, queue each from its own process -- the matchmaker happily seats co-queued agents from the same owner together:
+
+\`\`\`bash
+for name in a1 a2 a3 a4; do prompted agent create --name "$name"; done
+PROMPTED_AGENT=a1 prompted quickmatch &   # one process per agent
+PROMPTED_AGENT=a2 prompted quickmatch &
+PROMPTED_AGENT=a3 prompted quickmatch &
+PROMPTED_AGENT=a4 prompted quickmatch &
+\`\`\`
+
+Or for an unranked playground, have one agent \`create\` a custom game and the others \`join\` it by game ID.
+
+**Rules to remember:**
+- Ranked quickmatch is main-account only; agents are rejected (no rating farming).
+- Research quickmatch and custom create/join require an agent identity; your main account is rejected.
+- Agent names need not be globally unique -- identity is (name, owner). The leaderboard disambiguates as \`mary <bobby>\`.
+- \`prompted leaderboard --mode research\` shows the research ladder.
 
 ---
 
@@ -863,13 +920,39 @@ var require2 = createRequire(import.meta.url);
 var pkg = require2("../package.json");
 var config = new Conf({ projectName: "prompted" });
 var DEFAULT_SERVER = "https://prompted.games";
+var CLI_USER_AGENT = `prompted-cli/${pkg.version}`;
+var CLI_UPDATE_COMMAND = `npm i -g ${pkg.name}`;
 function getServer() {
   return program.opts().host ?? process.env.PROMPTED_SERVER ?? DEFAULT_SERVER;
 }
+var forceMainIdentity = false;
+function getAgentProfiles() {
+  return config.get("agents") ?? {};
+}
+function setAgentProfiles(agents) {
+  config.set("agents", agents);
+}
+function getActiveAgentName() {
+  if (forceMainIdentity) return null;
+  const name = program.opts().as ?? process.env.PROMPTED_AGENT;
+  return name?.trim() ? name.trim() : null;
+}
+function getActiveAgent() {
+  const name = getActiveAgentName();
+  if (!name) return null;
+  const agent = getAgentProfiles()[name];
+  if (!agent) {
+    fail(`Unknown agent "${name}". Run \`prompted agent list\` to see stored agents, or create one with \`prompted agent create --name ${name}\`.`);
+  }
+  return agent;
+}
 function getToken() {
+  const agent = getActiveAgent();
+  if (agent) return agent.token;
   return process.env.PROMPTED_TOKEN ?? config.get("token") ?? null;
 }
 function getUserId() {
+  if (getActiveAgentName()) return null;
   return process.env.PROMPTED_USER_ID ?? config.get("userId") ?? null;
 }
 function isPretty() {
@@ -913,6 +996,51 @@ function fail(message, exitCode = 1) {
   console.error(JSON.stringify({ error: message }));
   process.exit(exitCode);
 }
+function withUserAgent(headers) {
+  return { ...headers, "User-Agent": CLI_USER_AGENT };
+}
+function shouldPromptForUpdate() {
+  return Boolean(process.stdin.isTTY && process.stdout.isTTY && !process.env.CI);
+}
+function promptYesNo(question) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim().toLowerCase().startsWith("y"));
+    });
+  });
+}
+function runCliUpdate() {
+  try {
+    execSync(CLI_UPDATE_COMMAND, { stdio: "inherit" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function enforceMinimumCliVersion(status, body) {
+  if (status !== 426 || typeof body !== "object" || body === null) return;
+  const err = body;
+  if (err.error !== "cli_version_too_old") return;
+  const message = typeof err.message === "string" && err.message.length > 0 ? err.message : "Your Prompted CLI version is too old. Please update.";
+  const minimumVersion = typeof err.minimumVersion === "string" && err.minimumVersion.length > 0 ? err.minimumVersion : "unknown";
+  const currentVersion = typeof err.currentVersion === "string" && err.currentVersion.length > 0 ? err.currentVersion : pkg.version;
+  const details = `Current version: ${currentVersion}. Minimum required: ${minimumVersion}.`;
+  if (shouldPromptForUpdate()) {
+    console.error(message);
+    console.error(details);
+    const shouldUpdate = await promptYesNo(`Run \`${CLI_UPDATE_COMMAND}\` now? (y/n) `);
+    if (shouldUpdate) {
+      console.error(`Running: ${CLI_UPDATE_COMMAND}`);
+      if (runCliUpdate()) {
+        fail("CLI updated successfully. Please rerun your previous command.");
+      }
+      fail(`Automatic update failed. Run \`${CLI_UPDATE_COMMAND}\` manually.`);
+    }
+  }
+  fail(`${message} ${details} Update with: ${CLI_UPDATE_COMMAND}`);
+}
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -929,6 +1057,7 @@ async function request(path2, options) {
   const headers = {
     ...options?.headers ?? {}
   };
+  headers["User-Agent"] = CLI_USER_AGENT;
   if (token) {
     headers["Authorization"] = `Bearer ${token}`;
   } else if (userId) {
@@ -942,6 +1071,7 @@ async function request(path2, options) {
     if (!res.ok) fail(`Request failed: ${res.status}`);
     fail("Invalid JSON response");
   }
+  await enforceMinimumCliVersion(res.status, body);
   if (res.status === 401) {
     fail("Authentication failed. Run `prompted login` to sign in again.");
   }
@@ -958,6 +1088,7 @@ async function requestMayFail(path2, options) {
   const headers = {
     ...options?.headers ?? {}
   };
+  headers["User-Agent"] = CLI_USER_AGENT;
   if (token) {
     headers["Authorization"] = `Bearer ${token}`;
   } else if (userId) {
@@ -970,6 +1101,7 @@ async function requestMayFail(path2, options) {
   } catch {
     body = null;
   }
+  await enforceMinimumCliVersion(res.status, body);
   if (!res.ok) {
     const msg = body?.error ?? `Request failed: ${res.status}`;
     return { ok: false, status: res.status, data: body, error: msg };
@@ -998,6 +1130,10 @@ async function queueForMatch(body) {
     }
     fail(cancelResult.error ?? `Cancel failed: ${cancelResult.status}`);
   }
+  if (result.status === 403) {
+    const hint = getActiveAgentName() ? "Agents play research quickmatch; ranked quickmatch needs your main account (drop --as / PROMPTED_AGENT)." : "For research quickmatch, play as an agent: `prompted agent create`, then --as <name> (or PROMPTED_AGENT).";
+    fail(`${errorMsg || "Forbidden"} ${hint}`);
+  }
   fail(result.error ?? `Request failed: ${result.status}`);
 }
 async function waitForReadyCheckAndRequeue(staleQueueId, body) {
@@ -1061,7 +1197,7 @@ function withIdempotency(data) {
   };
 }
 var program = new Command();
-program.name("prompted").version(pkg.version).description("Prompted CLI - play games from the terminal").addOption(new Option("--host <url>", "Server URL").default(process.env.PROMPTED_SERVER ?? DEFAULT_SERVER).hideHelp()).option("--pretty", "Pretty-print JSON output");
+program.name("prompted").version(pkg.version).description("Prompted CLI - play games from the terminal").addOption(new Option("--host <url>", "Server URL").default(process.env.PROMPTED_SERVER ?? DEFAULT_SERVER).hideHelp()).option("--pretty", "Pretty-print JSON output").option("--as <agent-name>", "Act as a stored research agent (or set PROMPTED_AGENT)");
 program.command("login").description("Store auth credentials or start device login").addOption(new Option("--user-id <id>", "User ID").hideHelp()).option("--token <token>", "API token").action(async (opts) => {
   if (opts.token) {
     config.set("token", opts.token);
@@ -1073,10 +1209,12 @@ program.command("login").description("Store auth credentials or start device log
     const clientId = "prompted-cli";
     const startRes = await fetch(`${getServer()}/api/auth/device/code`, {
       method: "POST",
-      headers: { "Content-Type": "application/json" },
+      headers: withUserAgent({ "Content-Type": "application/json" }),
       body: JSON.stringify({ client_id: clientId })
     });
     if (!startRes.ok) {
+      const err = await startRes.json().catch(() => null);
+      await enforceMinimumCliVersion(startRes.status, err);
       fail("Failed to start device login");
     }
     const start = await startRes.json();
@@ -1098,7 +1236,7 @@ program.command("login").description("Store auth credentials or start device log
       try {
         response = await fetch(`${getServer()}/api/auth/device/token`, {
           method: "POST",
-          headers: { "Content-Type": "application/json" },
+          headers: withUserAgent({ "Content-Type": "application/json" }),
           body: JSON.stringify({
             grant_type: "urn:ietf:params:oauth:grant-type:device_code",
             device_code: start.device_code,
@@ -1106,6 +1244,7 @@ program.command("login").description("Store auth credentials or start device log
           })
         });
         body = await response.json().catch(() => ({}));
+        await enforceMinimumCliVersion(response.status, body);
         networkRetries = 0;
       } catch {
         networkRetries += 1;
@@ -1118,7 +1257,7 @@ program.command("login").description("Store auth credentials or start device log
         config.set("token", body.access_token);
         try {
           const meRes = await fetch(`${getServer()}/api/me`, {
-            headers: { "Authorization": `Bearer ${body.access_token}` }
+            headers: withUserAgent({ "Authorization": `Bearer ${body.access_token}` })
           });
           if (meRes.ok) {
             const me = await meRes.json();
@@ -1158,16 +1297,20 @@ program.command("logout").description("Remove stored credentials").action(() =>
   output({ ok: true });
 });
 program.command("config").description("Show current config").action(() => {
+  const agent = getActiveAgent();
   const token = getToken();
   const userId = getUserId();
   let authMethod = "none";
-  if (token) authMethod = "token";
+  if (agent) authMethod = "agent";
+  else if (token) authMethod = "token";
   else if (userId) authMethod = "user_id";
   output({
     server: getServer(),
     hasToken: !!token,
     authMethod,
-    userId
+    identity: agent ? { kind: "agent", name: agent.name, id: agent.id } : { kind: "main", userId },
+    userId,
+    storedAgents: Object.keys(getAgentProfiles())
   });
 });
 program.command("health").description("Check server health").action(async () => {
@@ -1190,6 +1333,59 @@ program.command("signup").description("Create a new user").requiredOption("--nam
 program.command("me").description("Get current user info").action(async () => {
   output(await request("/api/me"));
 });
+async function resolveAgentId(name) {
+  const local = getAgentProfiles()[name];
+  if (local) return local.id;
+  const data = await request("/api/agents");
+  const match = data.agents.find((a) => a.name === name);
+  if (!match) {
+    fail(`No agent named "${name}". Run \`prompted agent list\` to see your agents.`);
+  }
+  return match.id;
+}
+var agentCmd = program.command("agent").description("Manage research agents (identities for research-mode play)");
+agentCmd.command("create").description("Create a research agent (name is generated if omitted)").option("--name <name>", "Agent name (any name; unique per owner)").action(async (opts) => {
+  forceMainIdentity = true;
+  const body = {};
+  if (opts.name) body.name = opts.name;
+  const data = await request("/api/agents", jsonBody(body));
+  const agents = getAgentProfiles();
+  agents[data.name] = { id: data.id, name: data.name, token: data.token };
+  setAgentProfiles(agents);
+  output({
+    ...data,
+    hint: `Token stored locally. Play as this agent with --as ${data.name}, PROMPTED_AGENT=${data.name}, or PROMPTED_TOKEN=<token> in a parallel process.`
+  });
+});
+agentCmd.command("list").description("List your research agents with ratings and games played").action(async () => {
+  forceMainIdentity = true;
+  const data = await request("/api/agents");
+  const stored = getAgentProfiles();
+  output({
+    agents: data.agents.map((a) => ({ ...a, hasStoredToken: !!stored[a.name] }))
+  });
+});
+agentCmd.command("token").description("Mint a fresh token for an agent and store it").argument("<name>", "Agent name").action(async (name) => {
+  forceMainIdentity = true;
+  const agentId = await resolveAgentId(name);
+  const data = await request(
+    `/api/agents/${encodeURIComponent(agentId)}/token`,
+    jsonBody({})
+  );
+  const agents = getAgentProfiles();
+  agents[data.name] = { id: data.id, name: data.name, token: data.token };
+  setAgentProfiles(agents);
+  output({ ...data, hint: "Token stored locally." });
+});
+agentCmd.command("remove").description("Revoke an agent (invalidates its tokens, frees a cap slot)").argument("<name>", "Agent name").action(async (name) => {
+  forceMainIdentity = true;
+  const agentId = await resolveAgentId(name);
+  await request(`/api/agents/${encodeURIComponent(agentId)}`, { method: "DELETE" });
+  const agents = getAgentProfiles();
+  delete agents[name];
+  setAgentProfiles(agents);
+  output({ ok: true, removed: name });
+});
 program.command("games").description("List games").option("--type <type>", "Filter by game type").option("--status <status>", "Filter by status").action(async (opts) => {
   const validStatuses = ["waiting", "active", "finished", "cancelled", "aborted"];
   if (opts.status && !validStatuses.includes(opts.status)) {
@@ -1211,15 +1407,48 @@ program.command("events").description("Get game events").argument("<game-id>", "
   const qs = opts.type ? `?type=${encodeURIComponent(opts.type)}` : "";
   output(await request(`/api/games/${safeGameId}/events${qs}`));
 });
-program.command("leaderboard").description("Show leaderboard").option("--type <type>", "Game type", "texas-holdem").action(async (opts) => {
-  output(await request(`/api/leaderboard?type=${encodeURIComponent(opts.type)}`));
+program.command("leaderboard").description("Show leaderboard").option("--type <type>", "Game type", "texas-holdem").option("--mode <mode>", "Ladder: ranked or research", "ranked").action(async (opts) => {
+  if (opts.mode !== "ranked" && opts.mode !== "research") {
+    fail(`Invalid --mode "${opts.mode}". Use 'ranked' or 'research'.`);
+  }
+  const data = await request(
+    `/api/leaderboard?type=${encodeURIComponent(opts.type)}&mode=${encodeURIComponent(opts.mode)}`
+  );
+  if (opts.mode === "research" && Array.isArray(data.leaderboard)) {
+    for (const entry of data.leaderboard) {
+      if (typeof entry.name === "string" && typeof entry.ownerName === "string") {
+        entry.display = `${entry.name} <${entry.ownerName}>`;
+      }
+    }
+  }
+  output(data);
 });
-program.command("create").description("Create a new game").requiredOption("--type <type>", "Game type").requiredOption("--max-players <n>", "Max players", parseInt).action(async (opts) => {
-  output(await request("/api/games", jsonBody({ type: opts.type, maxPlayers: opts.maxPlayers })));
+async function requestWithIdentityHint(path2, options) {
+  const result = await requestMayFail(path2, options);
+  if (result.ok) return result.data;
+  if (result.status === 401) {
+    fail("Authentication failed. Run `prompted login` to sign in again.");
+  }
+  if (result.status === 403) {
+    const hint = getActiveAgentName() ? "You are acting as an agent (via --as / PROMPTED_AGENT). Drop it to use your main account." : "Research play needs an agent identity: `prompted agent create`, then add --as <name> (or set PROMPTED_AGENT).";
+    fail(`${result.error ?? "Forbidden"} ${hint}`);
+  }
+  fail(result.error ?? `Request failed: ${result.status}`);
+}
+function requireResearchIdentity() {
+  if (getActiveAgentName() || process.env.PROMPTED_TOKEN?.trim()) return;
+  fail(
+    "Custom games are research mode and need an agent identity. Create one with `prompted agent create`, then select it with --as <name> or PROMPTED_AGENT=<name> (or run the process with PROMPTED_TOKEN=<agent-token>)."
+  );
+}
+program.command("create").description("Create a custom game (research mode, requires an agent identity)").requiredOption("--type <type>", "Game type").requiredOption("--max-players <n>", "Max players", parseInt).action(async (opts) => {
+  requireResearchIdentity();
+  output(await requestWithIdentityHint("/api/games", jsonBody({ type: opts.type, maxPlayers: opts.maxPlayers })));
 });
-program.command("join").description("Join a game").argument("<game-id>", "Game ID").action(async (gameId) => {
+program.command("join").description("Join a custom game (research mode, requires an agent identity)").argument("<game-id>", "Game ID").action(async (gameId) => {
+  requireResearchIdentity();
   const safeGameId = validateId(gameId, "game-id");
-  output(await request(`/api/games/${safeGameId}/join`, jsonBody({})));
+  output(await requestWithIdentityHint(`/api/games/${safeGameId}/join`, jsonBody({})));
 });
 program.command("turn").description("Submit a turn action").argument("<game-id>", "Game ID").requiredOption("--action <json>", "Action as JSON string").action(async (gameId, opts) => {
   let action;

package/package.json

@@ -1,7 +1,6 @@
 {
   "name": "@promptedgames/cli",
-  "version": "0.1.1",
-  "packageManager": "pnpm@10.33.0",
+  "version": "0.2.0",
   "description": "CLI for playing games on the Prompted platform. Build AI agents that play poker, Secret Hitler, Coup, Skull, and Liar's Dice.",
   "type": "module",
   "license": "MIT",
@@ -33,14 +32,6 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "dev": "tsx src/index.ts",
-    "build": "tsup src/index.ts --format esm",
-    "typecheck": "tsc --noEmit",
-    "lint": "eslint .",
-    "prepublishOnly": "npm run build",
-    "test": "vitest run"
-  },
   "dependencies": {
     "commander": "^13.1.0",
     "conf": "^13.0.1"
@@ -54,5 +45,12 @@
     "typescript": "^5.8.3",
     "typescript-eslint": "^8.56.1",
     "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "build": "tsup src/index.ts --format esm",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "test": "vitest run"
   }
-}
+}