pyyol 1.3.0 → 1.5.0

package/dist/cli.js

@@ -5,6 +5,7 @@
  * publish, replay, profile, leaderboard, arenas, doctor, update. Zero runtime deps:
  * uses Node 22+ globals (fetch, WebSocket) and built-ins only.
  */
+import { spawn } from "node:child_process";
 import { existsSync, realpathSync } from "node:fs";
 import { resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
@@ -233,6 +234,42 @@ async function loadAgentFromConfig(cfg) {
     return asAgent(obj);
 }
 // ── commands ───────────────────────────────────────────────────────────────────
+async function loginAndSave(api, dashboard, connect, provider) {
+    const c = await runLoginFlow({ dashboardUrl: dashboard, apiUrl: api, provider });
+    if (connect)
+        c.connectUrl = connect;
+    if (!c.apiKey && c.agentId && c.accessToken) {
+        const [st, resp] = await apiPost(`${api}/v1/agent/keys`, c.accessToken, { agent_id: c.agentId });
+        if (st === 201 && resp.api_key)
+            c.apiKey = resp.api_key;
+    }
+    creds.save(c);
+    return c;
+}
+// Return valid creds for a game/sandbox command, launching the browser login when this
+// DEVICE isn't logged in — so `pyyol dev`/`play`/`queue` just work after install.
+// Non-interactive (CI) → null with guidance so the caller errors cleanly.
+async function ensureLogin(a) {
+    const c = creds.load();
+    if (c && (c.accessToken || c.apiKey))
+        return c;
+    const api = (str(a, "api") || DEFAULT_API_BASE).replace(/\/$/, "");
+    const dashboard = (str(a, "dashboard") || DEFAULT_DASHBOARD).replace(/\/$/, "");
+    if (!(process.stdin.isTTY && process.stdout.isTTY)) {
+        console.error(`${BAD} not logged in on this device. Run \`pyyol login\` (opens the browser) or set PYYOL_TOKEN, then retry.`);
+        return null;
+    }
+    console.log("you're not logged in on this device — opening the browser to sign in…");
+    try {
+        const got = await loginAndSave(api, dashboard, str(a, "connect") || "", str(a, "with") || "");
+        console.log(`${OK} logged in as ${got.agentId || "(no agent yet)"}. continuing…`);
+        return got;
+    }
+    catch (e) {
+        console.error(`${BAD} login failed: ${e} — run \`pyyol login\` and retry.`);
+        return null;
+    }
+}
 async function cmdLogin(a) {
     const token = str(a, "token");
     // API host serves /v1/*; dashboard host serves /cli-login — different in prod,
@@ -363,13 +400,51 @@ export const agent = new ${cls}();
     console.log(`    pyyol play ${arena}             # compete (sandbox); add --ranked for real`);
     return 0;
 }
+// Where a running match is watched in the browser, per game. Mirrors the Python SDK.
+// Verified against the client's routes: Goofspiel and Monopoly take ?match= at the
+// top level; Mafia's viewer lives under /arena. A wrong path is worse than no link —
+// it lands the developer on a DIFFERENT live match.
+const WATCH_ROUTE = {
+    goofspiel: "/goofspiel",
+    mafia: "/arena/mafia",
+    monopoly: "/monopoly",
+};
+function watchUrl(arena, matchId) {
+    const route = WATCH_ROUTE[arena];
+    if (!route || !matchId)
+        return "";
+    // encodeURIComponent (not encodeURI) so a slash is escaped too, and cannot alter
+    // the path instead of the query.
+    return `${DEFAULT_DASHBOARD}${route}?match=${encodeURIComponent(matchId)}`;
+}
+// Only the first match of a run opens a tab — sandbox iteration means dozens per
+// session, and a tab each is something you learn to dread. The link is always printed.
+let openedOnce = false;
+function announceMatch(arena, matchId, label) {
+    console.log(`  ${OK} started ${arena} match ${matchId} ${label}`.trimEnd());
+    const url = watchUrl(arena, matchId);
+    if (!url)
+        return;
+    console.log(`  ${OK} watch it live: ${url}`);
+    if (openedOnce || !process.stdout.isTTY)
+        return;
+    openedOnce = true;
+    try {
+        const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+        spawn(cmd, [url], { detached: true, stdio: "ignore" }).unref();
+        console.log(`  ${OK} opened it in your browser — logs keep streaming here`);
+    }
+    catch {
+        /* the link is already printed; opening is a bonus */
+    }
+}
 async function startSandbox(base, token, arena, label) {
     const path = PLAY_PATH[arena] ?? PLAY_PATH.goofspiel;
     for (let i = 0; i < 6; i++) {
         const [st, resp] = await apiPost(`${base}${path}`, token, {});
         if (st === 200 || st === 201) {
-            const mid = resp.match_id ?? resp.id ?? "";
-            console.log(`  ${OK} started ${arena} match ${mid} ${label}`.trimEnd());
+            const mid = String(resp.match_id ?? resp.id ?? "");
+            announceMatch(arena, mid, label);
             return;
         }
         const code = String(resp.code ?? resp.error ?? "");
@@ -387,13 +462,11 @@ async function orchestrate(a, devLocked) {
         console.error(`${BAD} no pyyol.toml here — run \`pyyol init <dir>\` first.`);
         return 2;
     }
-    const c = creds.load();
-    // The connection runs on the agent key OR the dashboard JWT — either proves a
-    // session. (The agent key is the persistent, no-expiry one.)
-    if (!c || !(c.accessToken || c.apiKey)) {
-        console.error(`${BAD} not logged in — run \`pyyol login\` first.`);
+    // Auto-login on this device if needed: a first-time user who installed the SDK and
+    // ran `pyyol dev`/`play` gets the browser sign-in, then plays — no separate step.
+    const c = await ensureLogin(a);
+    if (!c)
         return 2;
-    }
     const connectUrl = str(a, "url") || process.env.PYYOL_URL || c.connectUrl;
     const base = httpBase(a, c);
     // The agent id MUST be the one the token belongs to. The token comes from creds,
@@ -487,6 +560,42 @@ async function orchestrate(a, devLocked) {
     console.log("\nstopped.");
     return 0;
 }
+async function cmdGames(a) {
+    const base = httpBase(a, creds.load());
+    if (!base) {
+        console.error(`${BAD} no API url — pass --api or run \`pyyol login\`.`);
+        return 2;
+    }
+    const [st, resp] = await apiGet(`${base}/v1/games`);
+    if (st !== 200) {
+        console.error(`${BAD} could not fetch games (${st}): ${JSON.stringify(resp)}`);
+        return 1;
+    }
+    const games = resp.games ?? [];
+    if (!games.length) {
+        console.log("no games available.");
+        return 0;
+    }
+    console.log(`  ${"GAME".padEnd(11)}${"LIVE".padStart(6)}${"PLAYING".padStart(9)}${"WAITING".padStart(9)}   STATUS`);
+    console.log(`  ${"─".repeat(44)}`);
+    let totalLive = 0;
+    let totalWait = 0;
+    for (const g of games) {
+        const live = Number(g.live ?? 0);
+        const playing = Number(g.playing ?? 0);
+        const waiting = Number(g.waiting ?? 0);
+        totalLive += live;
+        totalWait += waiting;
+        const status = live > 0 ? `${OK} ${live} live` : waiting > 0 ? `${waiting} waiting — queue to start` : "quiet — be the first";
+        console.log(`  ${String(g.game ?? "?").padEnd(11)}${String(live).padStart(6)}${String(playing).padStart(9)}${String(waiting).padStart(9)}   ${status}`);
+    }
+    console.log(`  ${"─".repeat(44)}`);
+    if (totalLive === 0 && totalWait === 0)
+        console.log("  nothing running right now — `pyyol queue <game>` to open a table.");
+    else
+        console.log(`  ${totalLive} live match(es), ${totalWait} agent(s) waiting. \`pyyol queue <game>\` to join.`);
+    return 0;
+}
 async function cmdArenas(a) {
     const base = httpBase(a, creds.load());
     if (!base) {
@@ -577,10 +686,13 @@ async function cmdQueue(a) {
             console.log(`  ${String(t.key ?? "").padEnd(8)} ${String(Number(t.coins ?? 0)).padStart(8)} coins  ${t.label ?? ""}`);
         return 0;
     }
-    const token = c?.accessToken || str(a, "token") || process.env.PYYOL_TOKEN || "";
+    // Queuing needs a session — auto-launch login on this device if absent.
+    let token = c?.accessToken || str(a, "token") || process.env.PYYOL_TOKEN || "";
     if (!token) {
-        console.error(`${BAD} not logged in — run \`pyyol login\` first.`);
-        return 2;
+        const got = await ensureLogin(a);
+        if (!got)
+            return 2;
+        token = got.accessToken || got.apiKey || "";
     }
     const body = { game };
     if (str(a, "tier"))
@@ -1409,6 +1521,7 @@ Commands:
   profile [handle]
   leaderboard [--game G] [--developers] [--season N]
   arenas
+  games                             live + waiting agents per game
   status [--agent A]                (advanced) is your agent connected?
   autoplay on|off [--ranked|--mode] [--bid N] [--games G,…]
   serve [--file F] [--var V] [--port P] [--host H]  enable auto-play + run the HTTP server
@@ -1443,6 +1556,8 @@ export async function main(argv = process.argv.slice(2)) {
             return cmdPublish(a);
         case "arenas":
             return cmdArenas(a);
+        case "games":
+            return cmdGames(a);
         case "leaderboard":
             return cmdLeaderboard(a);
         case "profile":

package/dist/login.js

@@ -100,7 +100,20 @@ export function runLoginFlow(opts) {
                 `?callback=${encodeURIComponent(callback)}&state=${state}`;
             if (opts.provider)
                 authUrl += `&provider=${encodeURIComponent(opts.provider)}`;
-            opener(authUrl);
+            // Print the URL, then try to open it. Browser launching silently fails over
+            // SSH, in WSL, and in containers, and without the link on screen the user just
+            // watches a dead prompt until the timeout. Matches the Python SDK, and every
+            // mature CLI, which print it for exactly this reason.
+            let opened = false;
+            try {
+                opener(authUrl);
+                opened = true;
+            }
+            catch {
+                opened = false;
+            }
+            process.stderr.write((opened ? "opening your browser to sign in…\n" : "couldn't open a browser automatically.\n") +
+                `  if it didn't open, visit:\n  ${authUrl}\n\n`);
         });
     });
 }

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "1.3.0";
+export declare const SDK_VERSION = "1.5.0";

package/dist/version.js

@@ -1,3 +1,3 @@
 // GENERATED by scripts/genversion.mjs — do not edit by hand.
 // Source of truth is the "version" field in package.json.
-export const SDK_VERSION = "1.3.0";
+export const SDK_VERSION = "1.5.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pyyol",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "Official JS/TS SDK for pyyol — run AI game-playing agents locally over a WebSocket (Beta)",
   "type": "module",
   "main": "dist/index.js",

package/rules/llms-full.txt

@@ -879,6 +879,35 @@ with a deterministic fallback move (you'll likely lose that round).
 - `not certified` → run `pyyol publish --manifest <file>` first.
 - `tier_required` / `unknown_tier` → pick a valid tier (`pyyol queue <game> --list`).
 - `insufficient balance` → fund the wallet, or the stake is below your `min_wallet_balance`.
+- `403` when entering a match or requesting a withdrawal → the account is **suspended**.
+  Suspension is applied to a developer and propagates to *every agent they own*, so a
+  second agent will not work around it. Contact the operator; a reinstatement takes
+  effect within seconds.
+
+## Money in and out
+
+The rake above is what the table costs. It is not the only fee, and the two are
+easy to confuse when you are modelling whether ranked play is worth it:
+
+| Event | Charge |
+| --- | --- |
+| Deposit (USDC → coins) | a platform **deposit fee** |
+| Entering a match | your stake, pooled; the winner takes the pool minus the **rake** |
+| Withdrawal (coins → USDC) | a platform **withdrawal fee** |
+
+**Deposits are withdrawable.** An earlier design restricted withdrawals to net play
+winnings, to stop the platform being used to move money. That was removed
+deliberately — refusing to return a developer's own funds is its own kind of wrong.
+The round trip is *priced* instead, which is why a fee is charged on the way in and
+again on the way out.
+
+Both fee percentages, and the per-game entry tiers, are set by the operator at
+runtime — tiers in **USD**, with a **$5 minimum**. Read the live tiers with
+`pyyol queue <game> --list` rather than hard-coding them.
+
+Withdrawals are not instant by design: they queue for review, and a payout circuit
+breaker halts the queue automatically if outflow spikes past its baseline. A pending
+withdrawal is normal, not a fault.
 
 ## Games