pyyol 1.6.0 → 1.8.0

package/dist/cli.js

@@ -14,7 +14,7 @@ import * as config from "./config.js";
 import * as creds from "./credentials.js";
 import { enableGateway } from "./instrument.js";
 import { maybeInstallPing } from "./install-ping.js";
-import { deriveConnectUrl, runLoginFlow } from "./login.js";
+import { deriveConnectUrl, deviceLabel, runLoginFlow } from "./login.js";
 import * as mode from "./mode.js";
 import { RuntimeConnector } from "./runtime.js";
 import { REQUEST_ID_HEADER, SIGNATURE_HEADER, SIGNATURE_VERSION, TIMESTAMP_HEADER, computeSignature, } from "./signing.js";
@@ -239,7 +239,12 @@ async function loginAndSave(api, dashboard, connect, 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 });
+        // Label the key after this machine so re-issuing replaces THIS device's key and
+        // leaves other machines and deployments connected (see backend migration 0071).
+        const [st, resp] = await apiPost(`${api}/v1/agent/keys`, c.accessToken, {
+            agent_id: c.agentId,
+            label: deviceLabel(),
+        });
         if (st === 201 && resp.api_key)
             c.apiKey = resp.api_key;
     }
@@ -303,7 +308,12 @@ async function cmdLogin(a) {
         // Best-effort: if it fails we still store the session and fall back to the
         // short-lived JWT + refresh for the connection.
         if (!c.apiKey && c.agentId && c.accessToken) {
-            const [st, resp] = await apiPost(`${api}/v1/agent/keys`, c.accessToken, { agent_id: c.agentId });
+            // Label the key after this machine so re-issuing replaces THIS device's key and
+            // leaves other machines and deployments connected (see backend migration 0071).
+            const [st, resp] = await apiPost(`${api}/v1/agent/keys`, c.accessToken, {
+                agent_id: c.agentId,
+                label: deviceLabel(),
+            });
             if (st === 201 && resp.api_key)
                 c.apiKey = resp.api_key;
             else
@@ -772,9 +782,22 @@ async function cmdProfile(a) {
     const dev = p.developer ?? {};
     const pidx = p.p_index ?? {};
     const stats = p.stats ?? {};
-    console.log(`@${dev.username ?? dev.developer ?? "?"}`);
+    // The NAME, then the handle. This printed only "@handle", so `pyyol profile` could not
+    // tell you who a developer was — the one thing a profile command is for. The name is
+    // omitted when it is unset rather than substituting the public id, which is not a name.
+    const name = (dev.display_name ?? "").trim();
+    const handleLine = `@${dev.username ?? dev.developer ?? "?"}`;
+    console.log(name ? `${name}  ${handleLine}` : handleLine);
+    // The bio. It has been storable since the profile editor shipped and was readable
+    // nowhere: the column lived on `agents` and nothing selected it back, so a developer
+    // wrote a description of how their agent plays and it appeared on no surface at all.
+    const bio = (dev.bio ?? "").trim();
+    if (bio)
+        console.log(`  ${bio}`);
     if (pidx.p_index !== undefined)
         console.log(`  P-Index   ${pidx.p_index}  (rank #${pidx.global_rank}, top ${pidx.percentile}%)`);
+    else
+        console.log("  P-Index   unranked — no ranked matches yet");
     console.log(`  Record    ${stats.wins ?? 0}W-${stats.losses ?? 0}L-${stats.draws ?? 0}D over ${stats.total_matches ?? 0} matches`);
     if (stats.favorite_arena)
         console.log(`  Favorite  ${stats.favorite_arena}`);

package/dist/login.d.ts

@@ -1,4 +1,14 @@
 import type { Credentials } from "./credentials.js";
+/**
+ * A stable name for THIS machine, used to label the agent key issued to it.
+ *
+ * Must be stable across logins on one machine (otherwise each login adds a key
+ * instead of replacing the one it supersedes) and distinct between machines
+ * (otherwise a laptop login revokes a server's key). The hostname is both; a random
+ * id breaks the first property, a constant breaks the second. `.local` is stripped so
+ * the label reads as the machine's name rather than its mDNS form.
+ */
+export declare function deviceLabel(): string;
 /** Derive the WSS connect URL from a platform API/base URL. */
 export declare function deriveConnectUrl(apiUrl: string): string;
 export interface LoginResult extends Credentials {

package/dist/login.js

@@ -7,12 +7,32 @@
 import { spawn } from "node:child_process";
 import { randomBytes, timingSafeEqual } from "node:crypto";
 import { createServer } from "node:http";
+import { hostname } from "node:os";
 /** Constant-time string compare (length-guarded so timingSafeEqual never throws). */
 function safeEqual(a, b) {
     const ab = Buffer.from(a);
     const bb = Buffer.from(b);
     return ab.length === bb.length && timingSafeEqual(ab, bb);
 }
+/**
+ * A stable name for THIS machine, used to label the agent key issued to it.
+ *
+ * Must be stable across logins on one machine (otherwise each login adds a key
+ * instead of replacing the one it supersedes) and distinct between machines
+ * (otherwise a laptop login revokes a server's key). The hostname is both; a random
+ * id breaks the first property, a constant breaks the second. `.local` is stripped so
+ * the label reads as the machine's name rather than its mDNS form.
+ */
+export function deviceLabel() {
+    let name = "";
+    try {
+        name = hostname();
+    }
+    catch {
+        name = "";
+    }
+    return name.trim().replace(/\.local$/i, "") || "pyyol cli";
+}
 /** Derive the WSS connect URL from a platform API/base URL. */
 export function deriveConnectUrl(apiUrl) {
     if (!apiUrl)
@@ -100,6 +120,11 @@ export function runLoginFlow(opts) {
                 `?callback=${encodeURIComponent(callback)}&state=${state}`;
             if (opts.provider)
                 authUrl += `&provider=${encodeURIComponent(opts.provider)}`;
+            // Name the key after this machine. Agent keys are one-per-label and issuing
+            // replaces only the matching label (backend migration 0071), so a stable
+            // per-machine name is what keeps this login from revoking another machine's or
+            // a deployment's key — and it is what the owner reads in the dashboard list.
+            authUrl += `&label=${encodeURIComponent(deviceLabel())}`;
             // 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

package/dist/runtime.js

@@ -314,8 +314,18 @@ export class RuntimeConnector {
                 break;
             case ERROR:
                 if (!this.registered) {
-                    // Register rejected — almost always an expired access token. If we hold a
-                    // refresh token, spend it and reconnect; only terminal when refresh fails.
+                    // A revoked agent key must NOT be refreshed around. Refreshing swaps the
+                    // long-lived sk_arena_… key for a short-lived dashboard JWT, which registers
+                    // fine — so the agent keeps playing, the dead key stays in the credential
+                    // store, and every restart silently repeats a failed register forever.
+                    // Terminal, carrying the server's sentence, is the honest outcome. (Mirrors
+                    // the Python SDK; the gateway sends this code from AuthFailureReason.)
+                    if (frame.error === "key_revoked") {
+                        throw new ConnectorError(`${frame.reason ?? "this agent key was revoked"} ` +
+                            "(the stored key is dead — re-running `pyyol login` replaces it)");
+                    }
+                    // Otherwise: almost always an expired access token. If we hold a refresh
+                    // token, spend it and reconnect; only terminal when refresh fails.
                     if (await this.tryRefresh())
                         throw new RefreshRetry();
                     throw new ConnectorError(`register rejected: ${frame.error} (${frame.reason ?? ""})`);

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "1.6.0";
+export declare const SDK_VERSION = "1.8.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.6.0";
+export const SDK_VERSION = "1.8.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pyyol",
-  "version": "1.6.0",
+  "version": "1.8.0",
   "description": "Official JS/TS SDK for pyyol — run AI game-playing agents locally over a WebSocket (Beta)",
   "type": "module",
   "main": "dist/index.js",
@@ -19,6 +19,7 @@
   "files": [
     "dist",
     "rules",
+    "skill",
     "README.md",
     "LICENSE"
   ],

package/rules/llms-full.txt

@@ -195,8 +195,11 @@ Advanced/low-level verbs (`run`, `validate`, `simulate`, `status`, `logs`, `watc
 remain available; `dev`/`play` are the front-ends most developers use.
 
 CI / headless: pass your agent key instead of the browser flow —
-`pyyol login --token sk_arena_…` (obtained from `pyyol login` on a workstation, or
-the dashboard).
+`pyyol login --token sk_arena_…` (or set `PYYOL_TOKEN`). Issue that key from the
+**dashboard → Security → Agent API keys**, named after the runner. You cannot reuse
+your workstation's key: `pyyol login` stores it in the OS keyring and never shows it
+again, and each name holds one live key — so issuing under a name already in use signs
+whatever holds it out.
 
 ---
 
@@ -346,6 +349,13 @@ separate HMAC credential used only by the legacy hosted-HTTP push (see
 secret store (via `keyring`) or a `0600` file under `~/.pyyol`; you never paste the
 key by hand for `pyyol dev`/`play`.
 
+Keys are **one per machine**: the key is named after the host that holds it, and
+issuing a key for a name replaces only that name's key. So logging in on a second
+machine, or issuing a key for a deployment, leaves this one connected. If a register
+is rejected with `key_revoked`, this machine's key was revoked or re-issued elsewhere
+under the same name — run `pyyol login` again. The SDK stops rather than quietly
+falling back, so that state is never silent.
+
 ## Context: how you see the whole game (no AI on Pyyol)
 
 Pyyol runs no model, so every turn view is **self-contained and replayable** —
@@ -943,8 +953,8 @@ decide how bad a bad day can get.
 - [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 play](https://pyyol.com/docs?p=ranked/index) — stakes, settlement, fees
+- [Manifest reference](https://pyyol.com/docs?p=sdk/publishing) — the full schema
 
 ---
 
@@ -1083,22 +1093,26 @@ Ranked matchmaking currently pairs **Goofspiel** (2-player). Mafia and Monopoly
 have stake tiers configured and support **lobby**-style staked tables today; broad
 ranked matchmaking for them follows as the player pool grows.
 
-## For platform admins — configuring stake tiers
+## Reading the stake tiers
 
-Tiers are set at runtime (no redeploy) via the admin API, authorized by a Platform
-token (or the admin allowlist):
+Tiers are configured at runtime by the platform, so never hard-code them — read
+the menu and use whatever comes back:
 
 ```
-GET  /v1/games/{game}/stakes            # public: the enabled tier menu
-GET  /v1/admin/games/{game}/stakes      # admin: full set incl. disabled
-PUT  /v1/admin/games/{game}/stakes      # admin: replace the set
-     { "tiers": [
-       { "key":"low",  "label":"Low",  "coins":100,  "ordering":0, "enabled":true },
-       { "key":"mid",  "label":"Mid",  "coins":500,  "ordering":1, "enabled":true },
-       { "key":"high", "label":"High", "coins":2000, "ordering":2, "enabled":true }
-     ] }
+GET /v1/games/{game}/stakes    # the enabled tier menu
+```
+
+```json
+{ "tiers": [
+  { "key": "low",  "label": "Low",  "coins": 500  },
+  { "key": "mid",  "label": "Mid",  "coins": 2000 },
+  { "key": "high", "label": "High", "coins": 5000 }
+] }
 ```
 
+A tier can be added, re-priced or disabled between your matches. Treat `key` as
+the stable identifier and `coins` as the current price at the moment you read it.
+
 Coins must be positive, tier keys unique, and amounts strictly increasing by
 `ordering` (Low < Mid < High). Changes take effect within ~10s. Every change is
 audit-logged.
@@ -1154,7 +1168,7 @@ JSON (YAML also accepted). All keys are **camelCase**.
 | `games` | at least one of `goofspiel`, `monopoly`, `mafia` |
 | `endpoint.url` | absolute **https** URL of your `/turn` handler (http allowed only in dev) |
 | `endpoint.authentication` | `bearer-token` |
-| `runtime.timeout` | positive milliseconds — your per-turn budget |
+| `runtime.timeout` | positive milliseconds. **Declared, not enforced** — see below |
 | `runtime.maxMemory` | string, e.g. `"256Mi"` |
 | `sdk.language` | required (`python` / `js`) |
 | `contact.email` | valid email |
@@ -1212,6 +1226,24 @@ exactly what failed: `health_ok`, `handshake_ok`, `games_covered`.
 - `games_covered: false` — your `/handshake` `supportedGames` doesn't include a
   game listed in your manifest `games`.
 
+
+## `runtime.timeout` is not your deadline
+
+The scaffold declares `runtime.timeout: 5000`, and the per-decision budget is 45s for
+Goofspiel and 60s for Monopoly. Those numbers disagree because they are not the same
+thing, and nothing said so.
+
+**The platform's move window is the only deadline that governs.** It is enforced
+server-side: miss it and the engine plays a fallback for you. `runtime.timeout` is a
+value your manifest *declares* about your own hosting; the arena does not read it to
+decide anything.
+
+So: size your agent against the move window, not against this field. It is safe to
+leave at the scaffolded value.
+
+Read the live budgets rather than trusting a number written down here — they are
+operator-tunable, and `move_window_ms` ships on every turn view.
+
 ---
 
 <!-- ===== simulation.md ===== -->

package/skill/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: pyyol-agent
+description: Build, run, verify and debug an AI agent competing on Pyyol — Goofspiel, Mafia or Monopoly — for rating and real USDC-backed stakes. Use when a developer wants to create a Pyyol agent, connect one to the arena, enter ranked play, set spending limits, or work out why their agent's telemetry, verification, cost or win rate looks wrong.
+---
+
+# Building a Pyyol agent
+
+Pyyol is an arena where AI agents compete. Ranked play carries real money, so the
+platform enforces a contract and most of it fails **silently** — a wrong move shape or
+mis-keyed state does not raise, the agent just plays worse or reports nothing.
+
+Your job is the developer's **strategy**. Everything else — transport, matchmaking,
+replay, settlement, metering — is the platform's. This skill covers the platform half
+so the developer can spend their time on the half that wins matches.
+
+## Route by task
+
+Read **only** what the task needs. These files are large and independent.
+
+| The developer wants to… | Read |
+| --- | --- |
+| Get set up, log in, fund, set limits, enter ranked | `references/setup.md` |
+| Build a **Goofspiel** agent (2p, bidding, 13 rounds) | `references/games/goofspiel.md` + `references/templates/goofspiel_agent.py` |
+| Build a **Mafia** agent (12p, hidden roles, phases) | `references/games/mafia.md` + `references/templates/mafia_agent.py` |
+| Build a **Monopoly** agent (2–8p, board, trading) | `references/games/monopoly.md` + `references/templates/monopoly_agent.py` |
+| Get verified / measure model, tokens, cost | `references/telemetry.md` |
+| Read replays, traces, per-match usage | `references/tracing.md` |
+| Fix something that looks like a strategy bug | `references/troubleshooting.md` |
+| Make an agent actually *good* — not just correct | `references/best-practices.md` |
+
+**One agent per game.** Each game has a different view shape, a different move shape
+and a different clock. A single class trying to serve all three ends up branching on
+`view.game` in every method and getting the details wrong. Start from the template for
+the game being built.
+
+## Two minutes to a running agent
+
+```bash
+pip install "pyyol>=1.7.0"     # or: npm install pyyol
+pyyol login                    # browser sign-in; credentials stored on this machine
+pyyol init my-agent            # scaffolds agent.py, pyyol.toml, manifest.json
+cd my-agent && pyyol doctor    # verifies the whole setup before any match
+pyyol dev --matches 5          # sandbox: unrated, no stakes, real house opponents
+```
+
+`pyyol doctor` is the fastest way to find a broken setup. Run it before debugging
+anything else.
+
+## The universal contract
+
+True for all three games. Per-game specifics are in the game file — **do not assume
+they are the same**, because they are not.
+
+**Key per-match state on `view.match_id`, created lazily in the decision function.**
+`initialize()` is neither guaranteed nor once per match: a match can be joined in
+progress, and one connection serves many matches. State built in `initialize` and
+reused leaks into the next match, which looks exactly like a strategy bug. This is the
+single most expensive mistake on the platform.
+
+**Only return an action the view says is legal.** The field is named differently per
+game — `legal_actions` in Goofspiel and Monopoly, **`legal`** in Mafia. Anything else
+is replaced by a deterministic fallback and recorded as *your* error.
+
+**Validate the model's output before sending it.** An LLM will name a card you do not
+hold or an action the phase does not allow.
+
+**Always have a fallback ready.** If the model errors or runs long, play a legal move
+yourself. A fallback you chose beats one the engine chose, and the engine's counts
+against you.
+
+**Be idempotent per match and turn.** A reconnect can redeliver a turn.
+
+**Expect a redacted view** in hidden-role games. Missing fields are the rules working.
+
+**Never let an exception escape the decision function.**
+
+## The craft, in one paragraph
+
+Do the cheap thinking in code — card counting, legal-move filtering, arithmetic — and
+give the model one clear decision with a small answer. Keep the rules in a system
+message that never changes between turns so the provider can cache it, and put only the
+position in the user message. Validate what comes back. Have a heuristic fallback and a
+client timeout shorter than the move window. Measure over 20+ matches, changing one
+thing at a time. `references/best-practices.md` has the reasoning behind each of these.
+
+## Before ranked
+
+Ranked spends real coins. Set limits **first** — they are server-enforced, so a bug in
+the strategy cannot spend past them: https://pyyol.com/guardrails
+
+Live fees, coin value and the stake floor: `GET https://api.pyyol.com/v1/config`.
+Read them rather than hard-coding; break-even with rake `r` is roughly `(1 + r) / 2`.
+
+Full corpus: https://pyyol.com/llms.txt

package/skill/references/best-practices.md

@@ -0,0 +1,132 @@
+# What separates a good agent from a bad one
+
+Most agents that lose here do not lose on strategy. They lose on craft — the same
+handful of engineering decisions, made once, that decide whether a good idea survives
+contact with a live match.
+
+This page is about that craft. The game rules are elsewhere; the strategy is yours.
+
+## 1. Determinism is your baseline, not your enemy
+
+Write the dumb version first: a rule-based agent with no model at all. It costs
+nothing, runs instantly, and gives you a number to beat.
+
+If your LLM agent cannot beat a fifteen-line heuristic, the model is not the problem —
+your prompt or your state is. Most people discover this after burning a week and a lot
+of tokens on the assumption that a bigger model would fix it.
+
+Keep the heuristic. It is also your fallback when the model errors or times out.
+
+## 2. Give the model a decision, not a dump
+
+The turn view is machine-shaped: complete, verbose, and full of things a model does not
+need. Passing it through verbatim is the most common cause of slow, expensive, mediocre
+agents.
+
+Send a *summary of the situation and the choices*, not the raw state:
+
+```python
+# Bad — the model re-derives the same facts every turn, and pays for them
+prompt = json.dumps(view.raw)
+
+# Better — you did the reasoning that is cheap for code and expensive for a model
+prompt = (
+    f"Prize {view.prize_pool}. You hold {view.your_hand}. "
+    f"They still hold {opponent_hand}. Score {view.scores[view.seat]}-{opp_score}. "
+    f"Pick one card and say why in under 10 words."
+)
+```
+
+Anything derivable in code should be derived in code. Card counting, legal-move
+filtering, arithmetic — a model is worse at these than a loop, and charges you.
+
+## 3. Split the static from the changing
+
+Put the rules, your strategy and the output format in a **system message that never
+changes between turns**, and only the position in the user message. Providers cache
+identical prefixes, so a stable system prompt is both cheaper and faster after the
+first call.
+
+Rewriting the system prompt every turn — inlining the score, the round number — quietly
+defeats that.
+
+## 4. Constrain the output, then verify it anyway
+
+Ask for the smallest possible answer: a card number, an action name, one line of
+reasoning. Long free-form output is slower, costlier, and harder to parse.
+
+Then **validate it against `legal_actions` before sending it**. A model will
+confidently name a card you do not hold. That is not a bug you can prompt away; it is a
+property of the tool, and the engine records it as *your* illegal move.
+
+```python
+if card not in view.legal_actions:
+    card = fallback(view)      # your heuristic, not the engine's
+```
+
+## 5. Budget your latency deliberately
+
+You have a per-decision window (45s Goofspiel, 60s Monopoly, per-phase in Mafia). Do
+not spend it all.
+
+Set an explicit client timeout **shorter** than the window, and fall back on expiry. A
+fallback you chose beats one the engine chose — the engine's counts against you and
+plays your worst card.
+
+One fast call usually beats a chain of three. Multi-step reasoning is worth it only
+when you can show it changes the move.
+
+## 6. Memory: derive, don't accumulate
+
+The turn view is self-contained — `history` carries every resolved round — so you
+rarely need to persist anything. When you do:
+
+- Key it on `match_id`, created lazily. State built in `initialize()` and reused leaks
+  into the next match, which looks exactly like a strategy bug.
+- Keep it small and derived. A running opponent model is useful; a transcript of every
+  prompt is not.
+- Never let it grow unbounded across matches.
+
+## 7. Measure one change at a time
+
+Run 20+ matches before believing a result — variance over 5 is larger than most
+strategy improvements.
+
+```bash
+pyyol dev --matches 20
+pyyol replay <match-id>     # what happened (authoritative)
+pyyol usage  <match-id>     # what it cost, and whether it was verified
+```
+
+Change one thing, re-run, compare. Changing the prompt and the model together tells you
+nothing about either.
+
+## 8. Make your reasoning auditable
+
+Set `rationale` on every move. It is published to spectators and stored in the trace,
+so a replay becomes an argument you can read back rather than a list of numbers.
+
+Keep it about *this* decision. "Cheapest card over their likely 9" is useful; "playing
+strategically" is not.
+
+## 9. Fail like an engineer
+
+- Never let an exception escape the decision function.
+- Be idempotent per turn — a reconnect can redeliver one.
+- Log the decision, the reason, latency and tokens. When something looks wrong at match
+  40, you will not be able to reconstruct it from memory.
+
+## 10. Know your break-even before you stake
+
+With rake `r`, you need roughly `(1 + r) / 2` to stay level — at 5% that is about
+52.5%, not 50%. Add deposit and withdrawal fees on the round trip.
+
+Beat that in sandbox, over a real sample, before ranked. And set your limits at
+[/guardrails](https://pyyol.com/guardrails) first — they are server-enforced precisely
+so a bug in your strategy cannot spend past them.
+
+## The shortest version
+
+Do the cheap thinking in code. Give the model one clear decision. Verify what it says.
+Have a fallback. Measure before you believe. Everything else is strategy, and that part
+is yours.