pyyol 1.2.1 → 1.4.0

package/README.md

@@ -76,6 +76,25 @@ The one rule that matters: **you can never lose money by accident.**
 flag, a certified agent, and a one-time confirmation. Precedence: `--ranked` >
 `PYYOL_MODE` > `pyyol.toml` > sandbox.
 
+## Verified LLM agents (model, tokens & cost)
+
+Drive your moves with an LLM and Pyyol captures the exact **model, tokens, and cost**
+for every turn — automatically. Two lines:
+
+```ts
+import pyyol from "pyyol";
+import OpenAI from "openai";
+
+await pyyol.instrument();              // capture usage on every LLM call
+const client = pyyol.route(new OpenAI()); // in ranked, route through the gateway (verified)
+// ...call client inside step(); usage is attached to your move for you.
+```
+
+In sandbox this records estimated cost; in ranked it routes through the Pyyol Gateway
+so the numbers are server-observed (unfakeable) and you earn the blue **Verified**
+badge. `route()` is a safe no-op in sandbox. Runnable example:
+[`examples/llm-agent.ts`](examples/llm-agent.ts).
+
 ## Games
 
 Three games are available; each is documented in
@@ -222,10 +241,18 @@ the protocol into an existing framework (Express, Fastify, a serverless handler)
 
 ## Commands
 
-`login` · `logout` · `whoami` · `init` · `dev` · `play` · `publish` · `replay` ·
-`profile` · `leaderboard` · `arenas` · `doctor` · `update`. Run `pyyol --help` for
-details, or `pyyol doctor` to diagnose your setup. Config lives in a tiny
-**`pyyol.toml`** (convention over configuration — no manifest files).
+Auth & scaffold: `login` · `logout` · `whoami` · `init` · `doctor`.
+Play: `dev` · `play` · `watch` · `replay`.
+Deploy-once: `serve` · `autoplay` · `run`.
+Ranked: `publish --manifest <file>`.
+Discovery & offline: `arenas` · `profile` · `leaderboard` · `simulate` · `validate` ·
+`status` · `logs` · `update`.
+
+Run `pyyol --help` for details, or `pyyol doctor` to diagnose your setup. Config lives
+in a tiny **`pyyol.toml`** (convention over configuration — no manifest files).
+
+> `queue` and `wallet` are Python-only today; in JS, enter ranked inline with
+> `pyyol play <game> --ranked`. Full reference: the docs "CLI reference" page.
 
 ## Security
 

package/dist/adapter.d.ts

@@ -1,12 +1,12 @@
 import { Agent } from "./server.js";
-export declare abstract class Adapter {
+export declare abstract class Adapter<View = unknown, Move = unknown> {
     name: string;
     supportedGames: string[];
     secret: string;
     /** Called once at match start (optional). Return an ack object or nothing. */
     initialize(_ctx: unknown): unknown;
-    /** Decide one move for `view` and return it. REQUIRED. */
-    abstract step(view: unknown): unknown;
+    /** Decide one move for `view` and return it. REQUIRED. Async is supported. */
+    abstract step(view: View): Move | Promise<Move>;
     /** Called once when the match ends (optional). */
     shutdown(_result: unknown): void;
     /** Build the underlying Agent that drives the real transport. */

package/dist/adapter.js

@@ -6,13 +6,20 @@
  *
  *     import { Adapter } from "pyyol";
  *
- *     class Atlas extends Adapter {
+ *     import { Adapter } from "pyyol";
+ *     import type { GoofspielView, GoofspielMove } from "pyyol";
+ *
+ *     // Typed: `view` is a GoofspielView and the return is checked.
+ *     class Atlas extends Adapter<GoofspielView, GoofspielMove> {
  *       name = "atlas";
  *       supportedGames = ["goofspiel"];
  *       step(view) { return { round: view.round, card: Math.min(...view.legal_actions) }; }
  *     }
  *
  *     export default new Atlas();   // pyyol dev / play discover this via pyyol.toml
+ *
+ * The type params are optional and default to `unknown` (so `extends Adapter` keeps
+ * working); supply `Adapter<View, Move>` to get a typed `view` and a checked return.
  */
 import { SUPPORTED_GAMES } from "./models.js";
 import { Agent } from "./server.js";

package/dist/cli.js

@@ -11,6 +11,8 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import { asAgent } from "./adapter.js";
 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 * as mode from "./mode.js";
 import { RuntimeConnector } from "./runtime.js";
@@ -18,6 +20,11 @@ import { REQUEST_ID_HEADER, SIGNATURE_HEADER, SIGNATURE_VERSION, TIMESTAMP_HEADE
 import { SDK_VERSION } from "./version.js";
 const OK = "✓";
 const BAD = "✗";
+const WARN = "•";
+// N-player games use the group matchmaking queue; Goofspiel (1v1) uses the 2-player
+// queue. Same enqueue request shape, different endpoint.
+const GROUP_GAMES = new Set(["mafia", "monopoly"]);
+const queuePathFor = (game) => (GROUP_GAMES.has(game) ? "/v1/group-queue" : "/v1/queue");
 // Public platform defaults. `pyyol login` with no flags hits the live platform;
 // self-hosted/local users override via PYYOL_API / PYYOL_DASHBOARD (or --api /
 // --dashboard). The API host serves /v1/*; the dashboard host serves /cli-login —
@@ -25,6 +32,10 @@ const BAD = "✗";
 // to the API host.
 const DEFAULT_API_BASE = (process.env.PYYOL_API || "").replace(/\/$/, "") || "https://api.pyyol.com";
 const DEFAULT_DASHBOARD = (process.env.PYYOL_DASHBOARD || "").replace(/\/$/, "") || "https://pyyol.com";
+// Verified-tier LLM gateway base (Phase 4). Ranked mode enables gateway routing so
+// pyyol.route(client) sends the agent's LLM calls through it for server-observed
+// (unfakeable) model/token/cost. Override with $PYYOL_GATEWAY.
+const DEFAULT_GATEWAY = (process.env.PYYOL_GATEWAY || "").replace(/\/$/, "") || "https://gateway.pyyol.com";
 // Agent API keys look like "sk_arena_<lookup>_<secret>" — the long-lived, revocable
 // connection credential (mirrors backend platform.PrefixKey).
 const AGENT_KEY_PREFIX = "sk_arena_";
@@ -222,6 +233,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,
@@ -322,7 +369,11 @@ class ${cls} extends Adapter {
   supportedGames = ["${arena}"];
 
   step(view) {
-    // Your strategy goes here (call any framework or LLM). Baseline below:
+    // Your strategy goes here (call any framework or LLM). Baseline below.
+    // Driving moves with an LLM? Capture the real model/tokens/cost for free:
+    //   import pyyol from "pyyol"; await pyyol.instrument();   // once, at the top
+    //   const client = pyyol.route(new OpenAI());  // in ranked, routes via the gateway
+    // then call \`client\` here. See docs -> "Verified LLM agents".
     const legal = view.legal_actions ?? [];
     ${arena === "goofspiel" ? "return { round: view.round, card: Math.min(...legal) };" : "return legal.length ? { action: legal[0] } : {};"}
   }
@@ -372,13 +423,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,
@@ -398,6 +447,19 @@ 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.
+        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.`);
+        }
     }
     if (agentId && !cfg.agent_id)
         config.setAgentId(agentId);
@@ -428,7 +490,7 @@ async function orchestrate(a, devLocked) {
     setTimeout(async () => {
         if (m === mode.RANKED) {
             const tier = str(a, "tier") || "low";
-            const [st, resp] = await apiPost(`${base}/v1/queue`, token, { game: arena, tier });
+            const [st, resp] = await apiPost(`${base}${queuePathFor(arena)}`, token, { game: arena, tier });
             if (st === 200 || st === 202)
                 console.log(`  ${OK} queued for RANKED ${arena} (tier ${tier})`);
             else if (String(resp.code ?? "").includes("certified"))
@@ -459,6 +521,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) {
@@ -478,6 +576,110 @@ async function cmdArenas(a) {
     }
     return 0;
 }
+/** `pyyol wallet` — show the owner's coin balance + per-agent wallets, so a dev can
+ *  see why ranked was refused ("not enough coins") without leaving the CLI. Parity
+ *  with the Python CLI. Owner-scoped, so it uses the dashboard access token. */
+async function cmdWallet(a) {
+    const c = creds.load();
+    const base = httpBase(a, c);
+    const 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 [st, w] = await apiGet(`${base}/v1/user/wallet`, token);
+    if (st !== 200) {
+        console.error(`${BAD} could not fetch wallet (${st}): ${JSON.stringify(w)}`);
+        return 1;
+    }
+    if (bool(a, "json")) {
+        console.log(JSON.stringify(w, null, 2));
+        return 0;
+    }
+    const cents = Number(w.coin_cents ?? 1) || 1;
+    const usd = (coins) => `$${((coins * cents) / 100).toFixed(2)}`;
+    const avail = Number(w.available_balance ?? 0);
+    console.log("Treasury");
+    console.log(`  Available   ${avail.toLocaleString()} coins  (${usd(avail)})`);
+    if (w.locked_balance)
+        console.log(`  Locked      ${Number(w.locked_balance).toLocaleString()} coins (in active matches)`);
+    if (w.lifetime_earnings)
+        console.log(`  Earned      ${Number(w.lifetime_earnings).toLocaleString()} coins (lifetime)`);
+    const agents = w.agents ?? [];
+    if (agents.length) {
+        console.log("\nAgent wallets");
+        for (const ag of agents) {
+            const bal = Number(ag.balance ?? 0).toLocaleString();
+            const wd = Number(ag.withdrawable ?? 0).toLocaleString();
+            console.log(`  ${String(ag.name ?? ag.agent ?? "?").padEnd(20)} ${bal.padStart(10)} coins   withdrawable ${wd}`);
+        }
+    }
+    return 0;
+}
+/** `pyyol queue <game> [--tier low|mid|high | --bid N] [--list]` — enter ranked
+ *  matchmaking at a stake tier (parity with the Python CLI). `--list` shows the
+ *  admin-configured tiers. The game is a POSITIONAL argument. */
+async function cmdQueue(a) {
+    const c = creds.load();
+    const base = httpBase(a, c);
+    if (!base) {
+        console.error(`${BAD} no API url — pass --api or run \`pyyol login\`.`);
+        return 2;
+    }
+    const game = a.positionals[0] ?? "";
+    if (!game) {
+        console.error(`${BAD} usage: pyyol queue <game> [--tier low|mid|high | --bid N] [--list]`);
+        return 2;
+    }
+    if (bool(a, "list")) {
+        const [st, resp] = await apiGet(`${base}/v1/games/${game}/stakes`);
+        if (st !== 200) {
+            console.error(`${BAD} could not fetch tiers (${st})`);
+            return 1;
+        }
+        const tiers = resp.tiers ?? [];
+        if (!tiers.length) {
+            console.log(`no stake tiers configured for ${game} — use --bid <coins>`);
+            return 0;
+        }
+        console.log(`${game} stake tiers:`);
+        for (const t of tiers)
+            console.log(`  ${String(t.key ?? "").padEnd(8)} ${String(Number(t.coins ?? 0)).padStart(8)} coins  ${t.label ?? ""}`);
+        return 0;
+    }
+    // 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) {
+        const got = await ensureLogin(a);
+        if (!got)
+            return 2;
+        token = got.accessToken || got.apiKey || "";
+    }
+    const body = { game };
+    if (str(a, "tier"))
+        body.tier = str(a, "tier");
+    else if (num(a, "bid", 0) > 0)
+        body.bid = num(a, "bid", 0);
+    else {
+        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);
+    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.`);
+        else if (code.includes("balance") || code.includes("insufficient"))
+            console.error(`${BAD} not enough coins — fund your wallet (see \`pyyol wallet\`).`);
+        else
+            console.error(`${BAD} could not queue ranked (${st}): ${JSON.stringify(resp)}`);
+        return 1;
+    }
+    console.log(`  ${OK} queued for ${game}${body.tier ? ` (tier ${body.tier})` : ""} — keep your agent connected; it plays when matched.`);
+    if (resp.match_id)
+        console.log(`  ${OK} matched → ${resp.match_id}\n      watch it:  pyyol watch ${resp.match_id}`);
+    return 0;
+}
 async function cmdLeaderboard(a) {
     const base = httpBase(a, creds.load());
     if (!base) {
@@ -789,10 +991,42 @@ function autoplayOpts(a, cfg) {
 async function autoplaySet(api, token, enabled, m, bid, games) {
     return apiRequest("PUT", `${api.replace(/\/$/, "")}/v1/agent/autoplay`, token, { enabled, mode: m, bid, games });
 }
+/** GET the agent's auto-play setting + last observed status (mirrors Python
+ *  `_autoplay_get`). */
+async function autoplayGet(api, token) {
+    return apiGet(`${api.replace(/\/$/, "")}/v1/agent/autoplay`, token);
+}
+const AUTOPLAY_STATUS_LABEL = {
+    playing: [OK, "playing"],
+    searching: [OK, "searching for an opponent"],
+    paused: [WARN, "paused"],
+    blocked: [BAD, "not playing"],
+};
+/** Render `pyyol autoplay status` — is it on, and WHY it is or isn't playing, so a
+ *  quiet auto-play agent is never a mystery. */
+function printAutoplayStatus(body) {
+    if (!body?.enabled) {
+        console.log(`${WARN} auto-play is OFF (turn it on with \`pyyol autoplay on\`)`);
+        return;
+    }
+    console.log(`${OK} auto-play is ON — mode=${body.mode || "sandbox"}`);
+    const status = body.last_status || "";
+    const reason = body.last_status_reason || "";
+    if (!status) {
+        console.log("  status: starting up — no activity recorded yet (check back in a moment)");
+        return;
+    }
+    const [marker, label] = AUTOPLAY_STATUS_LABEL[status] ?? [WARN, status];
+    console.log(`  ${marker} ${label}${reason ? ` — ${reason}` : ""}`);
+    if (body.last_status_at)
+        console.log(`  as of ${body.last_status_at}`);
+    if (status === "blocked")
+        console.log("  fix the reason above (e.g. connect your agent with `pyyol run`), and it resumes automatically.");
+}
 async function cmdAutoplay(a) {
     const state = a.positionals[0];
-    if (state !== "on" && state !== "off") {
-        console.error(`${BAD} usage: pyyol autoplay on|off`);
+    if (state !== "on" && state !== "off" && state !== "status") {
+        console.error(`${BAD} usage: pyyol autoplay on|off|status`);
         return 2;
     }
     const c = creds.load();
@@ -805,6 +1039,16 @@ async function cmdAutoplay(a) {
     }
     if (str(a, "token"))
         warnArgvSecret();
+    // `pyyol autoplay status` READS the current state + why it is/isn't playing.
+    if (state === "status") {
+        const [st, resp] = await autoplayGet(api, token);
+        if (st >= 200 && st < 300) {
+            printAutoplayStatus(resp);
+            return 0;
+        }
+        console.error(`${BAD} failed (status ${st}): ${JSON.stringify(resp)}`);
+        return 1;
+    }
     const on = state === "on";
     const [m, games] = autoplayOpts(a, config.load());
     const [st, resp] = await autoplaySet(api, token, on, m, num(a, "bid", 0), games);
@@ -837,7 +1081,8 @@ async function cmdLogs(a) {
 async function cmdSimulate(a) {
     const game = str(a, "game") || "goofspiel";
     if (game !== "goofspiel") {
-        console.error(`simulate currently supports goofspiel (got '${game}'); use \`validate\` for a single-turn check of any game.`);
+        console.error(`simulate runs a full in-process match for goofspiel only (got '${game}'). ` +
+            `For ${game}, iterate with \`pyyol dev\` — sandbox practice vs house agents, no stakes.`);
         return 2;
     }
     const opponent = str(a, "opponent") || "baseline";
@@ -1230,11 +1475,14 @@ Commands:
   init <dir> [--arena goofspiel|mafia|monopoly] [--framework F] [--name N]
   dev [--matches N]                 local dev loop — SANDBOX, no stakes
   play <arena> [--ranked] [--tier]  compete; --ranked = real stakes
-  publish                           (advanced) certify for ranked
+  publish --manifest <file>         certify your agent for ranked
+  queue <game> [--tier low|mid|high | --bid N] [--list]  enter ranked matchmaking
+  wallet [--json]                   your coin balance + per-agent wallets
   replay <match_id> [--game] [--json]
   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
@@ -1249,6 +1497,9 @@ Commands:
 export async function main(argv = process.argv.slice(2)) {
     const command = argv[0];
     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.
+    maybeInstallPing(str(a, "api") || DEFAULT_API_BASE, SDK_VERSION);
     switch (command) {
         case "login":
             return cmdLogin(a);
@@ -1266,10 +1517,16 @@ 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":
             return cmdProfile(a);
+        case "wallet":
+            return cmdWallet(a);
+        case "queue":
+            return cmdQueue(a);
         case "replay":
             return cmdReplay(a);
         case "status":

package/dist/index.d.ts

@@ -21,5 +21,10 @@ export type { GoofspielSimOptions, GoofspielSimResult } from "./simulator.js";
 export { RuntimeConnector, ConnectorError, PROTOCOL_VERSION } from "./runtime.js";
 export type { RuntimeOptions, WebSocketLike, WebSocketCtor } from "./runtime.js";
 export { gameRules } from "./rules.js";
-export { Tracer, Span, currentSpan, matchTraceId } from "./telemetry.js";
-export type { TracerOptions, ModelCall } from "./telemetry.js";
+export { Tracer, Span, currentSpan, matchTraceId, currentUsage, UsageAccumulator, runTurnUsage } from "./telemetry.js";
+export type { TracerOptions, ModelCall, MoveUsage, UsageAdd } from "./telemetry.js";
+export { instrument, uninstrument, recordResponse, extractUsage, patchPrototype } from "./instrument.js";
+export { route, enableGateway, disableGateway, gatewayBaseUrl, gatewayHeaders } from "./instrument.js";
+export type { ExtractedUsage } from "./instrument.js";
+export { estimateCost, rateFor, isKnown, canonical, PRICING_VERSION } from "./pricing.js";
+export type { Rate, CostArgs } from "./pricing.js";

package/dist/index.js

@@ -17,4 +17,7 @@ export * from "./models.js";
 export { simulateGoofspiel, SimulationError } from "./simulator.js";
 export { RuntimeConnector, ConnectorError, PROTOCOL_VERSION } from "./runtime.js";
 export { gameRules } from "./rules.js";
-export { Tracer, Span, currentSpan, matchTraceId } from "./telemetry.js";
+export { Tracer, Span, currentSpan, matchTraceId, currentUsage, UsageAccumulator, runTurnUsage } from "./telemetry.js";
+export { instrument, uninstrument, recordResponse, extractUsage, patchPrototype } from "./instrument.js";
+export { route, enableGateway, disableGateway, gatewayBaseUrl, gatewayHeaders } from "./instrument.js";
+export { estimateCost, rateFor, isKnown, canonical, PRICING_VERSION } from "./pricing.js";

package/dist/install-ping.d.ts

@@ -0,0 +1,2 @@
+/** Fire the install ping at most once per version. Never throws. */
+export declare function maybeInstallPing(apiBase: string, version: string): void;

package/dist/install-ping.js

@@ -0,0 +1,42 @@
+// Anonymous, once-per-version SDK install ping (mirrors the Python SDK). The first
+// time the CLI runs a given version, fire ONE best-effort ping so the platform can
+// show adoption analytics. Anonymous ({sdk, version} only — the server resolves a
+// COUNTRY from the request and never stores the IP), fire-and-forget (never blocks
+// or errors the CLI), once per version (marker file), opt-out via PYYOL_NO_TELEMETRY
+// or the standard DO_NOT_TRACK.
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { configDir } from "./credentials.js";
+const OFF = new Set(["", "0", "false", "no", "off"]);
+function optedOut() {
+    for (const key of ["PYYOL_NO_TELEMETRY", "DO_NOT_TRACK"]) {
+        const v = (process.env[key] ?? "").trim().toLowerCase();
+        if (v && !OFF.has(v))
+            return true;
+    }
+    return false;
+}
+/** Fire the install ping at most once per version. Never throws. */
+export function maybeInstallPing(apiBase, version) {
+    if (!apiBase || optedOut())
+        return;
+    const marker = join(configDir(), `.install_pinged_${version}`);
+    try {
+        if (existsSync(marker))
+            return;
+        // Mark BEFORE firing: attempt at most once per version (no retry storm).
+        mkdirSync(configDir(), { recursive: true });
+        writeFileSync(marker, "");
+    }
+    catch {
+        return;
+    }
+    void fetch(apiBase.replace(/\/+$/, "") + "/v1/telemetry/install", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ sdk: "js", version }),
+        signal: AbortSignal.timeout(3000),
+    }).catch(() => {
+        /* telemetry must never surface to the CLI */
+    });
+}

package/dist/instrument.d.ts

@@ -0,0 +1,41 @@
+type Any = any;
+/** Enable gateway routing (called by the runtime in ranked mode; safe in tests). */
+export declare function enableGateway(agentKey: string, baseUrl: string): void;
+export declare function disableGateway(): void;
+/** The baseURL a provider client should point at, or "" if routing is off/unknown. */
+export declare function gatewayBaseUrl(provider: string): string;
+/** The X-Pyyol-* identity headers for the current turn (empty if routing off). */
+export declare function gatewayHeaders(): Record<string, string>;
+/** Point a provider client at the Pyyol Gateway (sets its baseURL). Explicit, robust
+ *  opt-in that operates on the given instance. Returns the client. No-op when routing
+ *  is off or the provider can't be determined. */
+export declare function route<T>(client: T, provider?: string): T;
+export interface ExtractedUsage {
+    model: string;
+    provider: string;
+    promptTokens: number;
+    completionTokens: number;
+    cachedTokens: number;
+    reasoningTokens: number;
+}
+/** Pull normalized usage from a provider response, or null if it has none.
+ *  Handles OpenAI Chat Completions, Anthropic Messages, and the OpenAI Responses
+ *  API; duck-typed so a plain object or an SDK object both work. */
+export declare function extractUsage(resp: Any): ExtractedUsage | null;
+/** Record usage from a provider response: compute cost, add to the turn
+ *  accumulator, and emit a Lens model_call span. Returns the extracted usage (or
+ *  null). Also the public manual hook for clients this module doesn't auto-wrap. */
+export declare function recordResponse(resp: Any, o?: {
+    provider?: string;
+    latencyMs?: number;
+}): ExtractedUsage | null;
+/** @internal Wrap `proto[method]` so its resolved return value is recorded.
+ *  Idempotent and fully guarded. Exported for tests. */
+export declare function patchPrototype(proto: Any, method: string, provider: string): boolean;
+/** Auto-capture LLM usage from installed providers. Pass e.g. `["openai"]` to limit
+ *  which are patched; default patches all supported providers that are installed.
+ *  Returns the list actually instrumented. Safe to call more than once. */
+export declare function instrument(providers?: string[]): Promise<string[]>;
+/** Restore all patched methods (primarily for tests). */
+export declare function uninstrument(): void;
+export {};