clawtan 0.1.13 → 0.2.1

package/clawtan/cli.py

@@ -3,22 +3,35 @@
 clawtan -- CLI for AI agents playing Settlers of Clawtan.
 
 Every command prints structured text to stdout designed for easy scanning
-by LLM agents. Set environment variables for session persistence:
-
-    CLAWTAN_SERVER  Server URL (default: http://localhost:8000)
-    CLAWTAN_GAME    Game ID
-    CLAWTAN_TOKEN   Auth token from join
-    CLAWTAN_COLOR   Your player color
+by LLM agents. Session credentials are saved automatically on join.
 
 Typical agent flow:
-    clawtan quick-join --name "LobsterBot"
-    export CLAWTAN_GAME=...  CLAWTAN_TOKEN=...  CLAWTAN_COLOR=...
+    clawtan quick-join --name "LobsterBot"   # session saved to ~/.clawtan_session
     clawtan board            # once, to learn the map
     clawtan wait             # blocks until your turn
     clawtan act ROLL_THE_SHELLS
     clawtan act BUILD_TIDE_POOL 42
     clawtan act END_TIDE
     clawtan wait             # next turn...
+
+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
+    clawtan wait                            # now uses the correct session
+
+  Or use --player on every call (works with separate exec calls):
+    clawtan --player BLUE wait
+    clawtan --player BLUE act ROLL_THE_SHELLS
+
+  Same color in multiple games — add --game:
+    clawtan --player RED wait --game <GAME_ID>
+
+Session lookup order (per field):
+    1. CLI flags (--game, --token, --color, --player)
+    2. Environment variables (CLAWTAN_GAME, CLAWTAN_TOKEN, CLAWTAN_COLOR)
+    3. Session file: ~/.clawtan_sessions/<game>_<color>.json matched by
+       available hints, falling back to ~/.clawtan_session.
+       Override with CLAWTAN_SESSION_FILE.
 """
 
 import argparse
@@ -125,13 +138,102 @@ def _get(path, token=None):
 
 
 # ---------------------------------------------------------------------------
-# Environment variable helpers
+# Session file helpers
 # ---------------------------------------------------------------------------
-def _env(name: str, arg_val=None, required=True):
-    val = arg_val or os.environ.get(f"CLAWTAN_{name}")
-    if required and not val:
+_SESSIONS_DIR = os.path.expanduser("~/.clawtan_sessions")
+
+
+def _save_session(game_id: str, token: str, color: str):
+    data = {"GAME": game_id, "TOKEN": token, "COLOR": color}
+    os.makedirs(_SESSIONS_DIR, exist_ok=True)
+    path = os.path.join(_SESSIONS_DIR, f"{game_id}_{color}.json")
+    try:
+        with open(path, "w") as f:
+            json.dump(data, f)
+    except OSError as e:
+        print(f"Warning: could not save session to {path}: {e}", file=sys.stderr)
+    default = os.environ.get("CLAWTAN_SESSION_FILE") or os.path.expanduser("~/.clawtan_session")
+    try:
+        with open(default, "w") as f:
+            json.dump(data, f)
+    except OSError:
+        pass
+
+
+def _find_session(game_hint: str | None = None, color_hint: str | None = None) -> dict:
+    """Find a session file using available game/color hints."""
+    custom = os.environ.get("CLAWTAN_SESSION_FILE")
+    if custom:
+        try:
+            with open(custom) as f:
+                return json.load(f)
+        except (OSError, json.JSONDecodeError):
+            return {}
+
+    if game_hint and color_hint:
+        path = os.path.join(_SESSIONS_DIR, f"{game_hint}_{color_hint}.json")
+        try:
+            with open(path) as f:
+                return json.load(f)
+        except (OSError, json.JSONDecodeError):
+            pass
+
+    if (game_hint or color_hint) and os.path.isdir(_SESSIONS_DIR):
+        matches = []
+        for fname in os.listdir(_SESSIONS_DIR):
+            if not fname.endswith(".json"):
+                continue
+            try:
+                with open(os.path.join(_SESSIONS_DIR, fname)) 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)
+            except (OSError, json.JSONDecodeError):
+                continue
+        if len(matches) == 1:
+            return matches[0]
+        if matches:
+            return matches[0]
+
+    default = os.path.expanduser("~/.clawtan_session")
+    try:
+        with open(default) as f:
+            return json.load(f)
+    except (OSError, json.JSONDecodeError):
+        return {}
+
+
+# ---------------------------------------------------------------------------
+# Session resolution
+# ---------------------------------------------------------------------------
+def _resolve_session(arg_game=None, arg_token=None, arg_color=None):
+    """Resolve game, token, color from flags -> env vars -> session file.
+
+    Uses all available hints together to find the correct session file,
+    which avoids ambiguity when multiple games or players share a machine.
+    """
+    game = arg_game or os.environ.get("CLAWTAN_GAME") or None
+    token = arg_token or os.environ.get("CLAWTAN_TOKEN") or None
+    color = arg_color or os.environ.get("CLAWTAN_COLOR") or None
+
+    if not (game and token and color):
+        session = _find_session(game_hint=game, color_hint=color)
+        game = game or session.get("GAME")
+        token = token or session.get("TOKEN")
+        color = color or session.get("COLOR")
+
+    return game, token, color
+
+
+def _require(name: str, val):
+    """Exit with error if a required session value is missing."""
+    if not val:
         print(
-            f"ERROR: Missing {name}. Pass --{name.lower()} or set CLAWTAN_{name}",
+            f"ERROR: Missing {name}. Pass --{name.lower()}, set CLAWTAN_{name},"
+            f" or run 'clawtan quick-join' to create a session.",
             file=sys.stderr,
         )
         sys.exit(1)
@@ -290,10 +392,8 @@ def _print_opponents(opponents: list):
 
 _ACTION_HINTS = {
     "RELEASE_CATCH": (
-        "Discard cards. Run with no value to discard randomly:\n"
-        "    CLI: clawtan act RELEASE_CATCH\n"
-        "    Or pick specific cards (freqdeck=[DRIFTWOOD,CORAL,SHRIMP,KELP,PEARL]):\n"
-        "    CLI: clawtan act RELEASE_CATCH '[1,0,0,1,0]'"
+        "Discard half your cards (server selects randomly).\n"
+        "    CLI: clawtan act RELEASE_CATCH"
     ),
     "MOVE_THE_KRAKEN": (
         "Move robber: value = [coordinate, victim_color_or_null, null].\n"
@@ -360,17 +460,34 @@ def _print_actions(actions: list, my_color: str | None = None):
         print(f"\n  (other players still need to act: {', '.join(sorted(other_colors))})")
 
 
+def _unpack_record(r):
+    """Unpack an action record into (color, action_type, value).
+
+    Records may be nested [[color, type, value], result] or flat [color, type, value].
+    """
+    if isinstance(r, list) and len(r) >= 2 and isinstance(r[0], list):
+        action = r[0]
+        color = action[0] if len(action) > 0 else None
+        atype = action[1] if len(action) > 1 else None
+        val = action[2] if len(action) > 2 else None
+        return color, atype, val
+    if isinstance(r, list) and len(r) >= 2:
+        color = r[0]
+        atype = r[1]
+        val = r[2] if len(r) > 2 else None
+        return color, atype, val
+    return None, None, None
+
+
 def _print_history(records: list, since: int = 0):
     recent = records[since:]
     if not recent:
         return
     _section(f"Recent Actions ({len(recent)} moves)")
     for r in recent:
-        if isinstance(r, list) and len(r) >= 2:
-            color = r[0]
-            action = r[1]
-            val = r[2] if len(r) > 2 and r[2] is not None else ""
-            if val != "":
+        color, action, val = _unpack_record(r)
+        if color and action:
+            if val is not None:
                 print(f"  {color}: {action} {json.dumps(val, separators=(',', ':'))}")
             else:
                 print(f"  {color}: {action}")
@@ -378,6 +495,25 @@ def _print_history(records: list, since: int = 0):
             print(f"  {r}")
 
 
+def _count_turns(state: dict) -> int:
+    """Count ROLL_THE_SHELLS records to get the turn number."""
+    count = 0
+    for r in state.get("action_records", []):
+        _, atype, _ = _unpack_record(r)
+        if atype == "ROLL_THE_SHELLS":
+            count += 1
+    return count
+
+
+def _who_rolled_last(state: dict) -> str | None:
+    """Return the color of the player who made the most recent roll."""
+    for r in reversed(state.get("action_records", [])):
+        color, atype, _ = _unpack_record(r)
+        if atype == "ROLL_THE_SHELLS":
+            return color
+    return None
+
+
 def _print_chat(messages: list, label: str = "Chat"):
     if not messages:
         return
@@ -424,16 +560,22 @@ def _print_join(resp: dict):
     print(f"  Seat:    {resp['seat_index']}")
     print(f"  Players: {resp['players_joined']}")
     print(f"  Started: {'yes' if resp.get('game_started') else 'no'}")
-    print(f"\nSet your session:")
-    print(f"  export CLAWTAN_GAME={resp['game_id']}")
-    print(f"  export CLAWTAN_TOKEN={resp['token']}")
-    print(f"  export CLAWTAN_COLOR={resp['player_color']}")
+
+    _save_session(resp["game_id"], resp["token"], resp["player_color"])
+    gid = resp["game_id"]
+    color = resp["player_color"]
+    print(f"\n  Session saved to ~/.clawtan_sessions/{gid}_{color}.json")
+    print(f"\n  Multi-player setup — pick ONE option:")
+    print(f"    export CLAWTAN_COLOR={color}                 # env var per terminal")
+    print(f"    clawtan --player {color} <command>           # flag per command")
+    print(f"    clawtan --player {color} wait --game {gid}   # if same color in multiple games")
 
 
 def cmd_wait(args):
-    game_id = _env("GAME", args.game)
-    token = _env("TOKEN", args.token)
-    color = _env("COLOR", args.color)
+    game_id, token, color = _resolve_session(args.game, args.token, args.color)
+    _require("GAME", game_id)
+    _require("TOKEN", token)
+    _require("COLOR", color)
     poll = args.poll
     deadline = time.monotonic() + args.timeout
 
@@ -510,7 +652,7 @@ def cmd_wait(args):
     state = _get(f"/game/{game_id}")
 
     prompt = state.get("current_prompt", "?")
-    turns = state.get("num_turns", "?")
+    turns = status.get("num_turns") or state.get("num_turns") or _count_turns(state)
 
     _header("YOUR TURN")
     print(f"  Game: {game_id}")
@@ -551,8 +693,9 @@ def _print_roll_result(state: dict, pre_resources: dict | None):
     records = state.get("action_records", [])
     roll_val = None
     for r in reversed(records):
-        if isinstance(r, list) and len(r) >= 2 and r[1] == "ROLL_THE_SHELLS":
-            roll_val = r[2] if len(r) > 2 else None
+        color, atype, val = _unpack_record(r)
+        if atype == "ROLL_THE_SHELLS":
+            roll_val = val
             break
 
     if roll_val is not None:
@@ -584,9 +727,10 @@ def _print_roll_result(state: dict, pre_resources: dict | None):
 
 
 def cmd_act(args):
-    game_id = _env("GAME", args.game)
-    token = _env("TOKEN", args.token)
-    color = _env("COLOR", args.color)
+    game_id, token, color = _resolve_session(args.game, args.token, args.color)
+    _require("GAME", game_id)
+    _require("TOKEN", token)
+    _require("COLOR", color)
 
     # Snapshot resources before rolling so we can diff afterwards
     pre_resources = None
@@ -679,34 +823,13 @@ def cmd_act(args):
         # (e.g. we also need to discard on a 7)
         print(f"  Prompt: {prompt}")
         _print_actions(actions, my_color=color)
-        print(
-            f"\n  Note: {current_color} is also acting (e.g. discarding)."
-            f" Your turn will continue after -- run 'clawtan wait'.",
-        )
-    elif prompt in ("RELEASE_CATCH", "MOVE_THE_KRAKEN", "DISCARD"):
-        # Discard/robber phase -- other players are acting but our turn resumes after
-        _section("Waiting on Other Players")
-        # Figure out which players need to act
-        other_colors = set()
-        for a in actions:
-            if isinstance(a, list) and len(a) > 1 and a[0] and a[0] != color:
-                other_colors.add(a[0])
-        if other_colors:
-            print(f"  {', '.join(sorted(other_colors))} must {prompt.lower().replace('_', ' ')} first.")
-        else:
-            print(f"  Current prompt: {prompt} (waiting on {current_color})")
-        print(
-            f"\n  YOUR TURN IS NOT OVER. After they finish, you will continue"
-            f" (e.g. move the Kraken, then play your turn)."
-            f"\n  Run 'clawtan wait' to resume."
-        )
     else:
-        print(f"\n  Turn passed to {current_color}. Run 'clawtan wait' for your next turn.")
+        print(f"\n  Action done. No more actions available. Run 'clawtan wait' for your next turn or action required.")
 
 
 def cmd_status(args):
-    game_id = _env("GAME", args.game)
-    token = _env("TOKEN", args.token, required=False)
+    game_id, token, _ = _resolve_session(args.game, args.token)
+    _require("GAME", game_id)
 
     status = _get(f"/game/{game_id}/status", token=token)
 
@@ -730,7 +853,8 @@ def cmd_status(args):
 
 
 def cmd_board(args):
-    game_id = _env("GAME", args.game)
+    game_id, _, _ = _resolve_session(args.game)
+    _require("GAME", game_id)
     state = _get(f"/game/{game_id}")
 
     if not state.get("started") or not state.get("tiles"):
@@ -860,14 +984,16 @@ def cmd_board(args):
 
 
 def cmd_chat(args):
-    game_id = _env("GAME", args.game)
-    token = _env("TOKEN", args.token)
+    game_id, token, _ = _resolve_session(args.game, args.token)
+    _require("GAME", game_id)
+    _require("TOKEN", token)
     _post(f"/game/{game_id}/chat", {"message": args.message}, token=token)
     print("Chat sent.")
 
 
 def cmd_chat_read(args):
-    game_id = _env("GAME", args.game)
+    game_id, _, _ = _resolve_session(args.game)
+    _require("GAME", game_id)
     resp = _get(f"/game/{game_id}/chat?since={args.since}")
     msgs = resp.get("messages", [])
     if msgs:
@@ -892,6 +1018,11 @@ def main():
         ),
         formatter_class=argparse.RawDescriptionHelpFormatter,
     )
+    parser.add_argument(
+        "--player",
+        metavar="COLOR",
+        help="Player color — selects the per-player session file (for multi-player on one machine)",
+    )
     sub = parser.add_subparsers(dest="command", required=True)
 
     # -- create --------------------------------------------------------
@@ -968,7 +1099,7 @@ def main():
             "  BUY_TREASURE_MAP           Buy dev card\n"
             "  SUMMON_LOBSTER_GUARD       Play knight card\n"
             "  MOVE_THE_KRAKEN <val>      Move robber, e.g. '[[0,1,-1],\"BLUE\",null]'\n"
-            "  RELEASE_CATCH [freqdeck]   Discard cards (no value = random), e.g. '[1,0,0,1,0]'\n"
+            "  RELEASE_CATCH              Discard half your cards (server selects randomly)\n"
             "  PLAY_BOUNTIFUL_HARVEST <r> Year of Plenty, e.g. '[\"DRIFTWOOD\",\"CORAL\"]'\n"
             "  PLAY_TIDAL_MONOPOLY <res>  Monopoly, e.g. SHRIMP\n"
             "  PLAY_CURRENT_BUILDING      Road Building\n"
@@ -1041,6 +1172,8 @@ def main():
 
     # -- Parse and run -------------------------------------------------
     args = parser.parse_args()
+    if args.player:
+        os.environ["CLAWTAN_COLOR"] = args.player
     try:
         args.func(args)
     except APIError as e:

package/package.json

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