pyyol 1.2.0 → 1.3.0

package/README.md

@@ -76,12 +76,32 @@ 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 has a runnable example under
-[`examples/`](examples/). Full field-by-field reference: [games.md](../docs/games.md).
+Three games are available; each is documented in
+[the game docs](https://pyyol.com/docs/games) — also bundled in the package and
+readable offline via `gameRules()` (all three) or `gameRules("mafia")`.
 
-### Goofspiel — [`examples/goofspiel-agent.ts`](examples/goofspiel-agent.ts)
+### Goofspiel
 
 Two-player simultaneous-bid card game. The typed `GoofspielView` gives you
 `your_hand`, `legal_actions`, `current_prize`, `scores`, and a self-contained
@@ -101,7 +121,7 @@ class Lowball extends Adapter {
 export const agent = new Lowball();
 ```
 
-### Mafia — [`examples/mafia-agent.ts`](examples/mafia-agent.ts)
+### Mafia
 
 12-seat hidden-role social deduction. The typed `MafiaView` gives you `your_role`
 (capitalized, e.g. `"Mafia"`), `phase`, `alive` (`{seat: bool}`), `allies` (Mafia
@@ -132,7 +152,7 @@ class TownHunter extends Adapter {
 export const agent = new TownHunter();
 ```
 
-### Monopoly — [`examples/monopoly-agent.ts`](examples/monopoly-agent.ts)
+### Monopoly
 
 Standard Monopoly for 2–8 seats, a phase machine with near-perfect information.
 The typed `MonopolyView` gives you `phase` and `legal_actions`; the whole board is
@@ -221,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. */
@@ -21,4 +21,3 @@ export declare abstract class Adapter {
  *  class object than the one here. We match by shape (toAgent / the transport
  *  methods) so those setups still work. */
 export declare function asAgent(obj: unknown): Agent;
-//# sourceMappingURL=adapter.d.ts.map

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";
@@ -65,4 +72,3 @@ export function asAgent(obj) {
         return obj;
     throw new TypeError("expected a pyyol Agent or Adapter; export one as the variable named in pyyol.toml `entry`");
 }
-//# sourceMappingURL=adapter.js.map

package/dist/cli.d.ts

@@ -17,4 +17,3 @@ export declare function connectionToken(a: Args, c: creds.Credentials | null): {
 };
 export declare function apiRequest(method: string, url: string, token: string, body: unknown): Promise<[number, any]>;
 export declare function main(argv?: string[]): Promise<number>;
-//# sourceMappingURL=cli.d.ts.map

package/dist/cli.js

@@ -5,12 +5,14 @@
  * publish, replay, profile, leaderboard, arenas, doctor, update. Zero runtime deps:
  * uses Node 22+ globals (fetch, WebSocket) and built-ins only.
  */
-import { existsSync } from "node:fs";
+import { existsSync, realpathSync } from "node:fs";
 import { resolve } from "node:path";
-import { pathToFileURL } from "node:url";
+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_";
@@ -322,7 +333,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] } : {};"}
   }
@@ -398,6 +413,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 +456,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"))
@@ -478,6 +506,107 @@ 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;
+    }
+    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 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 +918,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 +966,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 +1008,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,7 +1402,9 @@ 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]
@@ -1249,6 +1423,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);
@@ -1270,6 +1447,10 @@ export async function main(argv = process.argv.slice(2)) {
             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":
@@ -1308,8 +1489,19 @@ export async function main(argv = process.argv.slice(2)) {
             return 2;
     }
 }
-// Run when invoked as the bin (not when imported by tests).
-const invoked = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+// Run when invoked as the bin (not when imported by tests). We must resolve
+// symlinks: npm installs the bin as node_modules/.bin/pyyol → ../pyyol/dist/cli.js,
+// so process.argv[1] is the SYMLINK path while import.meta.url is the real module
+// path. Comparing them raw (the old check) never matched under a real install, so
+// the installed `pyyol` command silently did nothing. realpathSync resolves the
+// shim to the real file so both sides match.
+let invoked = false;
+try {
+    invoked = !!process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
+}
+catch {
+    invoked = false;
+}
 if (invoked) {
     // Set exitCode and let the event loop drain — process.exit() can truncate a
     // large piped stdout (e.g. `pyyol replay … --json | jq`) mid-write.
@@ -1322,4 +1514,3 @@ if (invoked) {
         process.exitCode = 1;
     });
 }
-//# sourceMappingURL=cli.js.map

package/dist/config.d.ts

@@ -25,4 +25,3 @@ export declare function save(cfg: Config, directory?: string): string;
 export declare function setAgentId(agentId: string, path?: string): boolean;
 /** Return a list of human-readable problems (empty = valid). */
 export declare function validate(cfg: Config): string[];
-//# sourceMappingURL=config.d.ts.map

package/dist/config.js

@@ -157,4 +157,3 @@ export function validate(cfg) {
     }
     return problems;
 }
-//# sourceMappingURL=config.js.map

package/dist/credentials.d.ts

@@ -10,4 +10,3 @@ export declare function configDir(): string;
 export declare function save(creds: Credentials): "keychain" | "file";
 export declare function load(): Credentials | null;
 export declare function clear(): boolean;
-//# sourceMappingURL=credentials.d.ts.map

package/dist/credentials.js

@@ -172,4 +172,3 @@ export function clear() {
     }
     return removed;
 }
-//# sourceMappingURL=credentials.js.map

package/dist/index.d.ts

@@ -21,6 +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";
-//# sourceMappingURL=index.d.ts.map
+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,5 +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";
-//# sourceMappingURL=index.js.map
+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 {};