@promptedgames/cli 0.1.2 → 0.2.0

package/dist/index.js

@@ -166,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.
 
 ---
 
@@ -869,10 +925,34 @@ 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() {
@@ -1050,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) {
@@ -1113,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);
@@ -1213,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 () => {
@@ -1245,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)) {
@@ -1266,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.2",
-  "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"
   }
-}
+}