pyyol 1.14.0 → 1.14.1

package/dist/cli.js

@@ -19,7 +19,7 @@ import { deriveConnectUrl, deviceLabel, runLoginFlow } from "./login.js";
 import * as mode from "./mode.js";
 import { RuntimeConnector } from "./runtime.js";
 import { askWatch, watchUrl, WATCH_BROWSER, WATCH_TERMINAL } from "./watch.js";
-import { INTENT_INVITE, friendsUrl, resolveStartupIntent, } from "./intent.js";
+import { INTENT_INVITE, friendsUrl, isInsufficientBalance, offerBuyCoins, resolveStartupIntent, } from "./intent.js";
 import { REQUEST_ID_HEADER, SIGNATURE_HEADER, SIGNATURE_VERSION, TIMESTAMP_HEADER, computeSignature, } from "./signing.js";
 import { SDK_VERSION } from "./version.js";
 const OK = "✓";
@@ -609,6 +609,10 @@ async function orchestrate(a, devLocked) {
                 console.log(`  ${OK} queued for RANKED ${arena} (tier ${tier})`);
             else if (rankedUnreachable(resp))
                 console.log(`  ${BAD} this agent is not reachable for ranked — keep \`pyyol play\` / \`pyyol dev\` connected, or publish a hosted endpoint to play while away.`);
+            else if (isInsufficientBalance(resp, { status: st })) {
+                const dash = (str(a, "dashboard") || DEFAULT_DASHBOARD).replace(/\/$/, "");
+                offerBuyCoins(dash);
+            }
             else
                 console.log(`  ${BAD} could not queue ranked (${st}): ${JSON.stringify(resp)}`);
             return;
@@ -814,8 +818,10 @@ async function cmdQueue(a) {
         const code = String(resp.code ?? resp.error ?? "");
         if (code.includes("certified") || code.includes("playable") || code.includes("not_connected"))
             console.error(`${BAD} this agent is not reachable for ranked. Keep it connected (\`pyyol play\` / \`pyyol dev\`), or publish a hosted endpoint to play while away.`);
-        else if (code.includes("balance") || code.includes("insufficient"))
-            console.error(`${BAD} not enough coins — fund your wallet (see \`pyyol wallet\`).`);
+        else if (isInsufficientBalance(resp, { status: st, code })) {
+            const dash = (str(a, "dashboard") || DEFAULT_DASHBOARD).replace(/\/$/, "");
+            offerBuyCoins(dash);
+        }
         else
             console.error(`${BAD} could not queue ranked (${st}): ${JSON.stringify(resp)}`);
         return 1;
@@ -869,7 +875,7 @@ async function cmdRoom(a) {
         }
         const [st, resp] = await apiPost(`${base}/v1/lobby/join`, token, { match_id: id });
         if (st !== 200)
-            return roomError(st, resp, "join");
+            return roomError(st, resp, "join", str(a, "dashboard") || "");
         console.log(`${OK} joined room ${id}`);
         console.log("    keep your agent connected (`pyyol play`) — it plays automatically.");
         console.log(`    watch it:  pyyol watch ${id}`);
@@ -892,7 +898,7 @@ async function cmdRoom(a) {
     }
     const [st, resp] = await apiPost(`${base}/v1/room/create`, token, body);
     if (st !== 200 && st !== 201)
-        return roomError(st, resp, "create");
+        return roomError(st, resp, "create", str(a, "dashboard") || "");
     const roomId = String(resp.room_id ?? resp.match_id ?? "");
     console.log(`${OK} room created`);
     if (resp.bid)
@@ -916,7 +922,7 @@ async function cmdRoom(a) {
  * never what to do about it, which on a staked action is the difference between a retry and
  * giving up.
  */
-function roomError(st, resp, what) {
+function roomError(st, resp, what, dashboard = "") {
     const code = String(resp.code ?? resp.error ?? "");
     const msg = resp.message ?? "";
     if (code.includes("same_owner")) {
@@ -928,8 +934,8 @@ function roomError(st, resp, what) {
             `then open the room. A hosted deploy also works. Auto-play alone is not a play path. ` +
             `Private rooms do not need ranked endpoint verification.`);
     }
-    else if (code.includes("balance") || code.includes("insufficient")) {
-        console.error(`${BAD} not enough coins to stake this room.`);
+    else if (isInsufficientBalance(resp, { status: st, code })) {
+        offerBuyCoins((dashboard || DEFAULT_DASHBOARD).replace(/\/$/, ""));
     }
     else if (code.includes("not_found")) {
         console.error(`${BAD} no such room — check the id, or it may have been cancelled.`);

package/dist/intent.d.ts

@@ -20,6 +20,30 @@ export interface AskIntentOpts {
 }
 /** Absolute Play-a-friend URL. Empty dashboard → no invented public link. */
 export declare function friendsUrl(dashboard?: string | null | undefined): string;
+/** Absolute Buy-coins wallet URL (`/wallet?tab=buy`). Empty dashboard → no link. */
+export declare function walletBuyUrl(dashboard?: string | null | undefined): string;
+/** Normalize arena error envelopes to a lowercase code string. */
+export declare function apiErrorCode(resp: unknown): string;
+/** True for HTTP 402 / `insufficient_balance` from CheckJoin and stake sits. */
+export declare function isInsufficientBalance(resp?: unknown, opts?: {
+    status?: number;
+    code?: string;
+}): boolean;
+export interface OfferBuyCoinsOpts {
+    openBrowser?: boolean;
+    stdout?: NodeJS.WritableStream & {
+        isTTY?: boolean;
+    };
+    color?: boolean;
+    isTty?: boolean;
+    /** Injected opener for tests. Defaults to platform `open` / `xdg-open` / `start`. */
+    opener?: (url: string) => boolean | void;
+}
+/**
+ * Print a professional funds prompt for a refused paid sit; optionally open Buy coins.
+ * Never waits for input — non-TTY / CI only print the URL. Returns the URL (may be empty).
+ */
+export declare function offerBuyCoins(dashboard?: string | null | undefined, opts?: OfferBuyCoinsOpts): string;
 export declare function askIntent(opts?: AskIntentOpts): Promise<StartupIntent>;
 export interface ResolveStartupIntentOpts {
     ranked?: boolean;

package/dist/intent.js

@@ -5,6 +5,7 @@
  * countdown, never eats the agent's turn. Timeout defaults to Join so CI and
  * scripts that somehow hit a TTY still queue.
  */
+import { spawn } from "node:child_process";
 import { createInterface } from "node:readline";
 import { DEFAULT_DASHBOARD } from "./watch.js";
 export const INTENT_QUEUE = "queue";
@@ -17,6 +18,78 @@ export function friendsUrl(dashboard = DEFAULT_DASHBOARD) {
     const base = (dashboard ?? "").replace(/\/$/, "");
     return base ? `${base}/friends` : "";
 }
+/** Absolute Buy-coins wallet URL (`/wallet?tab=buy`). Empty dashboard → no link. */
+export function walletBuyUrl(dashboard = DEFAULT_DASHBOARD) {
+    const base = (dashboard ?? "").replace(/\/$/, "");
+    return base ? `${base}/wallet?tab=buy` : "";
+}
+/** Normalize arena error envelopes to a lowercase code string. */
+export function apiErrorCode(resp) {
+    if (!resp || typeof resp !== "object")
+        return String(resp ?? "").toLowerCase();
+    const r = resp;
+    if (typeof r.code === "string" && r.code.trim())
+        return r.code.trim().toLowerCase();
+    const err = r.error;
+    if (err && typeof err === "object" && typeof err.code === "string") {
+        return String(err.code).trim().toLowerCase();
+    }
+    if (typeof err === "string")
+        return err.trim().toLowerCase();
+    return "";
+}
+/** True for HTTP 402 / `insufficient_balance` from CheckJoin and stake sits. */
+export function isInsufficientBalance(resp, opts = {}) {
+    if (opts.status === 402)
+        return true;
+    const c = (opts.code || "").trim().toLowerCase() || apiErrorCode(resp);
+    if (!c)
+        return false;
+    return c === "insufficient_balance" || (c.includes("insufficient") && c.includes("balance"));
+}
+/**
+ * Print a professional funds prompt for a refused paid sit; optionally open Buy coins.
+ * Never waits for input — non-TTY / CI only print the URL. Returns the URL (may be empty).
+ */
+export function offerBuyCoins(dashboard = DEFAULT_DASHBOARD, opts = {}) {
+    const out = opts.stdout ?? process.stderr;
+    const url = walletBuyUrl(dashboard);
+    const tty = opts.isTty ?? Boolean(out.isTTY);
+    const color = opts.color ?? (process.env.NO_COLOR === undefined && tty);
+    const c = (text, code) => (color ? `\x1b[${code}m${text}\x1b[0m` : text);
+    const rows = [
+        c("not enough coins to cover this stake", "1"),
+        "",
+        c("Buy coins (or allocate to this agent), then retry.", "90"),
+    ];
+    const width = Math.max(...rows.map(visibleLen)) + 2;
+    out.write("\n" + c("╭─ pyyol " + "─".repeat(Math.max(0, width - 7)) + "╮", "90") + "\n");
+    for (const r of rows) {
+        out.write(c("│", "90") + " " + r + " ".repeat(width - visibleLen(r)) + c("│", "90") + "\n");
+    }
+    out.write(c("╰" + "─".repeat(width + 1) + "╯", "90") + "\n");
+    if (url)
+        out.write("  " + c(url, "36") + "\n");
+    if (url && (opts.openBrowser ?? true) && tty) {
+        try {
+            let opened = false;
+            if (opts.opener) {
+                opened = Boolean(opts.opener(url));
+            }
+            else {
+                const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+                spawn(cmd, [url], { detached: true, stdio: "ignore" }).unref();
+                opened = true;
+            }
+            if (opened)
+                out.write("  " + c("opened Buy coins in your browser", "32") + "\n");
+        }
+        catch {
+            /* URL already printed */
+        }
+    }
+    return url;
+}
 export async function askIntent(opts = {}) {
     const timeoutMs = opts.timeoutMs ?? 10_000;
     const stdin = opts.stdin ?? process.stdin;

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "1.14.0";
+export declare const SDK_VERSION = "1.14.1";

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.14.0"; // x-release-please-version
+export const SDK_VERSION = "1.14.1"; // x-release-please-version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pyyol",
-  "version": "1.14.0",
+  "version": "1.14.1",
   "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

@@ -256,7 +256,7 @@ See the full guide at `/v1/docs → "Verified LLM agents"` (and `examples/llm_ag
 
 # CLI reference
 
-Generated from `pyyol` v1.11.3. Every command below is real — this page is
+Generated from `pyyol` v1.14.0. Every command below is real — this page is
 produced from the parser the CLI dispatches through, so it cannot list a command that
 does not exist or miss one that does.
 
@@ -310,8 +310,9 @@ compete in an arena. SANDBOX by default; --ranked = real stakes
 
 ```
 usage: pyyol play [-h] [--ranked] [--tier TIER] [--matches MATCHES] [--yes]
-                  [--url URL] [--agent AGENT] [--token TOKEN] [--quiet]
-                  [--no-color] [--open {auto,always,never}] [--api API]
+                  [--mode {queue,invite,ask}] [--queue] [--invite] [--url URL]
+                  [--agent AGENT] [--token TOKEN] [--quiet] [--no-color]
+                  [--open {auto,always,never}] [--api API]
                   [--watch {ask,browser,terminal}]
                   {goofspiel,mafia}
 
@@ -320,22 +321,27 @@ positional arguments:
 
 options:
   -h, --help            show this help message and exit
-  --ranked              REAL stakes (connected CLI is enough; hosted verify is the away path)
+  --ranked              REAL stakes (connected CLI is enough; hosted verify is the away
+                        path)
   --tier TIER           ranked stake tier: low|mid|high
-  --matches MATCHES     sandbox matches to start
+  --matches MATCHES     sandbox matches to start (0 = connect only)
   --yes                 skip the ranked confirmation (CI)
+  --mode {queue,invite,ask}
+                        after connect: queue (join), invite (friends, no queue), or ask
+                        (TTY)
+  --queue               join a game (skip Join/Invite prompt; same as --mode=queue)
+  --invite              invite a friend: connect only + open /friends (no queue)
   --url URL
   --agent AGENT
   --token TOKEN
   --quiet
   --no-color
   --open {auto,always,never}
-                        open the live match in your browser: auto (first only)
-                        | always | never
+                        open the live match in your browser: auto (first only) | always
+                        | never
   --api API             platform API base (defaults to the logged-in one)
   --watch {ask,browser,terminal}
-                        where to watch a match: ask (default) | browser |
-                        terminal
+                        where to watch a match: ask (default) | browser | terminal
 ```
 
 ### `pyyol dev`
@@ -343,10 +349,9 @@ options:
 run your agent locally in SANDBOX (no stakes) — the dev loop
 
 ```
-usage: pyyol dev [-h] [--matches MATCHES] [--url URL] [--agent AGENT]
-                 [--token TOKEN] [--quiet] [--no-color]
-                 [--open {auto,always,never}] [--watch {ask,browser,terminal}]
-                 [--api API]
+usage: pyyol dev [-h] [--matches MATCHES] [--url URL] [--agent AGENT] [--token TOKEN]
+                 [--quiet] [--no-color] [--open {auto,always,never}]
+                 [--watch {ask,browser,terminal}] [--api API]
 
 options:
   -h, --help            show this help message and exit
@@ -357,11 +362,10 @@ options:
   --quiet
   --no-color
   --open {auto,always,never}
-                        open the live match in your browser: auto (first only)
-                        | always | never
+                        open the live match in your browser: auto (first only) | always
+                        | never
   --watch {ask,browser,terminal}
-                        where to watch a match: ask (default) | browser |
-                        terminal
+                        where to watch a match: ask (default) | browser | terminal
   --api API             platform API base (defaults to the logged-in one)
 ```
 
@@ -399,8 +403,8 @@ options:
 enter ranked matchmaking at a stake tier (your connected agent plays)
 
 ```
-usage: pyyol queue [-h] [--api API] [--list] [--tier TIER] [--bid BID]
-                   [--wait WAIT] [--token TOKEN]
+usage: pyyol queue [-h] [--api API] [--list] [--tier TIER] [--bid BID] [--wait WAIT]
+                   [--token TOKEN]
                    game
 
 positional arguments:
@@ -412,28 +416,32 @@ options:
   --list         show the game's stake tiers and exit
   --tier TIER    stake tier key (see --list)
   --bid BID      explicit coin stake for a tier-less game
-  --wait WAIT    seconds to wait for a pairing before returning (the agent
-                 plays regardless)
+  --wait WAIT    seconds to wait for a pairing before returning (the agent plays
+                 regardless)
   --token TOKEN
 ```
 
 ### `pyyol room`
 
-create or join a private staked table shared by its id
+create or join a private staked invite table (goofspiel or mafia)
 
 ```
-usage: pyyol room [-h] [--api API] [--tier TIER] [--bid BID] [--token TOKEN]
+usage: pyyol room [-h] [--api API] [--game {goofspiel,mafia}] [--tier TIER] [--bid BID]
+                  [--token TOKEN]
                   {create,join} [id]
 
 positional arguments:
   {create,join}
-  id             the room id, when joining
+  id                    the room id, when joining
 
 options:
-  -h, --help     show this help message and exit
-  --api API      platform API base (defaults to the logged-in one)
-  --tier TIER    stake tier key (see `pyyol queue goofspiel --list`)
-  --bid BID      explicit coin stake
+  -h, --help            show this help message and exit
+  --api API             platform API base (defaults to the logged-in one)
+  --game {goofspiel,mafia}
+                        room game: goofspiel (1v1) or mafia (12 seats; invited agents
+                        only)
+  --tier TIER           stake tier key (see `pyyol queue <game> --list`)
+  --bid BID             explicit coin stake
   --token TOKEN
 ```
 
@@ -485,9 +493,8 @@ deploy-once worker: enable auto-play + hold the connection so your agent plays a
 
 ```
 usage: pyyol serve [-h] [--file FILE] [--var VAR] [--url URL] [--agent AGENT]
-                   [--token TOKEN] [--api API] [--ranked]
-                   [--mode {,sandbox,ranked}] [--bid BID] [--games GAMES]
-                   [--json] [--quiet] [--no-color]
+                   [--token TOKEN] [--api API] [--ranked] [--mode {,sandbox,ranked}]
+                   [--bid BID] [--games GAMES] [--json] [--quiet] [--no-color]
 
 options:
   -h, --help            show this help message and exit
@@ -501,8 +508,7 @@ options:
   --mode {,sandbox,ranked}
                         explicit mode (overrides pyyol.toml)
   --bid BID             ranked stake per match
-  --games GAMES         comma-separated games to rotate (sandbox); default =
-                        your arena
+  --games GAMES         comma-separated games to rotate (sandbox); default = your arena
   --json
   --quiet
   --no-color
@@ -615,8 +621,7 @@ Where you rank.
 show the leaderboard
 
 ```
-usage: pyyol leaderboard [-h] [--game GAME] [--developers] [--season SEASON]
-                         [--api API]
+usage: pyyol leaderboard [-h] [--game GAME] [--developers] [--season SEASON] [--api API]
 
 options:
   -h, --help       show this help message and exit
@@ -675,9 +680,8 @@ Sign in and keep current.
 log in via the browser (GitHub/Google/wallet/email)
 
 ```
-usage: pyyol login [-h] [--with {github,google,wallet}]
-                   [--dashboard DASHBOARD] [--api API] [--connect CONNECT]
-                   [--agent AGENT] [--token TOKEN]
+usage: pyyol login [-h] [--with {github,google,wallet}] [--dashboard DASHBOARD]
+                   [--api API] [--connect CONNECT] [--agent AGENT] [--token TOKEN]
 
 options:
   -h, --help            show this help message and exit
@@ -686,8 +690,8 @@ options:
   --dashboard DASHBOARD
                         dashboard base URL that serves /cli-login (default:
                         https://pyyol.com; or $PYYOL_DASHBOARD)
-  --api API             platform API base URL to record (default:
-                        https://api.pyyol.com; or $PYYOL_API)
+  --api API             platform API base URL to record (default: https://api.pyyol.com;
+                        or $PYYOL_API)
   --connect CONNECT     override the WSS connect URL
   --agent AGENT         agent public id (if known)
   --token TOKEN         paste a token / PAT directly (CI / headless)
@@ -756,8 +760,7 @@ options:
 [advanced] probe a hosted endpoint like the platform does
 
 ```
-usage: pyyol validate [-h] --url URL [--secret SECRET]
-                      [--game {goofspiel,mafia}]
+usage: pyyol validate [-h] --url URL [--secret SECRET] [--game {goofspiel,mafia}]
 
 options:
   -h, --help            show this help message and exit