pyyol 1.2.1 → 1.3.0

package/dist/instrument.js

@@ -0,0 +1,276 @@
+// Automatic, zero-config LLM usage capture (mirrors the Python SDK's instrument.py).
+//
+// Call `instrument()` once at startup and the SDK transparently wraps the OpenAI
+// and Anthropic clients: every non-streaming completion has its REAL model, token
+// counts, and cost recorded from the provider's own response — no boilerplate. The
+// runtime auto-attaches the captured usage to the outgoing move, so it reaches the
+// arena benchmark even with Lens disabled.
+//
+//   import { instrument } from "pyyol";
+//   await instrument();            // once, at startup
+//
+// Design: never imports a provider that isn't installed; every capture path is
+// guarded so instrumentation can never throw into the developer's call; idempotent;
+// uninstrument() restores originals (used by tests).
+// Limitation (Phase 2): streaming responses carry no usage on the returned stream;
+// pass `stream_options: { include_usage: true }` and record manually, or use
+// non-streaming calls for automatic capture.
+import { estimateCost } from "./pricing.js";
+import { currentSpan, currentUsage } from "./telemetry.js";
+// [prototype, method, original] for uninstrument().
+const PATCHED = [];
+// --- Verified-tier gateway routing (Phase 4c) ---------------------------------
+// When routing is enabled, the wrapper injects the Pyyol identity headers
+// (X-Pyyol-Key/Match/Turn) into each LLM call's request options so the Pyyol Gateway
+// can attribute the server-observed usage; route() points a client's baseURL at the
+// gateway. Together, ranked LLM traffic flows through the gateway with one opt-in line.
+const gateway = { key: "", base: "" };
+/** Enable gateway routing (called by the runtime in ranked mode; safe in tests). */
+export function enableGateway(agentKey, baseUrl) {
+    gateway.key = agentKey ?? "";
+    gateway.base = (baseUrl ?? "").replace(/\/+$/, "");
+}
+export function disableGateway() {
+    gateway.key = "";
+    gateway.base = "";
+}
+const PROVIDER_PATH = { openai: "/gw/openai/v1", anthropic: "/gw/anthropic" };
+/** The baseURL a provider client should point at, or "" if routing is off/unknown. */
+export function gatewayBaseUrl(provider) {
+    const path = PROVIDER_PATH[provider];
+    return gateway.base && path ? gateway.base + path : "";
+}
+/** The X-Pyyol-* identity headers for the current turn (empty if routing off). */
+export function gatewayHeaders() {
+    if (!gateway.key)
+        return {};
+    const h = { "X-Pyyol-Key": gateway.key };
+    const acc = currentUsage();
+    if (acc) {
+        if (acc.matchId)
+            h["X-Pyyol-Match"] = acc.matchId;
+        h["X-Pyyol-Turn"] = String(acc.turn ?? 0);
+    }
+    return h;
+}
+function detectProvider(client) {
+    const name = (client?.constructor?.name ?? "").toLowerCase();
+    if (name.includes("openai"))
+        return "openai";
+    if (name.includes("anthropic"))
+        return "anthropic";
+    // duck-type fallback
+    if (client?.chat?.completions)
+        return "openai";
+    if (client?.messages)
+        return "anthropic";
+    return "";
+}
+/** 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 function route(client, provider) {
+    const prov = provider ?? detectProvider(client);
+    const url = prov ? gatewayBaseUrl(prov) : "";
+    if (url) {
+        try {
+            client.baseURL = url;
+        }
+        catch {
+            // ignore — never break the caller
+        }
+    }
+    return client;
+}
+/** Best-effort read of the baseURL the provider client will actually call. The patched
+ *  method is bound to a resource whose `_client` holds the configured baseURL. */
+function clientBaseUrl(resource) {
+    try {
+        const base = resource?._client?.baseURL;
+        return base ? String(base).replace(/\/+$/, "") : "";
+    }
+    catch {
+        return "";
+    }
+}
+/** True only when this call's client is pointed at the Pyyol Gateway. Guards header
+ *  injection so the X-Pyyol-Key credential is NEVER sent to a third-party provider
+ *  (e.g. a client the dev forgot to route()) — only to the gateway that issued it. */
+function targetsGateway(resource) {
+    if (!gateway.base)
+        return false;
+    const base = clientBaseUrl(resource);
+    return !!base && base.startsWith(gateway.base);
+}
+// injectGatewayHeaders merges the Pyyol identity headers into an LLM call's request
+// options. JS SDKs take per-request headers via a SECOND options arg
+// (create(body, { headers })), so we ensure args[1].headers carries them. Dev-supplied
+// headers win. No-op when routing is off OR when the call does not target the gateway.
+function injectGatewayHeaders(resource, args) {
+    if (!targetsGateway(resource))
+        return;
+    const headers = gatewayHeaders();
+    if (!Object.keys(headers).length)
+        return;
+    try {
+        const opts = (args[1] && typeof args[1] === "object" ? args[1] : {});
+        opts.headers = { ...headers, ...(opts.headers ?? {}) }; // dev-supplied overrides
+        args[1] = opts;
+    }
+    catch {
+        // never break the dev's call
+    }
+}
+function get(obj, name, dflt) {
+    if (obj == null)
+        return dflt;
+    const v = obj[name];
+    return v === undefined ? dflt : v;
+}
+/** 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 function extractUsage(resp) {
+    const u = get(resp, "usage");
+    if (u == null)
+        return null;
+    const model = get(resp, "model", "") || "";
+    let prompt = get(u, "prompt_tokens");
+    let completion = get(u, "completion_tokens");
+    const styleOpenAiChat = prompt !== undefined || completion !== undefined;
+    if (prompt === undefined)
+        prompt = get(u, "input_tokens", 0);
+    if (completion === undefined)
+        completion = get(u, "output_tokens", 0);
+    let cached = 0;
+    let reasoning = 0;
+    const ptd = get(u, "prompt_tokens_details");
+    if (ptd != null)
+        cached = get(ptd, "cached_tokens", 0) || 0;
+    const ctd = get(u, "completion_tokens_details");
+    if (ctd != null)
+        reasoning = get(ctd, "reasoning_tokens", 0) || 0;
+    if (!cached)
+        cached = get(u, "cache_read_input_tokens", 0) || 0;
+    let provider = "";
+    if (styleOpenAiChat)
+        provider = "openai";
+    else if (get(u, "input_tokens") !== undefined)
+        provider = "anthropic";
+    return {
+        model,
+        provider,
+        promptTokens: Math.trunc(prompt || 0),
+        completionTokens: Math.trunc(completion || 0),
+        cachedTokens: Math.trunc(cached || 0),
+        reasoningTokens: Math.trunc(reasoning || 0),
+    };
+}
+/** 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 function recordResponse(resp, o = {}) {
+    const info = extractUsage(resp);
+    if (info === null)
+        return null;
+    const provider = o.provider || info.provider;
+    const cost = estimateCost(info.model, {
+        promptTokens: info.promptTokens,
+        completionTokens: info.completionTokens,
+        cachedTokens: info.cachedTokens,
+        reasoningTokens: info.reasoningTokens,
+    });
+    currentUsage()?.add({
+        model: info.model,
+        provider,
+        promptTokens: info.promptTokens,
+        completionTokens: info.completionTokens,
+        reasoningTokens: info.reasoningTokens,
+        cachedTokens: info.cachedTokens,
+        estimatedCost: cost,
+    });
+    currentSpan().logModelCall({
+        provider,
+        model: info.model,
+        promptTokens: info.promptTokens,
+        completionTokens: info.completionTokens,
+        totalTokens: info.promptTokens + info.completionTokens,
+        estimatedCost: cost,
+        latencyMs: o.latencyMs ?? 0,
+    });
+    return info;
+}
+/** @internal Wrap `proto[method]` so its resolved return value is recorded.
+ *  Idempotent and fully guarded. Exported for tests. */
+export function patchPrototype(proto, method, provider) {
+    if (proto == null)
+        return false;
+    const orig = proto[method];
+    if (typeof orig !== "function" || orig._pyyolInstrumented)
+        return false;
+    const wrapped = async function (...args) {
+        injectGatewayHeaders(this, args);
+        const start = Date.now();
+        const resp = await orig.apply(this, args);
+        try {
+            recordResponse(resp, { provider, latencyMs: Date.now() - start });
+        }
+        catch {
+            // instrumentation must never break the dev's call
+        }
+        return resp;
+    };
+    wrapped._pyyolInstrumented = true;
+    proto[method] = wrapped;
+    PATCHED.push([proto, method, orig]);
+    return true;
+}
+async function tryImport(spec) {
+    try {
+        return await import(spec);
+    }
+    catch {
+        return null;
+    }
+}
+async function patchOpenAI() {
+    let patched = false;
+    const chat = await tryImport("openai/resources/chat/completions");
+    if (chat?.Completions?.prototype)
+        patched = patchPrototype(chat.Completions.prototype, "create", "openai") || patched;
+    const responses = await tryImport("openai/resources/responses");
+    if (responses?.Responses?.prototype)
+        patched = patchPrototype(responses.Responses.prototype, "create", "openai") || patched;
+    return patched;
+}
+async function patchAnthropic() {
+    let patched = false;
+    const messages = await tryImport("@anthropic-ai/sdk/resources/messages");
+    if (messages?.Messages?.prototype)
+        patched = patchPrototype(messages.Messages.prototype, "create", "anthropic") || patched;
+    return patched;
+}
+/** 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 async function instrument(providers) {
+    const want = new Set(providers ?? ["openai", "anthropic"]);
+    const done = [];
+    if (want.has("openai") && (await patchOpenAI()))
+        done.push("openai");
+    if (want.has("anthropic") && (await patchAnthropic()))
+        done.push("anthropic");
+    return done;
+}
+/** Restore all patched methods (primarily for tests). */
+export function uninstrument() {
+    while (PATCHED.length) {
+        const [proto, method, orig] = PATCHED.pop();
+        try {
+            proto[method] = orig;
+        }
+        catch {
+            // ignore
+        }
+    }
+}

package/dist/models.d.ts

@@ -95,6 +95,10 @@ export interface MonopolyMove {
 }
 export interface MafiaMove {
     action: string;
+    /** Seat to act on. Seat 0 is a real player, so for a night action
+     *  (kill/investigate/protect/profile) set an explicit seat — omit it (or use -1)
+     *  ONLY to mean "no target" (the engine then drops the untargeted action rather
+     *  than acting on seat 0). Votes/discussion treat a missing/≤0 target as no target. */
     target?: number;
     tone?: string;
     text?: string;

package/dist/pricing.d.ts

@@ -0,0 +1,27 @@
+export declare const PRICING_VERSION = "2026-07-24";
+export interface Rate {
+    /** USD per 1M input tokens. */
+    input: number;
+    /** USD per 1M output tokens. */
+    output: number;
+    /** 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;
+/** True if the model maps to an explicit table entry (not the fallback). */
+export declare function isKnown(model: string): boolean;
+export interface CostArgs {
+    promptTokens?: number;
+    completionTokens?: number;
+    cachedTokens?: number;
+    reasoningTokens?: number;
+}
+/**
+ * USD cost estimate for one model call. `cachedTokens` are a subset of
+ * `promptTokens` billed at the cached-input rate; `reasoningTokens` are output
+ * tokens already counted in `completionTokens` (kept for reporting).
+ */
+export declare function estimateCost(model: string, a?: CostArgs): number;

package/dist/pricing.js

@@ -0,0 +1,110 @@
+// Versioned LLM price table + cost estimation (mirrors the Python SDK's pricing.py).
+//
+// Single, dated source of truth for turning token counts into a USD cost estimate.
+// Prices are public list prices in USD per 1,000,000 tokens as of PRICING_VERSION;
+// they are estimates for the sandbox/unverified tier (the ranked/verified tier's
+// 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.
+// Bump whenever any rate below changes. Stamped onto every estimate.
+export const PRICING_VERSION = "2026-07-24";
+// Canonical model id -> Rate. Lowercase, provider-agnostic.
+const TABLE = {
+    // OpenAI
+    "gpt-4o": { input: 2.5, output: 10.0, cachedInput: 1.25 },
+    "gpt-4o-mini": { input: 0.15, output: 0.6, cachedInput: 0.075 },
+    "gpt-4.1": { input: 2.0, output: 8.0, cachedInput: 0.5 },
+    "gpt-4.1-mini": { input: 0.4, output: 1.6, cachedInput: 0.1 },
+    "gpt-4.1-nano": { input: 0.1, output: 0.4, cachedInput: 0.025 },
+    o1: { input: 15.0, output: 60.0, cachedInput: 7.5 },
+    "o1-mini": { input: 1.1, output: 4.4, cachedInput: 0.55 },
+    o3: { input: 2.0, output: 8.0, cachedInput: 0.5 },
+    "o3-mini": { input: 1.1, output: 4.4, cachedInput: 0.55 },
+    "o4-mini": { input: 1.1, output: 4.4, cachedInput: 0.275 },
+    "gpt-3.5-turbo": { input: 0.5, output: 1.5 },
+    // Anthropic (distinct Opus / Sonnet / Haiku)
+    "claude-opus": { input: 15.0, output: 75.0, cachedInput: 1.5 },
+    "claude-sonnet": { input: 3.0, output: 15.0, cachedInput: 0.3 },
+    "claude-haiku": { input: 0.8, output: 4.0, cachedInput: 0.08 },
+    // 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 / 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 },
+};
+// 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.
+const RULES = [
+    ["gpt-4o-mini", "gpt-4o-mini"],
+    ["gpt-4o", "gpt-4o"],
+    ["4o-mini", "gpt-4o-mini"],
+    ["4o", "gpt-4o"],
+    ["gpt-4.1-nano", "gpt-4.1-nano"],
+    ["gpt-4.1-mini", "gpt-4.1-mini"],
+    ["gpt-4.1", "gpt-4.1"],
+    ["4.1-nano", "gpt-4.1-nano"],
+    ["4.1-mini", "gpt-4.1-mini"],
+    ["4.1", "gpt-4.1"],
+    ["o1-mini", "o1-mini"],
+    ["o1", "o1"],
+    ["o3-mini", "o3-mini"],
+    ["o3", "o3"],
+    ["o4-mini", "o4-mini"],
+    ["gpt-3.5", "gpt-3.5-turbo"],
+    ["3.5-turbo", "gpt-3.5-turbo"],
+    ["opus", "claude-opus"],
+    ["sonnet", "claude-sonnet"],
+    ["haiku", "claude-haiku"],
+    ["gemini-1.5-flash", "gemini-flash"],
+    ["gemini-2.0-flash", "gemini-flash"],
+    ["gemini-2.5-flash", "gemini-flash"],
+    ["flash", "gemini-flash"],
+    ["gemini-1.5-pro", "gemini-pro"],
+    ["gemini-2.5-pro", "gemini-pro"],
+    ["gemini", "gemini-pro"],
+    ["llama", "llama"],
+    ["mistral", "mistral"],
+    ["mixtral", "mistral"],
+    ["qwen", "qwen"],
+    ["deepseek", "deepseek"],
+];
+/** Map a raw model string to a canonical table key, or null if unknown. */
+export function canonical(model) {
+    const m = (model ?? "").trim().toLowerCase();
+    if (!m)
+        return null;
+    if (m in TABLE)
+        return m;
+    for (const [needle, key] of RULES)
+        if (m.includes(needle))
+            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);
+    return key !== null ? TABLE[key] : FALLBACK;
+}
+/** True if the model maps to an explicit table entry (not the fallback). */
+export function isKnown(model) {
+    return canonical(model) !== null;
+}
+/**
+ * USD cost estimate for one model call. `cachedTokens` are a subset of
+ * `promptTokens` billed at the cached-input rate; `reasoningTokens` are output
+ * tokens already counted in `completionTokens` (kept for reporting).
+ */
+export function estimateCost(model, a = {}) {
+    const rate = rateFor(model);
+    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));
+    const fullInput = prompt - cached;
+    const cachedRate = rate.cachedInput ?? rate.input;
+    const cost = (fullInput * rate.input + cached * cachedRate + completion * rate.output) / 1_000_000;
+    return Math.round(cost * 1e8) / 1e8;
+}

package/dist/runtime.d.ts

@@ -74,6 +74,7 @@ export declare class RuntimeConnector {
     private nudged;
     private registered;
     private refreshAttempts;
+    private turnNo;
     private readonly tracer;
     constructor(agent: Agent, opts: RuntimeOptions);
     /** The gateway echoes the newest published version on the registered frame.

package/dist/runtime.js

@@ -1,5 +1,5 @@
 import { SDK_VERSION } from "./server.js";
-import { Tracer } from "./telemetry.js";
+import { Tracer, runTurnUsage } from "./telemetry.js";
 // Frame types — byte-identical to the Go gateway (internal/agentgw/frame.go).
 const HELLO = "hello", REGISTERED = "registered", PONG = "pong";
 const INITIALIZE = "initialize", TURN = "turn", EVENT = "event", GAME_END = "game_end", ERROR = "error";
@@ -88,6 +88,7 @@ export class RuntimeConnector {
     nudged = false; // print the "upgrade available" notice at most once
     registered = false; // true once this session's register succeeded
     refreshAttempts = 0; // per-connection guard against a refresh loop
+    turnNo = 0; // monotonic per-connection turn counter (telemetry attribution fallback)
     // Opt-in Pyyol Lens telemetry (no-op unless PYYOL_LENS_ENDPOINT+KEY set).
     // Correlated to the match trace so the agent's model/tool calls render with
     // the platform's authoritative gateway spans.
@@ -329,20 +330,44 @@ export class RuntimeConnector {
                 break;
             case TURN: {
                 const view = frame.payload ?? {};
-                // Bracket the developer's handler in a Lens span; inside decideTurn the
-                // author can reach it via pyyol.currentSpan() to record model/tool calls.
-                const { status, body } = await this.tracer.runTurn({
+                this.turnNo++;
+                // Per-turn index for telemetry attribution. Goofspiel has `round`, Mafia has
+                // `day`; Monopoly has neither, so fall back to the monotonic per-match turn
+                // counter — otherwise X-Pyyol-Turn was always 0 for 2/3 games.
+                const turnNo = Number(view.round ?? view.day ?? 0) || this.turnNo;
+                // Bracket the developer's handler in a Lens span AND a turn-local usage
+                // accumulator. Inside decideTurn the author can reach the span via
+                // pyyol.currentSpan(); if instrument() is active, every LLM call is captured
+                // automatically. The accumulator is always on (independent of Lens) so usage
+                // rides the move to the arena regardless.
+                const { result, usage } = await runTurnUsage(() => this.tracer.runTurn({
                     matchId: view.match_id ?? "",
                     game: view.game ?? "",
-                    round: Number(view.round ?? 0) || 0,
+                    round: turnNo,
                     agentId: this.opts.agentId,
-                }, () => this.agent.decideTurn(view));
+                }, () => this.agent.decideTurn(view)), { matchId: view.match_id ?? "", turn: turnNo });
+                const { status, body } = result;
+                // Auto-attach captured model/token/cost to the move so the arena benchmark
+                // records real usage with no developer boilerplate. A dev-supplied `usage`
+                // always wins — we never overwrite it.
+                if (status === 200 &&
+                    body != null &&
+                    typeof body === "object" &&
+                    !usage.empty &&
+                    !("usage" in body)) {
+                    body.usage = usage.toMoveUsage();
+                }
                 if (status === 200) {
                     send({ t: RESPONSE, id: frame.id ?? "", payload: body });
                     this.feed("turn", summarizeMove(frame.payload?.game ?? "", body));
                 }
                 else {
-                    send({ t: RESPONSE, id: frame.id ?? "", error: body?.error ?? "handler_error" });
+                    const err = body?.error ?? "handler_error";
+                    const detail = body?.message || err;
+                    // Surface the REAL handler error in the feed (not just "handler_error"), so
+                    // a crashing step() is visible in `pyyol dev`.
+                    send({ t: RESPONSE, id: frame.id ?? "", error: err });
+                    this.feed("error", `turn ${this.turnNo}: ${detail} → fallback`);
                 }
                 break;
             }

package/dist/server.js

@@ -105,8 +105,16 @@ export class Agent {
             const move = await handler(parseView(data));
             return { status: 200, body: move ?? {} };
         }
-        catch {
-            return { status: 500, body: { error: "handler_error" } };
+        catch (e) {
+            // Do NOT swallow: a crashing step() is the #1 "why doesn't my agent work"
+            // trap. Log the real error + stack (so `pyyol dev` shows it) and return the
+            // message so the runtime can surface it in the feed. The engine still applies
+            // its deterministic fallback for this turn, so the match isn't wedged.
+            const msg = e instanceof Error ? e.message : String(e);
+            console.error(`${game} step() threw: ${msg}`);
+            if (e instanceof Error && e.stack)
+                console.error(e.stack);
+            return { status: 500, body: { error: "handler_error", message: msg } };
         }
     }
     // --- shared handler invocation (used by both the HTTP path and the socket

package/dist/telemetry.d.ts

@@ -31,6 +31,57 @@ export declare class Span {
 /** The span for the turn currently being handled, or a no-op span outside one.
  *  Always safe to call and chain (never null). */
 export declare function currentSpan(): Span;
+export interface MoveUsage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+    reasoning_tokens?: number;
+    cached_tokens?: number;
+    estimated_cost?: number;
+    model?: string | string[];
+    provider?: string | string[];
+}
+export interface UsageAdd {
+    model?: string;
+    provider?: string;
+    promptTokens?: number;
+    completionTokens?: number;
+    reasoningTokens?: number;
+    cachedTokens?: number;
+    estimatedCost?: number;
+}
+/** Sums token usage + cost across every model call within a single turn. */
+export declare class UsageAccumulator {
+    promptTokens: number;
+    completionTokens: number;
+    reasoningTokens: number;
+    cachedTokens: number;
+    estimatedCost: number;
+    calls: number;
+    readonly models: string[];
+    readonly providers: string[];
+    matchId: string;
+    turn: number;
+    add(u: UsageAdd): void;
+    get totalTokens(): number;
+    get empty(): boolean;
+    /** The `usage` block attached to a move — matches the arena's TokenUsage decode
+     *  (prompt/completion/reasoning/total) plus SDK-side model/provider/cost. */
+    toMoveUsage(): MoveUsage;
+}
+/** The accumulator for the turn in progress, or undefined outside one. The
+ *  instrumentation calls this to record real usage; it no-ops when undefined. */
+export declare function currentUsage(): UsageAccumulator | undefined;
+/** Run `fn` with a fresh usage accumulator installed as current (always active,
+ *  independent of the Tracer), returning both fn's result and the accumulator.
+ *  ctx.matchId/turn are carried so gateway routing can attribute a call to the match. */
+export declare function runTurnUsage<T>(fn: () => T | Promise<T>, ctx?: {
+    matchId?: string;
+    turn?: number;
+}): Promise<{
+    result: T;
+    usage: UsageAccumulator;
+}>;
 export interface TracerOptions {
     endpoint?: string;
     apiKey?: string;

package/dist/telemetry.js

@@ -90,6 +90,74 @@ const storage = new AsyncLocalStorage();
 export function currentSpan() {
     return storage.getStore() ?? NOOP_SPAN;
 }
+/** Sums token usage + cost across every model call within a single turn. */
+export class UsageAccumulator {
+    promptTokens = 0;
+    completionTokens = 0;
+    reasoningTokens = 0;
+    cachedTokens = 0;
+    estimatedCost = 0;
+    calls = 0;
+    models = [];
+    providers = [];
+    // Turn context (for gateway attribution); set by runTurnUsage().
+    matchId = "";
+    turn = 0;
+    add(u) {
+        this.promptTokens += Math.max(0, Math.trunc(u.promptTokens ?? 0));
+        this.completionTokens += Math.max(0, Math.trunc(u.completionTokens ?? 0));
+        this.reasoningTokens += Math.max(0, Math.trunc(u.reasoningTokens ?? 0));
+        this.cachedTokens += Math.max(0, Math.trunc(u.cachedTokens ?? 0));
+        this.estimatedCost += Math.max(0, u.estimatedCost ?? 0);
+        this.calls += 1;
+        if (u.model && !this.models.includes(u.model))
+            this.models.push(u.model);
+        if (u.provider && !this.providers.includes(u.provider))
+            this.providers.push(u.provider);
+    }
+    get totalTokens() {
+        return this.promptTokens + this.completionTokens;
+    }
+    get empty() {
+        return this.calls === 0;
+    }
+    /** The `usage` block attached to a move — matches the arena's TokenUsage decode
+     *  (prompt/completion/reasoning/total) plus SDK-side model/provider/cost. */
+    toMoveUsage() {
+        const usage = {
+            prompt_tokens: this.promptTokens,
+            completion_tokens: this.completionTokens,
+            total_tokens: this.totalTokens,
+        };
+        if (this.reasoningTokens)
+            usage.reasoning_tokens = this.reasoningTokens;
+        if (this.cachedTokens)
+            usage.cached_tokens = this.cachedTokens;
+        if (this.estimatedCost)
+            usage.estimated_cost = Math.round(this.estimatedCost * 1e8) / 1e8;
+        if (this.models.length)
+            usage.model = this.models.length === 1 ? this.models[0] : this.models;
+        if (this.providers.length)
+            usage.provider = this.providers.length === 1 ? this.providers[0] : this.providers;
+        return usage;
+    }
+}
+const usageStorage = new AsyncLocalStorage();
+/** The accumulator for the turn in progress, or undefined outside one. The
+ *  instrumentation calls this to record real usage; it no-ops when undefined. */
+export function currentUsage() {
+    return usageStorage.getStore();
+}
+/** Run `fn` with a fresh usage accumulator installed as current (always active,
+ *  independent of the Tracer), returning both fn's result and the accumulator.
+ *  ctx.matchId/turn are carried so gateway routing can attribute a call to the match. */
+export async function runTurnUsage(fn, ctx = {}) {
+    const acc = new UsageAccumulator();
+    acc.matchId = ctx.matchId ?? "";
+    acc.turn = ctx.turn ?? 0;
+    const result = await usageStorage.run(acc, fn);
+    return { result, usage: acc };
+}
 /** Batching, non-blocking emitter to the Pyyol Lens ingest. */
 export class Tracer {
     enabled;

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "1.2.1";
+export declare const SDK_VERSION = "1.3.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.2.1";
+export const SDK_VERSION = "1.3.0";

package/package.json

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