clawtan 0.2.0 → 0.2.2

package/clawtan/cli.py

@@ -14,10 +14,24 @@ Typical agent flow:
     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)
+    1. CLI flags (--game, --token, --color, --player)
     2. Environment variables (CLAWTAN_GAME, CLAWTAN_TOKEN, CLAWTAN_COLOR)
-    3. Session file (~/.clawtan_session, override with CLAWTAN_SESSION_FILE)
+    3. Session file: ~/.clawtan_sessions/<game>_<color>.json matched by
+       available hints, falling back to ~/.clawtan_session.
+       Override with CLAWTAN_SESSION_FILE.
 """
 
 import argparse
@@ -126,42 +140,97 @@ def _get(path, token=None):
 # ---------------------------------------------------------------------------
 # Session file helpers
 # ---------------------------------------------------------------------------
-def _session_path() -> str:
-    return os.environ.get("CLAWTAN_SESSION_FILE") or os.path.expanduser("~/.clawtan_session")
+_SESSIONS_DIR = os.path.expanduser("~/.clawtan_sessions")
 
 
 def _save_session(game_id: str, token: str, color: str):
-    path = _session_path()
     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]
 
-def _load_session() -> dict:
-    path = _session_path()
+    default = os.path.expanduser("~/.clawtan_session")
     try:
-        with open(path) as f:
+        with open(default) as f:
             return json.load(f)
     except (OSError, json.JSONDecodeError):
         return {}
 
 
 # ---------------------------------------------------------------------------
-# Environment / session variable helpers
+# Session resolution
 # ---------------------------------------------------------------------------
-def _env(name: str, arg_val=None, required=True):
-    # 1. CLI flag
-    val = arg_val
-    # 2. Environment variable
-    if not val:
-        val = os.environ.get(f"CLAWTAN_{name}")
-    # 3. Session file
+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:
-        val = _load_session().get(name)
-    if required and not val:
         print(
             f"ERROR: Missing {name}. Pass --{name.lower()}, set CLAWTAN_{name},"
             f" or run 'clawtan quick-join' to create a session.",
@@ -327,7 +396,7 @@ _ACTION_HINTS = {
         "    CLI: clawtan act RELEASE_CATCH"
     ),
     "MOVE_THE_KRAKEN": (
-        "Move robber: value = [coordinate, victim_color_or_null, null].\n"
+        "Move Kraken: value = [coordinate, victim_color_or_null, null].\n"
         "    CLI: clawtan act MOVE_THE_KRAKEN '[[0,1,-1],\"BLUE\",null]'"
     ),
     "OCEAN_TRADE": (
@@ -342,7 +411,101 @@ _ACTION_HINTS = {
 }
 
 
-def _print_actions(actions: list, my_color: str | None = None):
+def _player_network(state: dict, color: str) -> set:
+    """Return the set of node ID strings that belong to a player's network."""
+    nodes = state.get("nodes", {})
+    network = set()
+    for nid, node in nodes.items():
+        if node.get("color") == color:
+            network.add(str(nid))
+    for e in state.get("edges", []):
+        if e.get("color") == color:
+            eid = e.get("id")
+            if isinstance(eid, list) and len(eid) == 2:
+                network.add(str(eid[0]))
+                network.add(str(eid[1]))
+    return network
+
+
+def _node_resource_label(state: dict, nid) -> str:
+    """Return a compact resource description for a node, e.g. 'SHRIMP(4), KELP(2)'."""
+    adj_tiles = state.get("adjacent_tiles", {})
+    tiles_info = adj_tiles.get(str(nid), [])
+    labels = []
+    for t in tiles_info:
+        res = t.get("resource")
+        num = t.get("number")
+        if res:
+            labels.append(f"{res}({num})" if num else res)
+    return ", ".join(labels)
+
+
+def _edge_annotation(edge_val, state: dict, color: str) -> str:
+    """Annotate a BUILD_CURRENT edge with network context and destination resources."""
+    if not isinstance(edge_val, list) or len(edge_val) != 2 or not state:
+        return ""
+
+    a_str, b_str = str(edge_val[0]), str(edge_val[1])
+    network = _player_network(state, color)
+    nodes = state.get("nodes", {})
+
+    a_mine = a_str in network
+    b_mine = b_str in network
+
+    if a_mine and b_mine:
+        return "  (connects your network)"
+
+    if a_mine:
+        from_id, to_id = a_str, b_str
+    elif b_mine:
+        from_id, to_id = b_str, a_str
+    else:
+        return ""
+
+    from_node = nodes.get(from_id, {})
+    building = from_node.get("building")
+    if building and from_node.get("color") == color:
+        tag = "your " + building.lower()
+    else:
+        tag = "your road"
+
+    to_label = _node_resource_label(state, to_id)
+    port_nodes = state.get("port_nodes", {})
+    port = None
+    for res_or_any, nids in port_nodes.items():
+        if int(to_id) in nids:
+            port = "3:1" if res_or_any == "ANY" else f"2:1 {res_or_any}"
+            break
+    if port and to_label:
+        return f"  from {from_id} ({tag}) → {to_id}: {to_label} [port {port}]"
+    if to_label:
+        return f"  from {from_id} ({tag}) → {to_id}: {to_label}"
+    return f"  from {from_id} ({tag}) → {to_id}"
+
+
+def _node_annotation(node_val, state: dict) -> str:
+    """Annotate a BUILD_TIDE_POOL node with resources and port info."""
+    if state is None:
+        return ""
+    nid = str(node_val)
+    label = _node_resource_label(state, nid)
+    port_nodes = state.get("port_nodes", {})
+    port = None
+    for res_or_any, nids in port_nodes.items():
+        if int(nid) in nids:
+            port = "3:1" if res_or_any == "ANY" else f"2:1 {res_or_any}"
+            break
+    parts = []
+    if label:
+        parts.append(label)
+    if port:
+        parts.append(f"port {port}")
+    if parts:
+        return "  " + ", ".join(parts)
+    return ""
+
+
+def _print_actions(actions: list, my_color: str | None = None, state: dict | None = None):
     _section("Available Actions")
 
     my_actions = []
@@ -365,12 +528,25 @@ def _print_actions(actions: list, my_color: str | None = None):
         val = a[2] if isinstance(a, list) and len(a) > 2 else None
         grouped[atype].append(val)
 
+    annotated_types = {"BUILD_CURRENT", "BUILD_TIDE_POOL", "BUILD_REEF"}
+
     for atype, values in grouped.items():
         hint = _ACTION_HINTS.get(atype)
         if all(v is None for v in values):
             print(f"  {atype}")
             if hint:
                 print(f"    ({hint})")
+        elif state and my_color and atype in annotated_types:
+            print(f"  {atype} ({len(values)} options):")
+            if hint:
+                print(f"    ({hint})")
+            for v in values:
+                f = json.dumps(v, separators=(",", ":"))
+                if atype == "BUILD_CURRENT":
+                    ann = _edge_annotation(v, state, my_color)
+                else:
+                    ann = _node_annotation(v, state)
+                print(f"    {f}{ann}")
         else:
             formatted = [json.dumps(v, separators=(",", ":")) for v in values]
             if hint:
@@ -426,6 +602,94 @@ def _print_history(records: list, since: int = 0):
             print(f"  {r}")
 
 
+def _format_live_action(color, action, val, state=None, pre_resources=None):
+    """Format a game action as a human-readable live update line."""
+    ts = time.strftime("%H:%M:%S")
+
+    if action == "ROLL_THE_SHELLS":
+        if isinstance(val, list) and len(val) == 2:
+            line = f"  [{ts}] {color} rolled {val[0]}+{val[1]}={sum(val)}"
+        elif val is not None:
+            line = f"  [{ts}] {color} rolled {val}"
+        else:
+            line = f"  [{ts}] {color} rolled the shells"
+        if pre_resources and state:
+            post = _all_player_resources(state)
+            parts = []
+            for c in state.get("colors", []):
+                gains = []
+                for res in RESOURCES:
+                    diff = post.get(c, {}).get(res, 0) - pre_resources.get(c, {}).get(res, 0)
+                    if diff > 0:
+                        gains.append(f"+{diff} {res}")
+                    elif diff < 0:
+                        gains.append(f"{diff} {res}")
+                if gains:
+                    parts.append(f"           {c}: {', '.join(gains)}")
+            if parts:
+                line += "\n" + "\n".join(parts)
+            else:
+                line += " — no resources produced"
+        return line
+
+    if action == "MOVE_THE_KRAKEN":
+        tile = val
+        victim = None
+        if isinstance(val, list) and len(val) >= 2:
+            tile = val[0]
+            victim = val[1]
+        if victim:
+            return f"  [{ts}] {color} moved the Kraken to {tile}, stealing from {victim}"
+        return f"  [{ts}] {color} moved the Kraken to {tile}"
+
+    if action == "BUILD_TIDE_POOL":
+        return f"  [{ts}] {color} built a settlement" + (f" on node {val}" if val is not None else "")
+
+    if action == "BUILD_REEF":
+        return f"  [{ts}] {color} upgraded to a city" + (f" on node {val}" if val is not None else "")
+
+    if action == "BUILD_CURRENT":
+        return f"  [{ts}] {color} built a road" + (f" on edge {val}" if val is not None else "")
+
+    if action == "BUY_TREASURE_MAP":
+        return f"  [{ts}] {color} bought a development card"
+
+    if action == "SUMMON_LOBSTER_GUARD":
+        return f"  [{ts}] {color} played a Knight"
+
+    if action == "RELEASE_CATCH":
+        return f"  [{ts}] {color} discarded resources"
+
+    if action == "PLAY_BOUNTIFUL_HARVEST":
+        if isinstance(val, list):
+            return f"  [{ts}] {color} played Year of Plenty: {', '.join(str(v) for v in val)}"
+        return f"  [{ts}] {color} played Year of Plenty"
+
+    if action == "PLAY_TIDAL_MONOPOLY":
+        return f"  [{ts}] {color} played Monopoly" + (f" on {val}" if val else "")
+
+    if action == "PLAY_CURRENT_BUILDING":
+        return f"  [{ts}] {color} played Road Building"
+
+    if action == "OCEAN_TRADE":
+        if isinstance(val, list) and len(val) >= 2:
+            giving = val[:-1]
+            receiving = val[-1]
+            give_counts = {}
+            for r in giving:
+                give_counts[r] = give_counts.get(r, 0) + 1
+            give_str = ", ".join(f"{n}x {r}" for r, n in give_counts.items())
+            return f"  [{ts}] {color} traded {give_str} for 1x {receiving}"
+        return f"  [{ts}] {color} made a trade"
+
+    if action == "END_TIDE":
+        return f"  [{ts}] {color} ended their turn"
+
+    if val is not None:
+        return f"  [{ts}] {color}: {action} {json.dumps(val, separators=(',', ':'))}"
+    return f"  [{ts}] {color}: {action}"
+
+
 def _count_turns(state: dict) -> int:
     """Count ROLL_THE_SHELLS records to get the turn number."""
     count = 0
@@ -493,24 +757,32 @@ def _print_join(resp: dict):
     print(f"  Started: {'yes' if resp.get('game_started') else 'no'}")
 
     _save_session(resp["game_id"], resp["token"], resp["player_color"])
-    print(f"\n  Session saved to {_session_path()}")
-    print(f"  All subsequent clawtan commands will use this session automatically.")
+    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
 
     # Snapshot current history/chat counts so we can show "what's new"
     history_len = 0
     chat_since = 0
+    pre_resources = None
     try:
         state = _get(f"/game/{game_id}")
         if state.get("started"):
             history_len = len(state.get("action_records", []))
+            pre_resources = _all_player_resources(state)
         chat_resp = _get(f"/game/{game_id}/chat")
         chat_since = len(chat_resp.get("messages", []))
     except (APIError, Exception):
@@ -518,6 +790,8 @@ def cmd_wait(args):
 
     # Poll loop
     phase_shown = None
+    prev_current = None
+    live_header_shown = False
     while True:
         try:
             status = _get(f"/game/{game_id}/status", token=token)
@@ -536,7 +810,6 @@ def cmd_wait(args):
             _header("GAME OVER")
             winner = status["winning_color"]
             print(f"  Winner: {winner}")
-            # Fetch final state for scores
             try:
                 state = _get(f"/game/{game_id}")
                 colors = state.get("colors", [])
@@ -558,10 +831,34 @@ def cmd_wait(args):
                 print(f"Waiting for players ({pj}/{np})...", file=sys.stderr)
                 phase_shown = "lobby"
         else:
-            if phase_shown != "turn":
-                cur = status.get("current_color", "?")
+            cur = status.get("current_color", "?")
+            if phase_shown != "turn" or cur != prev_current:
                 print(f"Waiting for your turn (current: {cur})...", file=sys.stderr)
                 phase_shown = "turn"
+                prev_current = cur
+
+            # Live action feed: detect and display new game actions
+            try:
+                live_state = _get(f"/game/{game_id}")
+                records = live_state.get("action_records", [])
+                new_count = len(records)
+                if new_count > history_len:
+                    if not live_header_shown:
+                        print("── Game Progress ──", file=sys.stderr)
+                        live_header_shown = True
+                    for r in records[history_len:new_count]:
+                        c, a, v = _unpack_record(r)
+                        if c and a:
+                            desc = _format_live_action(
+                                c, a, v,
+                                state=live_state,
+                                pre_resources=pre_resources,
+                            )
+                            print(desc, file=sys.stderr)
+                    history_len = new_count
+                    pre_resources = _all_player_resources(live_state)
+            except (APIError, Exception):
+                pass
 
         # Our turn!
         if status.get("your_turn"):
@@ -605,11 +902,11 @@ def cmd_wait(args):
 
     actions = state.get("current_playable_actions", [])
     if actions:
-        _print_actions(actions, my_color=color)
+        _print_actions(actions, my_color=color, state=state)
 
     robber = state.get("robber_coordinate")
     if robber:
-        print(f"\n  Robber: {robber}")
+        print(f"\n  Kraken: {robber}")
 
 
 def _print_roll_result(state: dict, pre_resources: dict | None):
@@ -652,9 +949,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
@@ -694,7 +992,7 @@ def cmd_act(args):
                 print(f"  Current turn: {current} | Prompt: {prompt}", file=sys.stderr)
                 actions = state.get("current_playable_actions", [])
                 if actions:
-                    _print_actions(actions, my_color=color)
+                    _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,
@@ -739,21 +1037,21 @@ def cmd_act(args):
             _print_resources(my["resources"])
 
         if my_actions:
-            _print_actions(actions, my_color=color)
+            _print_actions(actions, my_color=color, state=state)
         else:
             print("\n  No actions available.")
     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}")
-        _print_actions(actions, my_color=color)
+        _print_actions(actions, my_color=color, state=state)
     else:
         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)
 
@@ -777,7 +1075,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"):
@@ -902,19 +1201,36 @@ def cmd_board(args):
         for r in roads:
             print(f"  Edge {r['id']}: {r['color']}")
 
+    # Node adjacency graph for road planning
+    adjacency = defaultdict(list)
+    for e in state.get("edges", []):
+        eid = e.get("id")
+        if isinstance(eid, list) and len(eid) == 2:
+            a, b = str(eid[0]), str(eid[1])
+            adjacency[a].append(b)
+            adjacency[b].append(a)
+
+    if adjacency:
+        _section("Node Graph (edges)")
+        for nid in sorted(adjacency.keys(), key=lambda x: int(x)):
+            neighbors = sorted(adjacency[nid], key=lambda x: int(x))
+            print(f"  {nid}: {', '.join(neighbors)}")
+
     if robber:
-        print(f"\n  Robber: {robber}")
+        print(f"\n  Kraken: {robber}")
 
 
 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:
@@ -939,6 +1255,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 --------------------------------------------------------
@@ -1014,7 +1335,7 @@ def main():
             "  BUILD_CURRENT <edge>       Build road, e.g. '[3,7]'\n"
             "  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"
+            "  MOVE_THE_KRAKEN <val>      Move Kraken, e.g. '[[0,1,-1],\"BLUE\",null]'\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"
@@ -1058,7 +1379,7 @@ def main():
         help="Show board layout, buildings, and roads",
         description=(
             "Display the board: tiles with resources/numbers, ports,\n"
-            "buildings, roads, and robber location.\n"
+            "buildings, roads, and Kraken location.\n"
             "Tile layout is static after game start -- call once and remember it."
         ),
     )
@@ -1088,6 +1409,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.2.0",
+  "version": "0.2.2",
   "description": "CLI for AI agents playing Settlers of Clawtan -- a lobster-themed Catan board game",
   "bin": {
     "clawtan": "./bin/clawtan.js"