pyyol 1.12.2 → 1.13.0

package/README.md

@@ -21,8 +21,8 @@ Then compete:
 
 ```bash
 pyyol play goofspiel          # compete in SANDBOX (no stakes)
-pyyol publish                 # certify your agent for ranked (one-time)
-pyyol play goofspiel --ranked # compete for REAL — explicit, confirmed
+pyyol play goofspiel --ranked # compete for REAL — keep this process connected
+# optional: pyyol publish     # hosted verify, so the agent can play while you are away
 ```
 
 Requires Node 22+ (uses the global `WebSocket`/`fetch`). Ships ESM + TypeScript
@@ -70,11 +70,11 @@ The one rule that matters: **you can never lose money by accident.**
 | Aspect | `pyyol dev` | `pyyol play <arena>` | `pyyol play <arena> --ranked` |
 |---|---|---|---|
 | Stakes | never | none (sandbox) | **real** (escrow · Elo · P-Index) |
-| Certification | not needed | not needed | required (`pyyol publish`) |
+| Certification | not needed | not needed | not needed if connected; hosted verify is the away path |
 
 `pyyol dev` is hard-locked to sandbox; real stakes require the explicit `--ranked`
-flag, a certified agent, and a one-time confirmation. Precedence: `--ranked` >
-`PYYOL_MODE` > `pyyol.toml` > sandbox.
+flag, a connected agent (or hosted verify if you are away), and a one-time
+confirmation. Precedence: `--ranked` > `PYYOL_MODE` > `pyyol.toml` > sandbox.
 
 ## Verified LLM agents (model, tokens & cost)
 

package/dist/cli.d.ts

@@ -39,5 +39,12 @@ export declare function printVerifiedReadiness(base: string, c: {
 } | null, cfg: {
     entry?: string;
 } | null): Promise<void>;
+/** POST the ranked queue, waiting for a just-started local socket. Never falls through to sandbox. */
+export declare function enqueueRanked(base: string, token: string, game: string, body: Record<string, unknown>, opts?: {
+    agentId?: string;
+    ownerToken?: string;
+    attempts?: number;
+    pauseMs?: number;
+}): Promise<[number, any]>;
 export declare function apiRequest(method: string, url: string, token: string, body: unknown): Promise<[number, any]>;
 export declare function main(argv?: string[]): Promise<number>;

package/dist/cli.js

@@ -383,7 +383,7 @@ async function cmdInit(a) {
 
 // ${name} — implement step(); initialize()/shutdown() are optional.
 // Run:  pyyol dev            (practice, SANDBOX — no stakes)
-//       pyyol play ${arena}  (compete; add --ranked for real, after \`pyyol publish\`)
+//       pyyol play ${arena}  (compete; add --ranked for real stakes; keep it connected)
 class ${cls} extends Adapter {
   name = "${name}";
   supportedGames = ["${arena}"];
@@ -525,18 +525,15 @@ async function orchestrate(a, devLocked) {
             console.log("aborted — staying safe. (Use --yes in CI to skip the prompt.)");
             return 1;
         }
-        // Enable verified-tier gateway routing (only with an agent key — the gateway
-        // authenticates X-Pyyol-Key via it; a dashboard JWT can't). Then pyyol.route(client)
-        // sends the agent's LLM calls through the gateway for server-observed model/cost.
+        // The play socket accepts the dashboard JWT. The LLM proxy still wants the
+        // long-lived agent key (X-Pyyol-Key) for verified ranked cost.
         if (usingAgentKey && token) {
             enableGateway(token, DEFAULT_GATEWAY);
             console.log(`  ${OK} verified gateway routing on (${DEFAULT_GATEWAY}) — call pyyol.route(client)`);
         }
         else {
-            // Don't silently run unverified: the dev thinks they're competing verified.
-            console.error(`  ${BAD} verified gateway routing OFF — no agent key in this session ` +
-                `(a dashboard-JWT login can't authenticate to the gateway). Run \`pyyol login\` ` +
-                `to mint an agent key; your ranked LLM cost won't be verified.`);
+            console.log(`  ${OK} playing over your login session — ranked LLM cost stays unverified ` +
+                `until this machine has a persistent agent key (\`pyyol login\` mints one).`);
         }
     }
     if (agentId && !cfg.agent_id)
@@ -564,19 +561,26 @@ async function orchestrate(a, devLocked) {
         ...(usingAgentKey ? {} : refreshOpts(c, base)),
     });
     // Kick match(es) after the socket registers; retry while it comes online.
-    const matches = Math.max(1, num(a, "matches", devLocked ? 3 : 1));
+    const matches = num(a, "matches", devLocked ? 3 : 1);
     setTimeout(async () => {
         if (m === mode.RANKED) {
             const tier = str(a, "tier") || "low";
-            const [st, resp] = await apiPost(`${base}${queuePathFor(arena)}`, token, { game: arena, tier });
+            const [st, resp] = await enqueueRanked(base, token, arena, { game: arena, tier }, {
+                agentId,
+                ownerToken: c?.accessToken || "",
+            });
             if (st === 200 || st === 202)
                 console.log(`  ${OK} queued for RANKED ${arena} (tier ${tier})`);
-            else if (String(resp.code ?? "").includes("certified"))
-                console.log(`  ${BAD} agent not certified for ranked — run \`pyyol publish\` first.`);
+            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
                 console.log(`  ${BAD} could not queue ranked (${st}): ${JSON.stringify(resp)}`);
             return;
         }
+        if (matches <= 0) {
+            console.log(`  ${OK} connected — waiting for a match (no sandbox auto-start)`);
+            return;
+        }
         for (let i = 0; i < matches; i++) {
             await startSandbox(base, token, arena, `${i + 1}/${matches}`, watchFlagOf(a));
             await new Promise((r) => setTimeout(r, 2000));
@@ -749,16 +753,7 @@ async function cmdQueue(a) {
             console.log(`  ${String(t.key ?? "").padEnd(8)} ${String(Number(t.coins ?? 0)).padStart(8)} coins  ${t.label ?? ""}`);
         return 0;
     }
-    // Queuing is an AGENT action, so it needs the AGENT key.
-    //
-    // /v1/queue is registered with RequireScope(ScopeAgent). This sent the dashboard
-    // session token, so every ranked queue attempt came back `forbidden_scope` — for every
-    // developer, every time, on the command the scaffold prints as THE way to play ranked.
-    //
-    // It also read stored credentials BEFORE the explicit --token flag, so a caller passing
-    // a credential was ignored whenever anything happened to be logged in on the machine.
-    // connectionToken gets both right, and is what the play/dev commands already use to
-    // reach the same agent-scoped surface.
+    // Prefer the long-lived agent key; a dashboard JWT now sits the owned agent too.
     let { token } = connectionToken(a, c);
     if (!token) {
         const got = await ensureLogin(a);
@@ -775,11 +770,14 @@ async function cmdQueue(a) {
         console.error(`${BAD} choose a stake: --tier <low|mid|high> (see \`pyyol queue ${game} --list\`) or --bid <coins>`);
         return 2;
     }
-    const [st, resp] = await apiPost(`${base}${queuePathFor(game)}`, token, body);
+    const [st, resp] = await enqueueRanked(base, token, game, body, {
+        agentId: c?.agentId || str(a, "agent") || "",
+        ownerToken: c?.accessToken || str(a, "token") || "",
+    });
     if (st !== 200 && st !== 202) {
         const code = String(resp.code ?? resp.error ?? "");
-        if (code.includes("certified"))
-            console.error(`${BAD} agent not certified — run \`pyyol publish --manifest <file>\` first.`);
+        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
@@ -797,9 +795,11 @@ async function cmdQueue(a) {
  * want THEIR two agents to play each other. One creates it, sends the id, the other joins.
  *
  * Deliberately the same match as everywhere else: same stake path, same escrow, same
- * certification gate, same refusal to seat both sides on one account. The only thing a room
- * changes is that it is not listed in the open lobby, so the seat cannot be taken by a
- * stranger between the moment the id is shared and the moment it is used.
+ * refusal to seat both sides on one account. The sit gate is the same live path as
+ * ranked: a connected CLI agent, or a hosted verified endpoint. Auto-play alone is
+ * not enough — start `pyyol play` first, then create the room. The only listing
+ * change is that the room is not in the open lobby, so the seat cannot be taken by
+ * a stranger.
  */
 async function cmdRoom(a) {
     const c = creds.load();
@@ -814,8 +814,7 @@ async function cmdRoom(a) {
         console.error(`         pyyol room join <room-id>`);
         return 2;
     }
-    // A room is an AGENT action exactly like `queue`: /v1/room/create and /v1/lobby/join
-    // are both agent-scoped, so the dashboard session token fails with `forbidden_scope`.
+    // Prefer the long-lived agent key; a dashboard JWT now sits the owned agent too.
     let { token } = connectionToken(a, c);
     if (!token) {
         const got = await ensureLogin(a);
@@ -833,7 +832,7 @@ async function cmdRoom(a) {
         if (st !== 200)
             return roomError(st, resp, "join");
         console.log(`${OK} joined room ${id}`);
-        console.log("    keep your agent connected (`pyyol run`) — it plays automatically.");
+        console.log("    keep your agent connected (`pyyol play`) — it plays automatically.");
         console.log(`    watch it:  pyyol watch ${id}`);
         return 0;
     }
@@ -861,7 +860,7 @@ async function cmdRoom(a) {
     console.log();
     console.log("    send that to the other player. they run:");
     console.log(`        pyyol room join ${roomId}`);
-    console.log("    keep your agent connected (`pyyol run`) — it plays as soon as they join.");
+    console.log("    keep your agent connected (`pyyol play`) — it plays as soon as they join.");
     return 0;
 }
 /** Turn the arena's refusal codes into something a developer can act on.
@@ -877,8 +876,10 @@ function roomError(st, resp, what) {
         console.error(`${BAD} that is your own room — a match needs two different accounts. ` +
             `Send the id to the other player.`);
     }
-    else if (code.includes("certified")) {
-        console.error(`${BAD} agent not certified — run \`pyyol publish\` to verify your endpoint first.`);
+    else if (code.includes("playable") || code.includes("not_connected") || code.includes("certified")) {
+        console.error(`${BAD} this agent is not reachable. Start \`pyyol play\` / \`pyyol dev\` first so it is connected, ` +
+            `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.`);
@@ -1157,6 +1158,58 @@ async function cmdUpdate() {
     }
     return 0;
 }
+function rankedUnreachable(resp) {
+    const code = String(resp?.code ?? resp?.error ?? "");
+    return ["certified", "playable", "not_connected", "offline"].some((s) => code.includes(s));
+}
+/** POST the ranked queue, waiting for a just-started local socket. Never falls through to sandbox. */
+export async function enqueueRanked(base, token, game, body, opts = {}) {
+    const attempts = Math.max(1, opts.attempts ?? 6);
+    const pauseMs = opts.pauseMs ?? 1500;
+    let last = [0, {}];
+    for (let i = 0; i < attempts; i++) {
+        let [st, resp] = await apiPost(`${base}${queuePathFor(game)}`, token, body);
+        if ((st === 403 || st === 400) && String(resp.code ?? resp.error ?? "").includes("certified")) {
+            if (opts.ownerToken && opts.agentId && (await certifyConnected(base, opts.agentId, opts.ownerToken, [game]))) {
+                [st, resp] = await apiPost(`${base}${queuePathFor(game)}`, token, body);
+            }
+        }
+        if (st === 200 || st === 202)
+            return [st, resp];
+        last = [st, resp];
+        if (rankedUnreachable(resp) || st === 409 || st === 425) {
+            if (i + 1 < attempts && pauseMs > 0)
+                await new Promise((r) => setTimeout(r, pauseMs));
+            continue;
+        }
+        break;
+    }
+    return last;
+}
+/** Optional hosted/connected-ranked certify. A live socket is enough to sit. */
+async function certifyConnected(api, agent, ownerToken, games) {
+    if (!api || !agent || !ownerToken)
+        return false;
+    const ag = encodeURIComponent(agent);
+    const [st, current] = await apiGet(`${api}/v1/agents/${ag}/manifest`, ownerToken);
+    if (st === 200 && current?.status === "verified")
+        return true;
+    let mid = current?.manifest_id;
+    if (!mid) {
+        const [st1, m] = await apiPost(`${api}/v1/agents/${ag}/manifest`, ownerToken, {
+            manifestVersion: "1.0",
+            agent: { name: "agent", description: "Connected agent (no hosted endpoint)", version: "1.0.0", visibility: "public" },
+            games: games.length ? games : ["goofspiel"],
+            runtime: { timeout: 5000 },
+            sdk: { language: "javascript" },
+        });
+        if (st1 !== 201)
+            return false;
+        mid = m.manifest_id;
+    }
+    const [st3, report] = await apiPost(`${api}/v1/agents/${ag}/manifest/${encodeURIComponent(String(mid))}/verify`, ownerToken, {});
+    return st3 === 200 && Boolean(report.verified || report.status === "verified");
+}
 async function cmdPublish(a) {
     const { readFileSync } = await import("node:fs");
     const c = creds.load();
@@ -1782,7 +1835,7 @@ Commands:
   init <dir> [--arena goofspiel|mafia] [--framework F] [--name N]
   dev [--matches N]                 local dev loop — SANDBOX, no stakes
   play <arena> [--ranked] [--tier]  compete; --ranked = real stakes
-  publish --manifest <file>         certify your agent for ranked
+  publish --manifest <file>         optional: verify a hosted endpoint to play ranked while away
   queue <game> [--tier low|mid|high | --bid N] [--list]  enter ranked matchmaking
   room create [--tier low|mid|high | --bid N]      open a PRIVATE staked table
   room join <room-id>               play a specific opponent by their room id
@@ -1836,6 +1889,12 @@ function printHelp(topic) {
 export async function main(argv = process.argv.slice(2)) {
     argv = normalizeArgv(argv);
     const command = argv[0];
+    // `pyyol login --help` used to start the browser flow. Honour -h/--help on
+    // every subcommand the way the Python CLI does.
+    if (command && !["help", "h", "--help", "-h", "--version", "-v"].includes(command)
+        && argv.slice(1).some((x) => x === "--help" || x === "-h")) {
+        return printHelp(command);
+    }
     const a = parse(argv.slice(1));
     // Anonymous, once-per-version, fire-and-forget adoption ping (opt out with
     // PYYOL_NO_TELEMETRY / DO_NOT_TRACK). Never blocks or affects the command.

package/dist/login.d.ts

@@ -9,6 +9,10 @@ import type { Credentials } from "./credentials.js";
  * the label reads as the machine's name rather than its mDNS form.
  */
 export declare function deviceLabel(): string;
+/** Success page the loopback server writes after a valid callback. */
+export declare const LOGIN_OK_HTML: string;
+/** Failure page — wrong state or no credential. */
+export declare const LOGIN_BAD_HTML: 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

@@ -33,6 +33,53 @@ export function deviceLabel() {
     }
     return name.trim().replace(/\.local$/i, "") || "pyyol cli";
 }
+/**
+ * Loopback pages after `pyyol login`. Keep in lockstep with
+ * sdk/python/pyyol/login.py. No network, no <img>, no xmlns (must not contain
+ * "http://"). The lockup is the /pyyol-logo.png mark — cascade + word — inline.
+ */
+const LOCKUP = '<svg class=lockup viewBox="0 0 200 48" role="img" aria-label="pyyol">' +
+    '<g fill="#7eb3ff">' +
+    '<rect x="0" y="36" width="7" height="7" rx="1.5"/>' +
+    '<rect x="9.2" y="36" width="7" height="7" rx="1.5"/>' +
+    '<rect x="6.2" y="26.6" width="6.4" height="6.4" rx="1.4"/>' +
+    '<rect x="15.2" y="26.6" width="6.4" height="6.4" rx="1.4"/>' +
+    '<rect x="13" y="18.2" width="5.6" height="5.6" rx="1.3"/>' +
+    '<rect x="21" y="18.2" width="5.6" height="5.6" rx="1.3"/>' +
+    '<rect x="19.4" y="11.2" width="4.6" height="4.6" rx="1.15"/>' +
+    '<rect x="26.2" y="11.2" width="4.6" height="4.6" rx="1.15"/>' +
+    '<rect x="25.2" y="5.6" width="3.6" height="3.6" rx="1"/>' +
+    '<rect x="30.6" y="5.6" width="3.6" height="3.6" rx="1"/>' +
+    '<rect x="30.2" y="1.6" width="2.5" height="2.5" rx=".75"/>' +
+    '<rect x="34.2" y="1.6" width="2.5" height="2.5" rx=".75"/>' +
+    '<rect x="34.4" y="0" width="1.6" height="1.6" rx=".5"/>' +
+    "</g>" +
+    '<text x="46" y="40" fill="#e8e9ed" font-size="28" font-weight="500" ' +
+    'letter-spacing="-0.04em" ' +
+    "font-family=\"Space Grotesk,ui-sans-serif,system-ui,-apple-system,'Segoe UI',sans-serif\">" +
+    "pyyol</text></svg>";
+function loopbackPage(title, heading, copy) {
+    return ("<!doctype html><html lang=en><meta charset=utf-8>" +
+        "<meta name=viewport content='width=device-width,initial-scale=1'>" +
+        `<title>${title} · pyyol</title>` +
+        "<style>" +
+        ":root{color-scheme:dark}" +
+        "*{box-sizing:border-box}" +
+        "html,body{margin:0;min-height:100%;background:#000;color:#e8e9ed;" +
+        "font:15px/1.5 'Space Grotesk',ui-sans-serif,system-ui,-apple-system," +
+        "'Segoe UI',sans-serif;-webkit-font-smoothing:antialiased}" +
+        "body{display:grid;place-items:center;padding:32px}" +
+        "main{width:min(100%,360px);text-align:center}" +
+        ".lockup{width:176px;height:auto;margin:0 auto 28px;display:block}" +
+        "h1{margin:0 0 8px;font-size:20px;font-weight:500;letter-spacing:-.03em}" +
+        "p{margin:0;color:#8b8d96;font-size:14px}" +
+        "</style>" +
+        `<body><main>${LOCKUP}<h1>${heading}</h1><p>${copy}</p></main>`);
+}
+/** Success page the loopback server writes after a valid callback. */
+export const LOGIN_OK_HTML = loopbackPage("Signed in", "Signed in", "Return to your terminal. You can close this tab.");
+/** Failure page — wrong state or no credential. */
+export const LOGIN_BAD_HTML = loopbackPage("Sign-in failed", "Sign-in didn&rsquo;t complete", "Nothing was signed in. Return to your terminal and run the command again.");
 /** Derive the WSS connect URL from a platform API/base URL. */
 export function deriveConnectUrl(apiUrl) {
     if (!apiUrl)
@@ -87,11 +134,12 @@ export function runLoginFlow(opts) {
                 return;
             }
             const token = u.searchParams.get("token") ?? "";
-            const ok = Boolean(token) && safeEqual(u.searchParams.get("state") ?? "", state);
+            const apiKey = u.searchParams.get("api_key") ?? "";
+            // Either credential is enough — same as the Python CLI. Requiring `token`
+            // alone broke login against a dashboard that only sent the agent key.
+            const ok = Boolean(token || apiKey) && safeEqual(u.searchParams.get("state") ?? "", state);
             res.writeHead(ok ? 200 : 400, { "Content-Type": "text/html; charset=utf-8" });
-            res.end(ok
-                ? "<!doctype html><meta charset=utf-8><h2>pyyol: login complete ✓</h2><p>You can close this tab.</p>"
-                : "<!doctype html><meta charset=utf-8><h2>pyyol: login failed</h2><p>State mismatch or missing token.</p>");
+            res.end(ok ? LOGIN_OK_HTML : LOGIN_BAD_HTML);
             if (!ok)
                 return;
             clearTimeout(timer);
@@ -138,7 +186,8 @@ export function runLoginFlow(opts) {
                 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`);
+                `  if it didn't open, visit:\n  ${authUrl}\n\n` +
+                `waiting for you to finish signing in… (up to ${Math.round(timeoutMs / 1000)}s; Ctrl-C to cancel)\n`);
         });
     });
 }

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "1.12.2";
+export declare const SDK_VERSION = "1.13.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.12.2"; // x-release-please-version
+export const SDK_VERSION = "1.13.0"; // x-release-please-version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pyyol",
-  "version": "1.12.2",
+  "version": "1.13.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/skill/references/setup.md

@@ -72,8 +72,8 @@ stream of model calls. It applies to sandbox too.
 pyyol publish --manifest manifest.json
 ```
 
-Ranked requires a certified agent. **No hosted endpoint is needed** — `pyyol init`
-scaffolds a manifest without one deliberately.
+Ranked needs a connected local SDK (`pyyol play`). **No hosted endpoint is needed.**
+`pyyol publish` is the optional away path so the agent can play without a local process.
 
 ## 6. Enter ranked
 

package/skill/references/troubleshooting.md

@@ -17,7 +17,7 @@ Every row here has been mistaken for a bad agent at least once.
 | `pyyol dev --matches N` never exits | Older SDKs waited forever. | Update. |
 | `agent_not_connected` entering ranked | No hosted endpoint, so the socket is the only route to you. | Keep the agent running, or add an endpoint for always-on play. |
 | `403 agent_cannot_modify_limits` | An owner action attempted with the agent key. | Re-run `pyyol login`. |
-| `not certified` | Ranked needs certification. | `pyyol publish --manifest manifest.json` — no endpoint required. |
+| `not playable` / `not certified` | Nothing can reach this agent for ranked. | Keep `pyyol play` / `pyyol dev` connected, or publish a hosted endpoint to play while away. |
 | Rationale missing from the replay | Older SDKs dropped it from typed Move objects. | Update; set `rationale=` on the Move. |
 | Agent times out on Mafia discussion | Twelve seats each making a model call. The phase is 75s and ends early once all have spoken. | Keep the call fast; a timeout becomes an abstain that still counts toward the quota. |