pyyol 1.7.0 → 1.9.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
@@ -626,7 +636,31 @@ async function cmdWallet(a) {
         console.error(`${BAD} not logged in — run \`pyyol login\` first.`);
         return 2;
     }
+    // AN AGENT KEY CANNOT READ THE OWNER'S TREASURY, and must not be sent here.
+    //
+    // The fallback chain above ends at PYYOL_TOKEN, which the deployment docs define as
+    // the sk_arena_… AGENT key for CI and containers. That key resolves server-side to
+    // its owner's user id, so this command used to work with it — an agent credential
+    // reading its owner's full balance and ledger. The arena now requires user scope on
+    // /v1/user/wallet and answers 403, which would surface here as an opaque
+    // "could not fetch wallet (403)".
+    //
+    // Refusing locally, by shape, is better than relaying that: it names the credential
+    // actually in play (easy to miss when it arrives from the environment rather than a
+    // flag) and says which one the command needs.
+    if (token.startsWith(AGENT_KEY_PREFIX)) {
+        console.error(`${BAD} \`pyyol wallet\` shows the OWNER's treasury, so it needs your dashboard login — ` +
+            `not an agent key.\n` +
+            `    The token in use is an agent key (sk_arena_…), probably from $PYYOL_TOKEN.\n` +
+            `    Run \`pyyol login\` on this machine, or unset PYYOL_TOKEN for this command.`);
+        return 2;
+    }
     const [st, w] = await apiGet(`${base}/v1/user/wallet`, token);
+    if (st === 403) {
+        console.error(`${BAD} this credential is not allowed to read the owner's treasury. ` +
+            `Sign in with \`pyyol login\` and try again.`);
+        return 1;
+    }
     if (st !== 200) {
         console.error(`${BAD} could not fetch wallet (${st}): ${JSON.stringify(w)}`);
         return 1;
@@ -772,9 +806,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/instrument.d.ts

@@ -6,6 +6,13 @@ export declare function disableGateway(): void;
 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>;
+/** The provider for one instrumented call.
+ *
+ *  `patchedAs` is the SDK we wrapped (which wire format this is). The client's baseURL
+ *  is consulted first and wins. A baseURL pointing at the PYYOL GATEWAY is not used for
+ *  attribution — it says the call was proxied, not who served it — so the upstream is
+ *  recovered from the gateway path by matching it back against PROVIDER_PATH. */
+export declare function resolveCallProvider(resource: Any, patchedAs: 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. */
@@ -18,9 +25,6 @@ export interface ExtractedUsage {
     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

package/dist/instrument.js

@@ -16,6 +16,7 @@
 // pass `stream_options: { include_usage: true }` and record manually, or use
 // non-streaming calls for automatic capture.
 import { estimateCost } from "./pricing.js";
+import * as providers from "./providers.js";
 import { currentSpan, currentUsage } from "./telemetry.js";
 // [prototype, method, original] for uninstrument().
 const PATCHED = [];
@@ -54,11 +55,15 @@ export function gatewayHeaders() {
     return h;
 }
 function detectProvider(client) {
-    const name = (client?.constructor?.name ?? "").toLowerCase();
-    if (name.includes("openai"))
-        return "openai";
-    if (name.includes("anthropic"))
-        return "anthropic";
+    // baseURL first: most of the ecosystem speaks the OpenAI wire format, so an OpenAI
+    // client pointed at http://localhost:11434/v1 IS Ollama — and calling it "openai"
+    // would price a model on the developer's own GPU at OpenAI's rates.
+    const byUrl = providers.fromBaseUrl(String(client?.baseURL ?? ""));
+    if (byUrl)
+        return byUrl;
+    const byName = providers.fromName(client?.constructor?.name ?? "");
+    if (byName)
+        return byName;
     // duck-type fallback
     if (client?.chat?.completions)
         return "openai";
@@ -66,6 +71,24 @@ function detectProvider(client) {
         return "anthropic";
     return "";
 }
+/** The provider for one instrumented call.
+ *
+ *  `patchedAs` is the SDK we wrapped (which wire format this is). The client's baseURL
+ *  is consulted first and wins. A baseURL pointing at the PYYOL GATEWAY is not used for
+ *  attribution — it says the call was proxied, not who served it — so the upstream is
+ *  recovered from the gateway path by matching it back against PROVIDER_PATH. */
+export function resolveCallProvider(resource, patchedAs) {
+    const base = clientBaseUrl(resource);
+    if (base && gateway.base && base.startsWith(gateway.base)) {
+        const tail = base.slice(gateway.base.length);
+        for (const [provider, path] of Object.entries(PROVIDER_PATH)) {
+            if (tail.startsWith(path))
+                return provider;
+        }
+        return patchedAs;
+    }
+    return providers.resolve({ baseUrl: base, fallback: patchedAs });
+}
 /** 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. */
@@ -130,10 +153,71 @@ function get(obj, name, dflt) {
 /** 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. */
+/** Ollama's native shape: no `usage` object at all, counts at the top level.
+ *  Without this an agent running Ollama reported zero tokens forever — it looked
+ *  instrumented and measured nothing, and no bill ever arrives to contradict a zero. */
+function extractOllama(resp) {
+    const prompt = get(resp, "prompt_eval_count");
+    const completion = get(resp, "eval_count");
+    if (prompt === undefined && completion === undefined)
+        return null;
+    return {
+        model: get(resp, "model", "") || "",
+        provider: providers.OLLAMA,
+        promptTokens: Math.trunc(prompt || 0),
+        completionTokens: Math.trunc(completion || 0),
+        cachedTokens: 0,
+        reasoningTokens: 0,
+    };
+}
+/** Google Gemini: counts hang off `usageMetadata` (camelCase in the JS SDK). */
+function extractGoogle(resp) {
+    const um = get(resp, "usageMetadata") ?? get(resp, "usage_metadata");
+    if (um == null)
+        return null;
+    const prompt = get(um, "promptTokenCount", get(um, "prompt_token_count", 0)) || 0;
+    const completion = get(um, "candidatesTokenCount", get(um, "candidates_token_count", 0)) || 0;
+    if (!prompt && !completion)
+        return null;
+    return {
+        model: get(resp, "modelVersion", "") || get(resp, "model", "") || "",
+        provider: providers.GOOGLE,
+        promptTokens: Math.trunc(prompt),
+        completionTokens: Math.trunc(completion),
+        cachedTokens: Math.trunc(get(um, "cachedContentTokenCount", get(um, "cached_content_token_count", 0)) || 0),
+        reasoningTokens: Math.trunc(get(um, "thoughtsTokenCount", get(um, "thoughts_token_count", 0)) || 0),
+    };
+}
+/** Cohere nests counts under `meta.tokens`. */
+function extractCohere(resp) {
+    const tokens = get(get(resp, "meta"), "tokens");
+    if (tokens == null)
+        return null;
+    const prompt = get(tokens, "inputTokens", get(tokens, "input_tokens", 0)) || 0;
+    const completion = get(tokens, "outputTokens", get(tokens, "output_tokens", 0)) || 0;
+    if (!prompt && !completion)
+        return null;
+    return {
+        model: get(resp, "model", "") || "",
+        provider: "cohere",
+        promptTokens: Math.trunc(prompt),
+        completionTokens: Math.trunc(completion),
+        cachedTokens: 0,
+        reasoningTokens: 0,
+    };
+}
 export function extractUsage(resp) {
     const u = get(resp, "usage");
-    if (u == null)
+    if (u == null) {
+        // Shapes that carry no `usage` at all. Only consulted here, so they can never
+        // hijack a normal OpenAI or Anthropic response.
+        for (const extractor of [extractOllama, extractGoogle, extractCohere]) {
+            const info = extractor(resp);
+            if (info !== null)
+                return info;
+        }
         return null;
+    }
     const model = get(resp, "model", "") || "";
     let prompt = get(u, "prompt_tokens");
     let completion = get(u, "completion_tokens");
@@ -175,6 +259,10 @@ export function recordResponse(resp, o = {}) {
         return null;
     const provider = o.provider || info.provider;
     const cost = estimateCost(info.model, {
+        // WHO served it, not just what was served: an open-weight model is free on your
+        // own hardware and billed when a hosted provider serves it, and the model id is
+        // identical either way.
+        provider,
         promptTokens: info.promptTokens,
         completionTokens: info.completionTokens,
         cachedTokens: info.cachedTokens,
@@ -213,7 +301,9 @@ export function patchPrototype(proto, method, provider) {
         const start = Date.now();
         const resp = await orig.apply(this, args);
         try {
-            recordResponse(resp, { provider, latencyMs: Date.now() - start });
+            // Resolve from the CLIENT's baseURL — the wire format we patched is not the
+            // same thing as who actually served the call.
+            recordResponse(resp, { provider: resolveCallProvider(this, provider), latencyMs: Date.now() - start });
         }
         catch {
             // instrumentation must never break the dev's call

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/pricing.d.ts

@@ -7,10 +7,13 @@ export interface Rate {
     /** USD per 1M cached (prompt-cache read) input tokens; defaults to `input`. */
     cachedInput?: number;
 }
-/** Map a raw model string to a canonical table key, or null if unknown. */
-export declare function canonical(model: string): string | null;
-/** The Rate for a model (falls back to a mid-tier rate for unknown models). */
-export declare function rateFor(model: string): Rate;
+/** Map a raw model string to a canonical table key, or null if unknown.
+ *  `provider` scopes the lookup: provider-specific rules win, because they are the
+ *  only ones that know a hosted bill exists for a model that would otherwise be free. */
+export declare function canonical(model: string, provider?: string): string | null;
+/** The Rate for a model (falls back to a mid-tier rate for unknown models).
+ *  `provider` scopes the lookup so a self-hosted model stays at $0. */
+export declare function rateFor(model: string, provider?: string): Rate;
 /** True if the model maps to an explicit table entry (not the fallback). */
 export declare function isKnown(model: string): boolean;
 export interface CostArgs {
@@ -18,6 +21,9 @@ export interface CostArgs {
     completionTokens?: number;
     cachedTokens?: number;
     reasoningTokens?: number;
+    /** WHO served the call. Decides whether there is a bill at all: the same model id
+     *  is billed on a hosted provider and free on the developer's own hardware. */
+    provider?: string;
 }
 /**
  * USD cost estimate for one model call. `cachedTokens` are a subset of

package/dist/pricing.js

@@ -6,6 +6,7 @@
 // authoritative cost comes from the Pyyol Gateway). When a provider changes prices,
 // bump PRICING_VERSION and update the table — never edit silently, so a cost can
 // always be traced to the table that produced it.
+import { isSelfHosted } from "./providers.js";
 // Bump whenever any rate below changes. Stamped onto every estimate.
 export const PRICING_VERSION = "2026-07-24";
 // Canonical model id -> Rate. Lowercase, provider-agnostic.
@@ -29,12 +30,32 @@ const TABLE = {
     // Google (Gemini)
     "gemini-flash": { input: 0.15, output: 0.6, cachedInput: 0.0375 },
     "gemini-pro": { input: 1.25, output: 5.0, cachedInput: 0.3125 },
+    // Open-weight served by a HOSTED provider — there IS a per-token bill.
+    //
+    // "Open weight" does not mean "free". Groq bills per token like anyone else, and
+    // recording $0 for it meant a Groq-backed agent reported no cost at all on a platform
+    // that advertises verified LLM cost tracking. (The Python SDK already scoped these by
+    // provider; this table did not, so the two disagreed about the same call.)
+    "groq-llama-8b": { input: 0.05, output: 0.08 },
+    "groq-llama-70b": { input: 0.59, output: 0.79 },
     // Open-weight / self-hosted (no per-token bill)
     llama: { input: 0.0, output: 0.0 },
     mistral: { input: 0.0, output: 0.0 },
     qwen: { input: 0.0, output: 0.0 },
     deepseek: { input: 0.27, output: 1.1 },
 };
+// Provider-scoped rules, checked BEFORE the name rules. An open-weight model is $0
+// when you run it yourself and very much not $0 when a hosted provider serves it — and
+// the model id cannot tell you which, since "llama-3.3-70b" is the same string either
+// way. Only an explicitly provider-attributed call gets a hosted rate.
+const PROVIDER_RULES = {
+    groq: [
+        ["llama-3.1-8b", "groq-llama-8b"],
+        ["llama-3.1-70b", "groq-llama-70b"],
+        ["llama-3.3-70b", "groq-llama-70b"],
+        ["llama-4", "groq-llama-70b"],
+    ],
+};
 // Last-resort rate for an unmapped model (never silently $0 unless open-weight).
 const FALLBACK = { input: 0.5, output: 1.5 };
 // Ordered [substring, canonical] rules; first match wins, most specific first.
@@ -72,11 +93,17 @@ const RULES = [
     ["qwen", "qwen"],
     ["deepseek", "deepseek"],
 ];
-/** Map a raw model string to a canonical table key, or null if unknown. */
-export function canonical(model) {
+/** Map a raw model string to a canonical table key, or null if unknown.
+ *  `provider` scopes the lookup: provider-specific rules win, because they are the
+ *  only ones that know a hosted bill exists for a model that would otherwise be free. */
+export function canonical(model, provider = "") {
     const m = (model ?? "").trim().toLowerCase();
     if (!m)
         return null;
+    for (const [needle, key] of PROVIDER_RULES[provider.trim().toLowerCase()] ?? []) {
+        if (m.includes(needle))
+            return key;
+    }
     if (m in TABLE)
         return m;
     for (const [needle, key] of RULES)
@@ -84,9 +111,19 @@ export function canonical(model) {
             return key;
     return null;
 }
-/** The Rate for a model (falls back to a mid-tier rate for unknown models). */
-export function rateFor(model) {
-    const key = canonical(model);
+// Rate for a model the developer serves themselves. Not a guess and not a fallback —
+// there is no per-token bill, so any non-zero number here would be fiction.
+const FREE = { input: 0, output: 0, cachedInput: 0 };
+/** The Rate for a model (falls back to a mid-tier rate for unknown models).
+ *  `provider` scopes the lookup so a self-hosted model stays at $0. */
+export function rateFor(model, provider = "") {
+    // Self-hosted first, ahead of every name-based rule. The model id cannot tell you
+    // who served it — "llama-3.3-70b" is the same string on Groq's bill and on your own
+    // GPU — so without this an Ollama user is charged Groq's rates for electricity they
+    // already paid for, and the unknown-model fallback would invent a bill outright.
+    if (isSelfHosted(provider.trim().toLowerCase()))
+        return FREE;
+    const key = canonical(model, provider);
     return key !== null ? TABLE[key] : FALLBACK;
 }
 /** True if the model maps to an explicit table entry (not the fallback). */
@@ -99,7 +136,7 @@ export function isKnown(model) {
  * tokens already counted in `completionTokens` (kept for reporting).
  */
 export function estimateCost(model, a = {}) {
-    const rate = rateFor(model);
+    const rate = rateFor(model, a.provider ?? "");
     const prompt = Math.max(0, a.promptTokens ?? 0);
     const completion = Math.max(0, a.completionTokens ?? 0);
     const cached = Math.max(0, Math.min(a.cachedTokens ?? 0, prompt));

package/dist/providers.d.ts

@@ -0,0 +1,27 @@
+export declare const OPENAI = "openai";
+export declare const ANTHROPIC = "anthropic";
+export declare const GOOGLE = "google";
+export declare const GROQ = "groq";
+export declare const OLLAMA = "ollama";
+export declare const SELF_HOSTED = "self-hosted";
+/** True for loopback, link-local and private-network addresses, and for the hostnames
+ *  that conventionally mean "this machine". A model served from one of these has no
+ *  per-token bill, which is why it is worth detecting even when unnamed. */
+export declare function isLocalHost(host: string): boolean;
+/** Provider key implied by a base URL, or "" when the host says nothing. A local
+ *  address always resolves to SOMETHING — never "" — because "we could not tell" and
+ *  "it runs on your own hardware for free" must not be the same answer. */
+export declare function fromBaseUrl(baseUrl: string): string;
+/** Provider key implied by a client's constructor or module name, or "". */
+export declare function fromName(name: string): string;
+/** The provider serving this call. baseURL wins over the name: the name only says
+ *  which WIRE FORMAT the client speaks, while the URL says who is on the other end —
+ *  and for every OpenAI-compatible endpoint those are different answers. */
+export declare function resolve(o: {
+    name?: string;
+    baseUrl?: string;
+    fallback?: string;
+}): string;
+/** True when the provider runs on the developer's own hardware, so its tokens carry
+ *  no per-token bill. */
+export declare function isSelfHosted(provider: string): boolean;

package/dist/providers.js

@@ -0,0 +1,140 @@
+// Which provider is actually serving this call?
+//
+// Identifying the provider by the client CLASS is not enough, and getting it wrong is
+// not cosmetic: the provider decides whether a call is priced or free, and it is half
+// of the model attribution the public benchmark ranks on.
+//
+// The problem is that most of the ecosystem speaks the OpenAI wire format. Ollama,
+// vLLM, LM Studio, llama.cpp, OpenRouter, Together, Groq, DeepSeek, Azure and others
+// are all routinely driven through the OpenAI SDK with nothing changed but `baseURL`.
+// Classifying those by constructor name calls every one of them "openai" — pricing a
+// locally-served Llama at OpenAI's rates and filing it under the wrong vendor.
+//
+// Resolution order: baseURL host → module/constructor name → caller's fallback.
+// Anything on a loopback or private address is SELF-HOSTED even when the runtime is
+// unrecognised: it has no per-token bill, and "unknown" would price it as if it did.
+//
+// Keep the provider keys here in step with `internal/rating/taxonomy.go` and the
+// Python SDK's `providers.py` — the backend classifies exactly these strings.
+export const OPENAI = "openai";
+export const ANTHROPIC = "anthropic";
+export const GOOGLE = "google";
+export const GROQ = "groq";
+export const OLLAMA = "ollama";
+export const SELF_HOSTED = "self-hosted";
+/** host substring -> provider key. Most specific first. */
+const HOST_RULES = [
+    ["api.openai.com", OPENAI],
+    ["openai.azure.com", "azure"],
+    ["api.anthropic.com", ANTHROPIC],
+    ["bedrock-runtime", "bedrock"],
+    ["bedrock", "bedrock"],
+    ["generativelanguage.googleapis.com", GOOGLE],
+    ["aiplatform.googleapis.com", "vertex"],
+    ["api.groq.com", GROQ],
+    ["openrouter.ai", "openrouter"],
+    ["api.together.xyz", "together"],
+    ["together.ai", "together"],
+    ["api.fireworks.ai", "fireworks"],
+    ["api.deepinfra.com", "deepinfra"],
+    ["api.mistral.ai", "mistral"],
+    ["api.deepseek.com", "deepseek"],
+    ["api.cohere.ai", "cohere"],
+    ["api.cohere.com", "cohere"],
+    ["api.x.ai", "xai"],
+    ["api.perplexity.ai", "perplexity"],
+    ["api.cerebras.ai", "cerebras"],
+    ["api.sambanova.ai", "sambanova"],
+    ["api.studio.nebius", "nebius"],
+    ["api.hyperbolic.xyz", "hyperbolic"],
+    ["api.moonshot", "moonshot"],
+    ["dashscope.aliyuncs.com", "alibaba"],
+];
+/** Default ports of the common local runtimes. */
+const LOCAL_PORTS = {
+    "11434": OLLAMA,
+    "1234": "lmstudio",
+    "8000": "vllm",
+    "8080": "llamacpp",
+    "5000": "localai",
+    "3000": SELF_HOSTED,
+    "9997": SELF_HOSTED,
+};
+/** constructor/module-name substring -> provider. "openai" LAST: several packages
+ *  embed it in their own names. */
+const NAME_RULES = [
+    ["ollama", OLLAMA],
+    ["anthropic", ANTHROPIC],
+    ["groq", GROQ],
+    ["mistral", "mistral"],
+    ["cohere", "cohere"],
+    ["googlegenai", GOOGLE],
+    ["generativeai", GOOGLE],
+    ["google", GOOGLE],
+    ["openai", OPENAI],
+];
+const SELF_HOSTED_KEYS = new Set([OLLAMA, SELF_HOSTED, "vllm", "lmstudio", "llamacpp", "localai", "tgi"]);
+function parse(baseUrl) {
+    if (!baseUrl)
+        return { host: "", port: "" };
+    const withScheme = baseUrl.includes("://") ? baseUrl : `http://${baseUrl}`;
+    try {
+        const u = new URL(withScheme);
+        return { host: u.hostname.toLowerCase(), port: u.port };
+    }
+    catch {
+        return { host: "", port: "" };
+    }
+}
+/** True for loopback, link-local and private-network addresses, and for the hostnames
+ *  that conventionally mean "this machine". A model served from one of these has no
+ *  per-token bill, which is why it is worth detecting even when unnamed. */
+export function isLocalHost(host) {
+    if (!host)
+        return false;
+    if (["localhost", "127.0.0.1", "::1", "0.0.0.0", "host.docker.internal"].includes(host))
+        return true;
+    if (host.endsWith(".local") || host.endsWith(".internal"))
+        return true;
+    // IPv4 private ranges: 10/8, 192.168/16, 172.16–31/12, 127/8, 169.254/16.
+    const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
+    if (!m)
+        return false;
+    const [a, b] = [Number(m[1]), Number(m[2])];
+    return a === 10 || a === 127 || (a === 192 && b === 168) || (a === 172 && b >= 16 && b <= 31) || (a === 169 && b === 254);
+}
+/** Provider key implied by a base URL, or "" when the host says nothing. A local
+ *  address always resolves to SOMETHING — never "" — because "we could not tell" and
+ *  "it runs on your own hardware for free" must not be the same answer. */
+export function fromBaseUrl(baseUrl) {
+    const { host, port } = parse(baseUrl);
+    if (!host)
+        return "";
+    for (const [needle, provider] of HOST_RULES) {
+        if (host.includes(needle))
+            return provider;
+    }
+    if (isLocalHost(host))
+        return LOCAL_PORTS[port] ?? SELF_HOSTED;
+    return "";
+}
+/** Provider key implied by a client's constructor or module name, or "". */
+export function fromName(name) {
+    const n = (name || "").toLowerCase().replace(/[^a-z]/g, "");
+    for (const [needle, provider] of NAME_RULES) {
+        if (n.includes(needle))
+            return provider;
+    }
+    return "";
+}
+/** The provider serving this call. baseURL wins over the name: the name only says
+ *  which WIRE FORMAT the client speaks, while the URL says who is on the other end —
+ *  and for every OpenAI-compatible endpoint those are different answers. */
+export function resolve(o) {
+    return fromBaseUrl(o.baseUrl ?? "") || fromName(o.name ?? "") || o.fallback || "";
+}
+/** True when the provider runs on the developer's own hardware, so its tokens carry
+ *  no per-token bill. */
+export function isSelfHosted(provider) {
+    return SELF_HOSTED_KEYS.has(provider);
+}

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.7.0";
+export declare const SDK_VERSION = "1.9.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.7.0";
+export const SDK_VERSION = "1.9.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pyyol",
-  "version": "1.7.0",
+  "version": "1.9.0",
   "description": "Official JS/TS SDK for pyyol — run AI game-playing agents locally over a WebSocket (Beta)",
   "type": "module",
   "main": "dist/index.js",

package/rules/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** —
@@ -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.
@@ -1158,7 +1172,55 @@ JSON (YAML also accepted). All keys are **camelCase**.
 | `runtime.maxMemory` | string, e.g. `"256Mi"` |
 | `sdk.language` | required (`python` / `js`) |
 | `contact.email` | valid email |
-| `model` | **optional**; if present, `provider` + `model` required. Always shown as *developer-declared* (the platform can't verify a remote model). |
+| `model` | **optional**, but scaffolded by `pyyol init` — see below. If present, `provider` + `model` are both required. |
+
+## How your model is identified on the benchmark
+
+The [model board](https://pyyol.com/models) ranks by the model that actually played
+each match, resolved at whichever of these tiers it can reach — best first:
+
+| tier | source | can you misreport it? |
+| --- | --- | --- |
+| **verified** | the model name in the provider's own API response, read by the Pyyol gateway | no |
+| **observed** | the model your SDK reported for the calls it made that turn | yes, but per call |
+| **claimed** | this `model:` block | yes |
+
+Two practical consequences:
+
+- Route your LLM calls through the gateway (`/gw/openai/...`, `/gw/anthropic/...`) and
+  your rows show as **verified** — and your cost-per-win is computed from spend the
+  server measured rather than from a number your agent reported.
+- Fill the `model:` block in anyway. It is the fallback for any match where neither
+  the gateway nor the SDK saw a model name, and an agent with none can disappear from
+  the board entirely. `pyyol init` writes placeholders (`your-provider` /
+  `your-model`) — replace them, because an unedited block is not a useful claim.
+
+### Running something other than OpenAI or Anthropic
+
+`pyyol.instrument()` identifies your model whatever serves it. It resolves the
+provider from the client's **base URL** first, then its SDK, because almost everything
+speaks the OpenAI wire format — so an OpenAI client pointed somewhere else is not an
+OpenAI call, and treating it as one would price it wrong.
+
+| you run | what happens |
+| --- | --- |
+| OpenAI / Anthropic SDKs | captured natively |
+| **Ollama** (native client or `ollama.chat`) | captured, reported as `ollama`, priced at **$0** |
+| OpenAI SDK → `localhost:11434` / `:1234` / `:8000` / `:8080` | detected as ollama / LM Studio / vLLM / llama.cpp, priced at **$0** |
+| OpenAI SDK → any private or loopback address | `self-hosted`, priced at **$0** |
+| OpenAI SDK → Groq, OpenRouter, Together, DeepSeek, Fireworks, xAI, Perplexity, Cerebras, Azure… | detected by host and priced as that provider |
+| Google Gemini (`google-genai` or `google-generativeai`) | captured natively |
+| Cohere | captured natively |
+
+Self-hosted models are recorded at **$0 per token** — you already paid for the
+hardware — but their tokens, latency and move quality are measured exactly like
+anyone else's, so they compete on the board on equal terms. The board also groups by
+open-weights vs proprietary and hosted vs self-hosted, so you can see how your setup
+compares to the camp rather than only to individual models.
+
+If you use a client the SDK cannot recognise, call `pyyol.record_response(resp,
+provider="...")` yourself, or `pyyol.route(client, provider="...")` to name it
+explicitly.
 
 ## The endpoint secret
 

package/skill/references/setup.md

@@ -12,7 +12,11 @@ pyyol login
 `login` opens a browser, authenticates you, and stores **two** credentials on this
 machine — they are not interchangeable:
 
-- **agent key** (`sk_arena_…`) — long-lived, agent-scope. Plays matches.
+- **agent key** (`sk_arena_…`) — long-lived, agent-scope. Plays matches. Named after
+  this machine, and one name holds one live key: logging in elsewhere issues that
+  machine its own key and does not touch this one. For a server or CI runner (no
+  browser), issue a key from the dashboard under its own name and pass it as
+  `PYYOL_TOKEN` — not `PYYOL_SECRET`, which is the unrelated legacy endpoint secret.
 - **dashboard token** — your session. Owner-scope actions only: publish, wallet,
   withdrawals.