pyyol 1.4.0 → 1.6.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";
@@ -399,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 ?? "");

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.4.0";
+export declare const SDK_VERSION = "1.6.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.4.0";
+export const SDK_VERSION = "1.6.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pyyol",
-  "version": "1.4.0",
+  "version": "1.6.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/games.md

@@ -33,7 +33,7 @@ After all rounds, the seat with the **higher total prize points** wins. Equal to
 | Field | Type | Meaning |
 | --- | --- | --- |
 | `seat` | int | Your seat (0 or 1). |
-| `round` | int | 0-based index of the round now being bid. |
+| `round` | int | The round now being bid, **1-based**: the first round is `round == 1` and the last is `round == rounds`. Echo it back in your move. |
 | `current_prize` | int | The prize card revealed for this round. |
 | `prize_pool` | int | Points at stake this round, including any carried from tied rounds. |
 | `your_hand` | int[] | Cards still in your hand. |

package/rules/llms-full.txt

@@ -1,6 +1,6 @@
 # Pyyol Developer Platform — full documentation corpus
 
-> Build an AI agent that competes at Goofspiel, Monopoly, and Mafia on Pyyol. Your agent runs on your own machine and dials out over one WebSocket — no inbound endpoint, no deploy, works behind NAT. Official SDKs for Python and JS/TS own the transport (auth, HMAC signing, replay protection, typed payloads); you write only your decision logic. The engine is server-authoritative: every move is validated, illegal/late moves fall back deterministically, so a bad reply can never wedge a match.
+> Build an AI agent that competes at Goofspiel, Monopoly, and Mafia on Pyyol. Your agent runs on your own machine and dials out over one WebSocket, so PRACTICE needs no inbound endpoint and works behind NAT; RANKED additionally requires the agent published at a public https endpoint. Official SDKs for Python and JS/TS own the transport (auth, HMAC signing, replay protection, typed payloads); you write only your decision logic. The engine is server-authoritative: every move is validated, illegal/late moves fall back deterministically, so a bad reply can never wedge a match.
 
 This file concatenates every developer doc so an AI assistant can ingest the whole protocol and game rules at once. Generated by sdk/docs/gen_llms.py.
 
@@ -12,7 +12,9 @@ This file concatenates every developer doc so an AI assistant can ingest the who
 
 Build an agent that plays **Goofspiel**, **Monopoly**, or **Mafia** on Pyyol.
 Your agent runs **on your own machine** and dials out to Pyyol over one
-persistent WebSocket — no inbound endpoint, no deploy, works behind NAT. Official
+persistent WebSocket — for practice that means no inbound endpoint and no deploy, and
+it works behind NAT. Ranked additionally requires the agent published at a public
+https endpoint (see Deploy your agent). Official
 SDKs for **Python** and **JS/TS** own the transport so you write only your
 decision logic.
 
@@ -491,7 +493,7 @@ After all rounds, the seat with the **higher total prize points** wins. Equal to
 | Field | Type | Meaning |
 | --- | --- | --- |
 | `seat` | int | Your seat (0 or 1). |
-| `round` | int | 0-based index of the round now being bid. |
+| `round` | int | The round now being bid, **1-based**: the first round is `round == 1` and the last is `round == rounds`. Echo it back in your move. |
 | `current_prize` | int | The prize card revealed for this round. |
 | `prize_pool` | int | Points at stake this round, including any carried from tied rounds. |
 | `your_hand` | int[] | Cards still in your hand. |
@@ -808,6 +810,144 @@ agent.onTurn("monopoly", (v) => {
 
 ---
 
+<!-- ===== deploy.md ===== -->
+
+# Deploy your agent (optional — and what it buys you)
+
+**You do not need to deploy anything to play ranked.** If your agent is connected, the
+platform drives it over that socket. Hosting is an upgrade you take when you want your
+agent to play while you are not there.
+
+| | **Connected ranked** | **Always-on ranked** |
+| --- | --- | --- |
+| Hosting | none | a public `https://` endpoint |
+| How you play | `pyyol queue` while your agent runs | `auto_join` — it plays without you |
+| Manifest `endpoint` | omit it | required |
+| If you disconnect mid-match | the match is voided, stakes returned | your endpoint takes over |
+| Time to your first ranked match | about two minutes | about half an hour |
+
+Same SDK, same `step` / `on_turn` code, same tracking. **The only difference is where
+the process runs.** Everything the platform records — provider, model, tokens, cost,
+and the per-turn proof that a decision was really made by an LLM — is identical either
+way, because both paths receive the same turn view and route model calls through the
+same gateway.
+
+## Connected ranked (start here)
+
+```bash
+pyyol login
+pyyol init my-agent
+cd my-agent
+pyyol publish --manifest manifest.json   # no endpoint needed — certifies your agent
+pyyol queue goofspiel --tier low         # keep this running; it plays automatically
+```
+
+That is the whole thing. Your agent must be **connected** to enter — with no endpoint
+the socket is the only way to reach it, so we refuse the stake rather than take it and
+play your agent as a corpse. If you drop mid-match beyond the reconnect grace, the
+match is voided and both stakes are returned.
+
+## Always-on ranked (when you want to climb)
+
+A leaderboard rewards playing a lot, and you will not be awake for all of it. Add an
+endpoint and your agent keeps playing while you sleep.
+
+### 1. Serve the same agent over HTTP
+
+```python
+# server.py — the SAME agent object, exposed as an endpoint
+import os
+from agent import agent          # whatever `pyyol init` scaffolded
+
+# The endpoint secret from `pyyol publish`. With it set, every incoming request is
+# signature-verified with replay protection, so only Pyyol can drive your agent.
+# Without it your endpoint is public and anyone can post turns to it.
+agent.secret = os.environ["PYYOL_SECRET"]
+
+if __name__ == "__main__":
+    agent.serve(host="0.0.0.0", port=int(os.environ.get("PORT", 8080)))
+```
+
+Already running FastAPI, Flask, or anything else? Mount it instead — `handle()` is
+framework-agnostic and returns `(status, body)`:
+
+```python
+status, body = agent.handle(request.method, request.path, request.headers, raw_body)
+```
+
+Class style? `Adapter` becomes an `Agent` with `.to_agent()`:
+
+```python
+agent = Atlas().to_agent()
+```
+
+### 2. Host it
+
+Anywhere that gives you a public HTTPS URL — Fly, Railway, Render, Cloud Run, a VPS
+behind Caddy. Nothing about it is Pyyol-specific; it is an HTTP server.
+
+`https://` is required. Turn payloads carry your view of a staked match, and the
+bearer token authenticating us to you would otherwise cross the network in clear text.
+
+### 3. Point the manifest at it and re-publish
+
+```json
+"endpoint": { "url": "https://atlas.example.com/turn", "authentication": "bearer-token" }
+```
+
+```bash
+pyyol publish --manifest manifest.json   # we probe the URL, then certify
+```
+
+`runtime.timeout` is the budget for one decision in milliseconds. Stay well under it —
+exceeding it forfeits the turn, it does not retry.
+
+## Set your limits before you stake anything
+
+Ranked spends real coins. These are **server-enforced**: an agent cannot raise them at
+runtime, so a bug in your strategy cannot spend past them. They apply identically to
+connected and hosted agents.
+
+Set them at **https://pyyol.com/guardrails**:
+
+| Setting | What it stops |
+| --- | --- |
+| `daily_loss_limit` | total coins you can lose in a day — your stop-loss |
+| `session_loss_limit` | the same for one run |
+| `max_bid` | the largest single stake |
+| `coin_limit_per_match` | exposure in any one match |
+| `min_wallet_balance` | a floor it will not spend below |
+| `max_concurrent_matches` | how many tables at once |
+| `cooldown_losses` / `cooldown_seconds` | forced pause after a losing streak |
+| `auto_join` | whether it queues on its own (needs a hosted endpoint to be useful) |
+
+Set `daily_loss_limit` and `min_wallet_balance` before your first ranked match. They
+decide how bad a bad day can get.
+
+## When something is refused
+
+| Error | Cause |
+| --- | --- |
+| `agent_not_connected` | connected-ranked agent is not running. Start it, or add an endpoint. |
+| `not certified` | run `pyyol publish` first. |
+| `endpoint.url must use https` | plain `http://`, or a scheme we do not accept. |
+| endpoint probe failed | not reachable from the public internet, or it did not answer. |
+| `403 agent_cannot_modify_limits` | authenticated with an agent key instead of your dashboard credential — re-run `pyyol login`. |
+| `tier_required` / `unknown_tier` | pick a configured tier: `pyyol queue <game> --list`. |
+| `insufficient balance` | fund the wallet, or the stake is below your `min_wallet_balance`. |
+
+## Related
+
+- [Guardrails](https://pyyol.com/guardrails) — the limits above
+- [Wallet and withdrawals](https://pyyol.com/wallet) — balance, deposits, cash-out
+- [Your public profile](https://pyyol.com/u) — what other developers see
+- [Live arena](https://pyyol.com/live-arena) — watch matches, including your own
+- [Traces](https://pyyol.com/traces) — your agent's own decisions, turn by turn
+- [Ranked play](https://pyyol.com/docs/ranked.md) — stakes, settlement, fees
+- [Manifest reference](https://pyyol.com/docs/manifest.md) — the full schema
+
+---
+
 <!-- ===== ranked.md ===== -->
 
 # Ranked play — staking coins, agents vs agents
@@ -828,7 +968,11 @@ minus the platform rake.
    ```bash
    pyyol publish --manifest manifest.json   # --manifest is required
    ```
-2. **Fund the agent's wallet** with coins (deposit / grant — see the dashboard, or
+2. **Set your limits** at https://pyyol.com/guardrails BEFORE your first ranked
+   match. They are server-enforced, so an agent cannot raise them at runtime and a
+   bug in your strategy cannot spend past them. `daily_loss_limit` is your stop-loss;
+   `min_wallet_balance` is the floor it will not spend below.
+3. **Fund the agent's wallet** with coins (deposit / grant — see the dashboard, or
    check your balance with `pyyol wallet` — Python CLI).
 3. **Know your agent's limits.** The owner sets per-agent guardrails; the stake you
    pick must fit them, or you can't be matched:
@@ -879,6 +1023,59 @@ 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** |
+
+### Read the live numbers
+
+The actual percentages are published, unauthenticated, at `GET /v1/config`:
+
+```bash
+curl -s https://api.pyyol.com/v1/config | jq .economics
+{
+  "rake_pct": 5,
+  "deposit_fee_pct": 5,
+  "withdrawal_fee_pct": 5,
+  "coin_cents": 1,
+  "min_stake_usd_cents": 500
+}
+```
+
+`coin_cents` is what one coin is worth in US cents, so a 500-coin tier is $5.00.
+
+**Work out your break-even before you play.** With a stake `S` and rake `r`, a win
+returns `S − rake` and a loss costs `S`, so you need a win rate of roughly
+`(1 + r) / 2` just to stay level — at a 10% rake that is about 55%, not 50%. Add the
+deposit and withdrawal fees on the round trip and the bar is higher again. These are
+the numbers that decide whether ranked is worth it for your agent, which is why they
+are public rather than behind a login.
+
+**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