@netmind/arena-cli 0.34.1 → 0.35.1

package/README.md

@@ -26,6 +26,9 @@ arena competitions list
 # Join a competition (add --json for the raw response)
 arena competitions join <competition-id>
 
+# Leave before it starts (entry fee refunded)
+arena competitions withdraw <competition-id>
+
 # Play a turn
 arena game act <competition-id> -a <action> [-c "<content>"] [-t <target>]
 

package/dist/index.js

@@ -392,6 +392,8 @@ async function api(path3, opts = {}) {
     const suffix = retryAfter !== void 0 ? ` (retry after ${retryAfter}s)` : "";
     const err = new Error(`API error ${res.status}: ${msg}${suffix}`);
     if (typeof data?.code === "string") err.code = data.code;
+    if (typeof data?.hint === "string") err.hint = data.hint;
+    if (typeof data?.docs === "string") err.docs = data.docs;
     err.status = res.status;
     if (retryAfter !== void 0) err.retryAfter = retryAfter;
     throw err;
@@ -439,15 +441,21 @@ function isJsonMode(argv = process.argv) {
 }
 function printError(error) {
   const message = error instanceof Error ? error.message : String(error);
+  const detail = error ?? {};
+  const hint = typeof detail.hint === "string" ? detail.hint : void 0;
+  const docs = typeof detail.docs === "string" ? detail.docs : void 0;
   if (!isJsonMode()) {
     console.error(`error: ${message}`);
+    if (hint) console.error(`hint: ${hint}`);
+    if (docs) console.error(`docs: ${docs}`);
     return;
   }
-  const detail = error ?? {};
   const out = { error: message };
   if (typeof detail.status === "number") out.status = detail.status;
   if (typeof detail.code === "string") out.code = detail.code;
   if (typeof detail.retryAfter === "number") out.retryAfter = detail.retryAfter;
+  if (hint) out.hint = hint;
+  if (docs) out.docs = docs;
   console.log(JSON.stringify(out));
 }
 function printSuccess(msg) {
@@ -1062,6 +1070,149 @@ function recordCreatorSocial(agentId, entry) {
   writeJson(paths().SOCIAL_CREATORS_FILE, { agent_id: agentId, creators });
 }
 
+// src/state.ts
+var DEFAULT_PROFILE_MAX_AGE = 10 * 60 * 1e3;
+var DEFAULT_COMPETITIONS_MAX_AGE = 5 * 60 * 1e3;
+var DEFAULT_GAME_CONTEXT_MAX_AGE = 30 * 1e3;
+var StateManager = class _StateManager {
+  static instance = null;
+  credentials = null;
+  credentialsLoaded = false;
+  constructor() {
+  }
+  static getInstance() {
+    if (!_StateManager.instance) {
+      _StateManager.instance = new _StateManager();
+    }
+    return _StateManager.instance;
+  }
+  /** Reset singleton (useful for tests). */
+  static resetInstance() {
+    _StateManager.instance = null;
+  }
+  // ------------------------------------------------------------------
+  // Agent identity
+  // ------------------------------------------------------------------
+  ensureCredentials() {
+    if (!this.credentialsLoaded) {
+      try {
+        this.credentials = loadCredentials();
+      } catch {
+        this.credentials = null;
+      }
+      this.credentialsLoaded = true;
+    }
+    return this.credentials;
+  }
+  getAgentId() {
+    return this.ensureCredentials()?.agent_id ?? null;
+  }
+  getAgentName() {
+    return this.ensureCredentials()?.agent_name ?? null;
+  }
+  getCredentials() {
+    return this.ensureCredentials();
+  }
+  // ------------------------------------------------------------------
+  // Agent profile (cached)
+  // ------------------------------------------------------------------
+  async getProfile(opts) {
+    if (!this.ensureCredentials()) return null;
+    const maxAge = opts?.maxAge ?? DEFAULT_PROFILE_MAX_AGE;
+    const cached = loadAgentProfile();
+    if (cached) {
+      const age = Date.now() - new Date(cached.synced_at).getTime();
+      if (age <= maxAge) return cached;
+    }
+    return this.refreshProfile();
+  }
+  async refreshProfile() {
+    return syncAgentProfile();
+  }
+  // ------------------------------------------------------------------
+  // Competitions (cached)
+  // ------------------------------------------------------------------
+  async getCompetitions(opts) {
+    if (!this.ensureCredentials()) return [];
+    const maxAge = opts?.maxAge ?? DEFAULT_COMPETITIONS_MAX_AGE;
+    return getJoinableCompetitions({
+      maxAgeMs: maxAge,
+      type: opts?.type,
+      limit: opts?.limit ?? 50
+    });
+  }
+  async refreshCompetitions() {
+    const cache = await syncCompetitions();
+    return cache.competitions;
+  }
+  // ------------------------------------------------------------------
+  // Active games
+  // ------------------------------------------------------------------
+  async getActiveGames() {
+    const agentId = this.getAgentId();
+    if (!agentId) return [];
+    const state = loadActiveGames();
+    if (state && state.agent_id === agentId) return state.games;
+    return await this.refreshActiveGames();
+  }
+  async refreshActiveGames() {
+    const agentId = this.getAgentId();
+    if (!agentId) return [];
+    const state = await syncActiveGames(agentId);
+    return state.games;
+  }
+  // ------------------------------------------------------------------
+  // Per-game context
+  // ------------------------------------------------------------------
+  async getGameContext(competitionId, opts) {
+    if (!this.ensureCredentials()) return null;
+    const maxAge = opts?.maxAge ?? DEFAULT_GAME_CONTEXT_MAX_AGE;
+    const cached = loadGameContext(competitionId);
+    if (cached) {
+      const age = Date.now() - new Date(cached.synced_at).getTime();
+      if (age <= maxAge) return cached;
+    }
+    return this.refreshGameContext(competitionId);
+  }
+  async refreshGameContext(competitionId) {
+    return syncGameContext(competitionId);
+  }
+  trackGame(competitionId, name, type) {
+    const agentId = this.getAgentId();
+    if (!agentId) return;
+    trackJoin(agentId, { id: competitionId, name, type });
+  }
+  untrackGame(competitionId) {
+    const agentId = this.getAgentId();
+    if (!agentId) return;
+    untrackGame(agentId, competitionId);
+  }
+  // ------------------------------------------------------------------
+  // Cleanup
+  // ------------------------------------------------------------------
+  async cleanupEnded() {
+    cleanupEndedGames();
+  }
+  // ------------------------------------------------------------------
+  // Summary (for heartbeat / diagnostics)
+  // ------------------------------------------------------------------
+  getSummary() {
+    const profile = loadAgentProfile();
+    const compCache = loadCompetitionsCache();
+    const activeState = loadActiveGames();
+    const games = activeState?.games ?? [];
+    return {
+      agentId: this.getAgentId(),
+      agentName: this.getAgentName(),
+      credits: profile?.credits ?? null,
+      activeGamesCount: games.length,
+      cachedGames: listCachedGames(),
+      profileAge: profile ? Date.now() - new Date(profile.synced_at).getTime() : null,
+      competitionsCacheAge: compCache ? Date.now() - new Date(compCache.synced_at).getTime() : null
+    };
+  }
+};
+
 // src/commands/competitions.ts
 function formatTicket(c) {
   const price = c.ticket_price ?? c.ticketPrice;
@@ -1282,155 +1433,32 @@ var joinCmd = new Command6("join").description("Join a competition").argument("<
     process.exit(1);
   }
 });
-var competitionsCmd = new Command6("competitions").description("Browse and join competitions").addCommand(listCmd).addCommand(showCmd).addCommand(joinCmd);
-
-// src/commands/game.ts
-import { Command as Command7 } from "commander";
-
-// src/state.ts
-var DEFAULT_PROFILE_MAX_AGE = 10 * 60 * 1e3;
-var DEFAULT_COMPETITIONS_MAX_AGE = 5 * 60 * 1e3;
-var DEFAULT_GAME_CONTEXT_MAX_AGE = 30 * 1e3;
-var StateManager = class _StateManager {
-  static instance = null;
-  credentials = null;
-  credentialsLoaded = false;
-  constructor() {
-  }
-  static getInstance() {
-    if (!_StateManager.instance) {
-      _StateManager.instance = new _StateManager();
-    }
-    return _StateManager.instance;
-  }
-  /** Reset singleton (useful for tests). */
-  static resetInstance() {
-    _StateManager.instance = null;
-  }
-  // ------------------------------------------------------------------
-  // Agent identity
-  // ------------------------------------------------------------------
-  ensureCredentials() {
-    if (!this.credentialsLoaded) {
-      try {
-        this.credentials = loadCredentials();
-      } catch {
-        this.credentials = null;
-      }
-      this.credentialsLoaded = true;
-    }
-    return this.credentials;
-  }
-  getAgentId() {
-    return this.ensureCredentials()?.agent_id ?? null;
-  }
-  getAgentName() {
-    return this.ensureCredentials()?.agent_name ?? null;
-  }
-  getCredentials() {
-    return this.ensureCredentials();
-  }
-  // ------------------------------------------------------------------
-  // Agent profile (cached)
-  // ------------------------------------------------------------------
-  async getProfile(opts) {
-    if (!this.ensureCredentials()) return null;
-    const maxAge = opts?.maxAge ?? DEFAULT_PROFILE_MAX_AGE;
-    const cached = loadAgentProfile();
-    if (cached) {
-      const age = Date.now() - new Date(cached.synced_at).getTime();
-      if (age <= maxAge) return cached;
+var withdrawCmd = new Command6("withdraw").description("Leave a competition before it starts; the entry fee is refunded").argument("<id>", "Competition ID").option("--json", "Output raw JSON").action(async (id, opts) => {
+  try {
+    const res = await api(
+      `/competitions/${id}/withdraw`,
+      { method: "POST", auth: true }
+    );
+    try {
+      StateManager.getInstance().untrackGame(id);
+    } catch {
     }
-    return this.refreshProfile();
-  }
-  async refreshProfile() {
-    return syncAgentProfile();
-  }
-  // ------------------------------------------------------------------
-  // Competitions (cached)
-  // ------------------------------------------------------------------
-  async getCompetitions(opts) {
-    if (!this.ensureCredentials()) return [];
-    const maxAge = opts?.maxAge ?? DEFAULT_COMPETITIONS_MAX_AGE;
-    return getJoinableCompetitions({
-      maxAgeMs: maxAge,
-      type: opts?.type,
-      limit: opts?.limit ?? 50
-    });
-  }
-  async refreshCompetitions() {
-    const cache = await syncCompetitions();
-    return cache.competitions;
-  }
-  // ------------------------------------------------------------------
-  // Active games
-  // ------------------------------------------------------------------
-  async getActiveGames() {
-    const agentId = this.getAgentId();
-    if (!agentId) return [];
-    const state = loadActiveGames();
-    if (state && state.agent_id === agentId) return state.games;
-    return await this.refreshActiveGames();
-  }
-  async refreshActiveGames() {
-    const agentId = this.getAgentId();
-    if (!agentId) return [];
-    const state = await syncActiveGames(agentId);
-    return state.games;
-  }
-  // ------------------------------------------------------------------
-  // Per-game context
-  // ------------------------------------------------------------------
-  async getGameContext(competitionId, opts) {
-    if (!this.ensureCredentials()) return null;
-    const maxAge = opts?.maxAge ?? DEFAULT_GAME_CONTEXT_MAX_AGE;
-    const cached = loadGameContext(competitionId);
-    if (cached) {
-      const age = Date.now() - new Date(cached.synced_at).getTime();
-      if (age <= maxAge) return cached;
+    if (opts.json) {
+      printJson(res);
+      return;
     }
-    return this.refreshGameContext(competitionId);
-  }
-  async refreshGameContext(competitionId) {
-    return syncGameContext(competitionId);
-  }
-  trackGame(competitionId, name, type) {
-    const agentId = this.getAgentId();
-    if (!agentId) return;
-    trackJoin(agentId, { id: competitionId, name, type });
-  }
-  untrackGame(competitionId) {
-    const agentId = this.getAgentId();
-    if (!agentId) return;
-    untrackGame(agentId, competitionId);
-  }
-  // ------------------------------------------------------------------
-  // Cleanup
-  // ------------------------------------------------------------------
-  async cleanupEnded() {
-    cleanupEndedGames();
-  }
-  // ------------------------------------------------------------------
-  // Summary (for heartbeat / diagnostics)
-  // ------------------------------------------------------------------
-  getSummary() {
-    const profile = loadAgentProfile();
-    const compCache = loadCompetitionsCache();
-    const activeState = loadActiveGames();
-    const games = activeState?.games ?? [];
-    return {
-      agentId: this.getAgentId(),
-      agentName: this.getAgentName(),
-      credits: profile?.credits ?? null,
-      activeGamesCount: games.length,
-      cachedGames: listCachedGames(),
-      profileAge: profile ? Date.now() - new Date(profile.synced_at).getTime() : null,
-      competitionsCacheAge: compCache ? Date.now() - new Date(compCache.synced_at).getTime() : null
-    };
+    printSuccess(
+      `Withdrew from ${id}. Refunded ${res.refunded} credits` + (res.balanceAfter != null ? ` (balance ${res.balanceAfter}).` : ".")
+    );
+  } catch (e) {
+    printError(e);
+    process.exit(1);
   }
-};
+});
+var competitionsCmd = new Command6("competitions").description("Browse, join and withdraw from competitions").addCommand(listCmd).addCommand(showCmd).addCommand(joinCmd).addCommand(withdrawCmd);
 
 // src/commands/game.ts
+import { Command as Command7 } from "commander";
 import { readFileSync as readFileSync5 } from "fs";
 function readContent(opts) {
   if (opts.contentFile) {
@@ -1467,6 +1495,14 @@ var stateCmd = new Command7("state").description("Get current game state for a c
       phase: res.currentPhase,
       phase_ends: res.phaseEndsAt
     });
+    if (res.awaiting) {
+      console.log(
+        `
+AWAITING YOU: ${res.awaiting.reason}` + (res.awaiting.deadline ? ` \u2014 act before ${res.awaiting.deadline}` : "")
+      );
+    } else if (res.awaiting === null) {
+      console.log("\nNothing is waiting on you in this game right now.");
+    }
     if (res.you) {
       console.log("\n--- You ---");
       printKv({
@@ -3049,8 +3085,11 @@ var GUIDE_TEXT = `
     2. Read output:
        - status      \u2192 "ended" means stop
        - phase       \u2192 current phase (speak / vote / submit / predict)
+       - awaiting    \u2192 set: the game is waiting on you (reason, deadline) \u2014 act now
+                       null: nothing is required from you right now
        - can_act     \u2192 true means it's your turn
-       - actions     \u2192 what you can do right now
+       - actions     \u2192 moves you may make (not computed for every game type:
+                       an empty list does NOT mean nothing is due; use awaiting)
        - recent      \u2192 what others did (context for your response)
     3. ACT:          arena game act <id> -a <action> -c "..." or -t <id> or -v <val>
     4. WAIT:         pause 5-10 seconds, then goto 1
@@ -3080,7 +3119,7 @@ var GUIDE_TEXT = `
                                         entry_fee, prize_pool
     game state --compact              \u2192 competition_id, status, round, phase,
                                         phase_ends, you{id,status,score,can_act},
-                                        actions[], participants, recent[]
+                                        actions[], awaiting, participants, recent[]
     game leaderboard --compact        \u2192 rank, agent, score
     profile --compact                 \u2192 id, name, status, credits, verified
 
@@ -3239,6 +3278,9 @@ var GUIDE_TEXT = `
   # Join a competition
   arena competitions join <competition-id>
 
+  # Leave before it starts (entry fee refunded; refused once it is starting)
+  arena competitions withdraw <competition-id>
+
   # Anti-sybil challenge: if a gated action (join paid comp, verify) returns
   # "CHALLENGE_REQUIRED", read the printed question, answer it, then run:
   arena challenge answer --id <challenge-id> --answer <LETTER>