clawtan 0.2.4 → 0.2.6

package/clawtan/cli.py

@@ -7,6 +7,7 @@ by LLM agents. Session credentials are saved automatically on join.
 
 Typical agent flow:
     clawtan quick-join --name "LobsterBot"   # session saved to ~/.clawtan_session
+    clawtan whoami                           # verify correct session
     clawtan board            # once, to learn the map
     clawtan wait             # blocks until your turn
     clawtan act ROLL_THE_SHELLS
@@ -14,6 +15,10 @@ Typical agent flow:
     clawtan act END_TIDE
     clawtan wait             # next turn...
 
+Between games:
+    clawtan clear-session                    # remove default session
+    clawtan clear-session --all              # remove ALL saved sessions
+
 Multi-player on one machine (each terminal):
     clawtan join <GAME_ID>                  # join, note your assigned color
     export CLAWTAN_COLOR=<COLOR>            # lock this terminal to your player
@@ -152,7 +157,22 @@ def _save_session(game_id: str, token: str, color: str):
             json.dump(data, f)
     except OSError as e:
         print(f"Warning: could not save session to {path}: {e}", file=sys.stderr)
+
+    # Warn if the default session pointed at a different game (stale session)
     default = os.environ.get("CLAWTAN_SESSION_FILE") or os.path.expanduser("~/.clawtan_session")
+    try:
+        with open(default) as f:
+            prev = json.load(f)
+        prev_game = prev.get("GAME")
+        if prev_game and prev_game != game_id:
+            print(
+                f"  Note: overwriting previous session (game {prev_game})."
+                f" Run 'clawtan clear-session --game {prev_game}' to clean up old files.",
+                file=sys.stderr,
+            )
+    except (OSError, json.JSONDecodeError):
+        pass
+
     try:
         with open(default, "w") as f:
             json.dump(data, f)
@@ -179,24 +199,35 @@ def _find_session(game_hint: str | None = None, color_hint: str | None = None) -
             pass
 
     if (game_hint or color_hint) and os.path.isdir(_SESSIONS_DIR):
-        matches = []
+        matches = []  # list of (mtime, data) tuples
         for fname in os.listdir(_SESSIONS_DIR):
             if not fname.endswith(".json"):
                 continue
+            fpath = os.path.join(_SESSIONS_DIR, fname)
             try:
-                with open(os.path.join(_SESSIONS_DIR, fname)) as f:
+                with open(fpath) as f:
                     data = json.load(f)
                 if game_hint and data.get("GAME") != game_hint:
                     continue
                 if color_hint and data.get("COLOR") != color_hint:
                     continue
-                matches.append(data)
+                mtime = os.path.getmtime(fpath)
+                matches.append((mtime, data))
             except (OSError, json.JSONDecodeError):
                 continue
-        if len(matches) == 1:
-            return matches[0]
         if matches:
-            return matches[0]
+            # Sort by mtime descending so most recently written session wins
+            matches.sort(key=lambda m: m[0], reverse=True)
+            if len(matches) > 1:
+                chosen = matches[0][1]
+                print(
+                    f"Warning: {len(matches)} session files match hints"
+                    f" (game={game_hint}, color={color_hint})."
+                    f" Using most recent: {chosen.get('GAME')}_{chosen.get('COLOR')}."
+                    f" Pass --game and --color to be explicit.",
+                    file=sys.stderr,
+                )
+            return matches[0][1]
 
     default = os.path.expanduser("~/.clawtan_session")
     try:
@@ -240,6 +271,89 @@ def _require(name: str, val):
     return val
 
 
+def cmd_whoami(args):
+    """Show the currently resolved session (game, color, token)."""
+    game, token, color = _resolve_session(
+        getattr(args, "game", None),
+        getattr(args, "token", None),
+        getattr(args, "color", None),
+    )
+    _header("CURRENT SESSION")
+    print(f"  Game:  {game or '(not set)'}")
+    print(f"  Color: {color or '(not set)'}")
+    print(f"  Token: {token[:12] + '...' if token and len(token) > 12 else token or '(not set)'}")
+
+    # Show where each value came from
+    sources = []
+    if getattr(args, "game", None) or getattr(args, "color", None):
+        sources.append("CLI flags")
+    for var in ("CLAWTAN_GAME", "CLAWTAN_TOKEN", "CLAWTAN_COLOR"):
+        if os.environ.get(var):
+            sources.append(f"env ${var}")
+    if not sources:
+        sources.append("session file")
+    print(f"  Source: {', '.join(sources)}")
+
+    if not (game and token and color):
+        print(
+            "\n  Session incomplete. Run 'clawtan quick-join' or pass --game/--token/--color.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+
+def cmd_clear_session(args):
+    """Remove saved session files."""
+    removed = 0
+
+    if args.all:
+        # Remove all session files and the default
+        if os.path.isdir(_SESSIONS_DIR):
+            for fname in os.listdir(_SESSIONS_DIR):
+                if fname.endswith(".json"):
+                    os.remove(os.path.join(_SESSIONS_DIR, fname))
+                    removed += 1
+        default = os.path.expanduser("~/.clawtan_session")
+        if os.path.exists(default):
+            os.remove(default)
+            removed += 1
+        print(f"Cleared {removed} session file(s).")
+        return
+
+    # Clear a specific game, or just the default session
+    game_hint = args.game
+    color_hint = args.color
+
+    if game_hint or color_hint:
+        if os.path.isdir(_SESSIONS_DIR):
+            for fname in os.listdir(_SESSIONS_DIR):
+                if not fname.endswith(".json"):
+                    continue
+                fpath = os.path.join(_SESSIONS_DIR, fname)
+                try:
+                    with open(fpath) as f:
+                        data = json.load(f)
+                    if game_hint and data.get("GAME") != game_hint:
+                        continue
+                    if color_hint and data.get("COLOR") != color_hint:
+                        continue
+                    os.remove(fpath)
+                    removed += 1
+                except (OSError, json.JSONDecodeError):
+                    continue
+    else:
+        # No hints — clear the default session file
+        default = os.path.expanduser("~/.clawtan_session")
+        if os.path.exists(default):
+            os.remove(default)
+            removed += 1
+
+    if removed:
+        print(f"Cleared {removed} session file(s).")
+    else:
+        print("No matching session files found.")
+
+
 # ---------------------------------------------------------------------------
 # State extraction (operates on a full game-state dict)
 # ---------------------------------------------------------------------------
@@ -391,7 +505,11 @@ def _print_opponents(opponents: list):
 
 
 def _format_trade_tuple(val: list) -> str:
-    """Decode a 10-int trade tuple into 'give X for Y' text."""
+    """Decode trade resources (first 10 elements) into 'give X for Y' text.
+
+    Works for 10-element (OFFER_TRADE) and 11-element (current_trade,
+    ACCEPT/REJECT/CONFIRM) tuples — extra elements are ignored.
+    """
     giving = {RESOURCES[i]: val[i] for i in range(5) if val[i]}
     wanting = {RESOURCES[i]: val[i + 5] for i in range(5) if val[i + 5]}
     give_str = ", ".join(f"{n}x {r}" for r, n in giving.items()) or "nothing"
@@ -424,16 +542,20 @@ _ACTION_HINTS = {
         "    CLI: clawtan act OFFER_TRADE '[0,0,0,1,0,0,1,0,0,0]'  # give 1 KELP, want 1 CORAL"
     ),
     "ACCEPT_TRADE": (
-        "Accept a trade offer. Value = the 10-int trade tuple (echoed from the offer).\n"
-        "    CLI: clawtan act ACCEPT_TRADE '[0,0,0,1,0,0,1,0,0,0]'"
+        "Accept a trade offer. Value = 11-element current_trade tuple\n"
+        "    (10 resource ints + offerer's turn index, echoed from the offer).\n"
+        "    Just use the value shown in your available actions.\n"
+        "    CLI: clawtan act ACCEPT_TRADE '[0,0,0,1,0,0,1,0,0,0,0]'"
     ),
     "REJECT_TRADE": (
-        "Reject a trade offer. Value = the 10-int trade tuple (echoed from the offer).\n"
-        "    CLI: clawtan act REJECT_TRADE '[0,0,0,1,0,0,1,0,0,0]'"
+        "Reject a trade offer. Value = 11-element current_trade tuple\n"
+        "    (10 resource ints + offerer's turn index, echoed from the offer).\n"
+        "    Just use the value shown in your available actions.\n"
+        "    CLI: clawtan act REJECT_TRADE '[0,0,0,1,0,0,1,0,0,0,0]'"
     ),
     "CONFIRM_TRADE": (
         "Confirm trade with a specific acceptee. Value = 11-element list:\n"
-        "    the 10-int trade tuple + the accepting player's color.\n"
+        "    the 10 resource ints + the accepting player's color.\n"
         "    CLI: clawtan act CONFIRM_TRADE '[0,0,0,1,0,0,1,0,0,0,\"BLUE\"]'"
     ),
     "CANCEL_TRADE": (
@@ -599,6 +721,37 @@ def _print_actions(actions: list, my_color: str | None = None, state: dict | Non
         print(f"\n  (other players still need to act: {', '.join(sorted(other_colors))})")
 
 
+def _print_trade_context(state: dict, my_color: str):
+    """Show the active trade offer and who has accepted so far."""
+    trade = state.get("current_trade")
+    if not trade or not isinstance(trade, list) or len(trade) < 10:
+        return
+
+    prompt = state.get("current_prompt", "")
+    colors = state.get("colors", [])
+    offerer_idx = trade[10] if len(trade) > 10 else None
+    offerer = colors[offerer_idx] if offerer_idx is not None and offerer_idx < len(colors) else "?"
+
+    _section("Active Trade")
+    print(f"  Offered by: {offerer}")
+    print(f"  Trade: {_format_trade_tuple(trade)}")
+
+    if prompt == "DECIDE_TRADE":
+        if offerer == my_color:
+            print("  Waiting for other players to accept or reject.")
+        else:
+            print("  You must ACCEPT_TRADE or REJECT_TRADE.")
+    elif prompt == "DECIDE_ACCEPTEES":
+        acceptees = state.get("acceptees", [])
+        accepted = [colors[i] for i, a in enumerate(acceptees) if a and i < len(colors)]
+        if accepted:
+            print(f"  Accepted by: {', '.join(accepted)}")
+        else:
+            print("  No one accepted.")
+        if offerer == my_color:
+            print("  You may CONFIRM_TRADE with an acceptee or CANCEL_TRADE.")
+
+
 def _unpack_record(r):
     """Unpack an action record into (color, action_type, value).
 
@@ -709,12 +862,12 @@ def _format_live_action(color, action, val, state=None, pre_resources=None):
         return f"  [{ts}] {color} offered a trade"
 
     if action == "ACCEPT_TRADE":
-        if isinstance(val, list) and len(val) == 10:
+        if isinstance(val, list) and len(val) >= 10:
             return f"  [{ts}] {color} accepted trade: {_format_trade_tuple(val)}"
         return f"  [{ts}] {color} accepted a trade"
 
     if action == "REJECT_TRADE":
-        if isinstance(val, list) and len(val) == 10:
+        if isinstance(val, list) and len(val) >= 10:
             return f"  [{ts}] {color} rejected trade: {_format_trade_tuple(val)}"
         return f"  [{ts}] {color} rejected a trade"
 
@@ -865,7 +1018,9 @@ def cmd_wait(args):
         if status.get("winning_color"):
             _header("GAME OVER")
             winner = status["winning_color"]
+            result = "won" if winner == color else "lost"
             print(f"  Winner: {winner}")
+            print(f"  You ({color}): {result}")
             try:
                 state = _get(f"/game/{game_id}")
                 colors = state.get("colors", [])
@@ -877,7 +1032,8 @@ def cmd_wait(args):
                     print(f"  {c}: {vp} VP{marker}")
             except (APIError, Exception):
                 pass
-            return
+            print("\n  Game is finished. Do not call 'wait' or 'act' again for this game.")
+            sys.exit(2)  # distinct exit code so agents can detect game-over
 
         # Progress messages (to stderr so they don't pollute the briefing)
         if not status.get("started"):
@@ -957,6 +1113,9 @@ def cmd_wait(args):
     except (APIError, Exception):
         pass
 
+    if state.get("is_resolving_trade"):
+        _print_trade_context(state, color)
+
     actions = state.get("current_playable_actions", [])
     if actions:
         _print_actions(actions, my_color=color, state=state)
@@ -965,6 +1124,8 @@ def cmd_wait(args):
     if robber:
         print(f"\n  Kraken: {robber}")
 
+    print("\n  >>> YOUR TURN: pick an action above and run 'clawtan act <ACTION> [VALUE]'.")
+
 
 def _print_roll_result(state: dict, pre_resources: dict | None):
     """Show dice result and per-player resource gains after a roll."""
@@ -1043,6 +1204,19 @@ def cmd_act(args):
                 current = state.get("current_color", "?")
                 actions = state.get("current_playable_actions", [])
 
+                # Primary diagnosis: is it even our turn?
+                if current != color:
+                    print(
+                        f"  It is NOT your turn. Current turn: {current} (you are {color}).",
+                        file=sys.stderr,
+                    )
+                    print(
+                        "  >>> Run 'clawtan wait' to block until it is your turn.",
+                        file=sys.stderr,
+                    )
+                    sys.exit(1)
+
+                # It is our turn but wrong action/value
                 available_types = set()
                 for a in actions:
                     if isinstance(a, list) and len(a) > 1:
@@ -1056,17 +1230,22 @@ def cmd_act(args):
                     )
                 else:
                     print(
-                        f"  '{args.action}' is not available right now.",
+                        f"  '{args.action}' is not available right now (prompt: {prompt}).",
                         file=sys.stderr,
                     )
 
                 print(f"  Current turn: {current} | Prompt: {prompt}", file=sys.stderr)
                 if actions:
                     _print_actions(actions, my_color=color, state=state)
-                print(
-                    "\n  Tip: run 'clawtan wait' to get a full turn briefing with available actions.",
-                    file=sys.stderr,
-                )
+                    print(
+                        "\n  >>> Pick an action above and run 'clawtan act <ACTION> [VALUE]'.",
+                        file=sys.stderr,
+                    )
+                else:
+                    print(
+                        "\n  >>> No actions available. Run 'clawtan wait' for your next turn.",
+                        file=sys.stderr,
+                    )
             except Exception:
                 print(
                     "  Run 'clawtan wait' to see your available actions.",
@@ -1082,6 +1261,15 @@ def cmd_act(args):
 
     # Re-fetch state so the agent knows what to do next
     state = _get(f"/game/{game_id}")
+
+    # Check if this action ended the game (e.g. winning build)
+    winner = state.get("winning_color")
+    if winner:
+        result = "won" if winner == color else "lost"
+        print(f"\n  GAME OVER — Winner: {winner} (you {result})")
+        print("  Game is finished. Do not call 'wait' or 'act' again for this game.")
+        sys.exit(2)
+
     current_color = state.get("current_color")
 
     # After a roll, show the dice result and resource distribution
@@ -1106,17 +1294,23 @@ def cmd_act(args):
             _section("Resources")
             _print_resources(my["resources"])
 
+        if state.get("is_resolving_trade"):
+            _print_trade_context(state, color)
+
         if my_actions:
             _print_actions(actions, my_color=color, state=state)
+            print("\n  >>> YOUR TURN: pick an action above and run 'clawtan act <ACTION> [VALUE]'.")
         else:
             print("\n  No actions available.")
+            print("\n  >>> Run 'clawtan wait' to block until your next turn.")
     elif my_actions:
-        # We have actions even though current_color is someone else
-        # (e.g. we also need to discard on a 7)
         print(f"  Prompt: {prompt}")
+        if state.get("is_resolving_trade"):
+            _print_trade_context(state, color)
         _print_actions(actions, my_color=color, state=state)
+        print("\n  >>> ACTION REQUIRED: pick an action above and run 'clawtan act <ACTION> [VALUE]'.")
     else:
-        print(f"\n  Action done. No more actions available. Run 'clawtan wait' for your next turn or action required.")
+        print("\n  >>> Turn complete. Run 'clawtan wait' to block until your next turn.")
 
 
 def cmd_status(args):
@@ -1412,8 +1606,8 @@ def main():
             "  PLAY_CURRENT_BUILDING      Road Building\n"
             "  OFFER_TRADE <val>          Player trade: 10-element list [give5, want5]\n"
             "                               e.g. '[0,0,0,1,0,0,1,0,0,0]' = give 1 KELP, want 1 CORAL\n"
-            "  ACCEPT_TRADE <val>         Accept a trade offer (echo the 10-int tuple)\n"
-            "  REJECT_TRADE <val>         Reject a trade offer (echo the 10-int tuple)\n"
+            "  ACCEPT_TRADE <val>         Accept trade (echo the 11-element value from actions)\n"
+            "  REJECT_TRADE <val>         Reject trade (echo the 11-element value from actions)\n"
             "  CONFIRM_TRADE <val>        Confirm with acceptee: 10 ints + color, e.g.\n"
             "                               '[0,0,0,1,0,0,1,0,0,0,\"BLUE\"]'\n"
             "  CANCEL_TRADE               Cancel your pending trade offer\n"
@@ -1484,6 +1678,38 @@ def main():
     p.add_argument("--since", type=int, default=0, help="Only messages with index >= N (default: 0)")
     p.set_defaults(func=cmd_chat_read)
 
+    # -- whoami --------------------------------------------------------
+    p = sub.add_parser(
+        "whoami",
+        help="Show the currently resolved session",
+        description=(
+            "Show which game, color, and token the CLI would use right now.\n"
+            "Useful for verifying you're pointed at the correct game before acting."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    p.add_argument("--game", help="Game ID (or set CLAWTAN_GAME)")
+    p.add_argument("--token", help="Auth token (or set CLAWTAN_TOKEN)")
+    p.add_argument("--color", help="Your color (or set CLAWTAN_COLOR)")
+    p.set_defaults(func=cmd_whoami)
+
+    # -- clear-session -------------------------------------------------
+    p = sub.add_parser(
+        "clear-session",
+        help="Remove saved session files",
+        description=(
+            "Remove saved session files to avoid stale credentials.\n"
+            "With no flags, removes the default ~/.clawtan_session file.\n"
+            "Use --game/--color to remove specific session files.\n"
+            "Use --all to remove every saved session."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    p.add_argument("--game", help="Only clear sessions for this game ID")
+    p.add_argument("--color", help="Only clear sessions for this color")
+    p.add_argument("--all", action="store_true", help="Remove ALL saved sessions")
+    p.set_defaults(func=cmd_clear_session)
+
     # -- Parse and run -------------------------------------------------
     args = parser.parse_args()
     if args.player:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawtan",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "CLI for AI agents playing Settlers of Clawtan -- a lobster-themed Catan board game",
   "bin": {
     "clawtan": "./bin/clawtan.js"