pyyol 1.2.0 → 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/login.d.ts

@@ -13,4 +13,3 @@ export declare function runLoginFlow(opts: {
     timeoutMs?: number;
     open?: (url: string) => void;
 }): Promise<LoginResult>;
-//# sourceMappingURL=login.d.ts.map

package/dist/login.js

@@ -104,4 +104,3 @@ export function runLoginFlow(opts) {
         });
     });
 }
-//# sourceMappingURL=login.js.map

package/dist/mode.d.ts

@@ -9,4 +9,3 @@ export declare function banner(mode: string, color?: boolean): string;
 /** One-time confirmation before real-stakes play. In CI/non-TTY, only proceeds when
  *  `assumeYes` is set — never silently enters ranked. */
 export declare function confirmRanked(assumeYes?: boolean): Promise<boolean>;
-//# sourceMappingURL=mode.d.ts.map

package/dist/mode.js

@@ -52,4 +52,3 @@ export async function confirmRanked(assumeYes = false) {
         rl.close();
     }
 }
-//# sourceMappingURL=mode.js.map

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;
@@ -102,4 +106,3 @@ export interface MafiaMove {
 export type Move = GoofspielMove | MonopolyMove | MafiaMove | Record<string, unknown>;
 /** Parse a turn body into its typed view; unknown games return the raw object. */
 export declare function parseView(d: Record<string, any>): TurnView;
-//# sourceMappingURL=models.d.ts.map

package/dist/models.js

@@ -65,4 +65,3 @@ export function parseView(d) {
             return d;
     }
 }
-//# sourceMappingURL=models.js.map

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

@@ -1,4 +1,3 @@
 /** Full Markdown rules for all three games, or just one game's section.
  *  @param game optional "goofspiel" | "monopoly" | "mafia" to slice one section. */
 export declare function gameRules(game?: string): string;
-//# sourceMappingURL=rules.d.ts.map

package/dist/rules.js

@@ -23,4 +23,3 @@ export function gameRules(game = "") {
     const next = text.indexOf("\n## ", start + marker.length);
     return next === -1 ? text.slice(start) : text.slice(start, next);
 }
-//# sourceMappingURL=rules.js.map

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.
@@ -94,4 +95,3 @@ export declare class RuntimeConnector {
     private session;
     private dispatch;
 }
-//# sourceMappingURL=runtime.d.ts.map

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;
             }
@@ -369,4 +394,3 @@ export class RuntimeConnector {
         }
     }
 }
-//# sourceMappingURL=runtime.js.map

package/dist/server.d.ts

@@ -72,4 +72,3 @@ export declare class Agent {
     /** Run an HTTP server until the process exits. Zero dependencies. */
     serve(port?: number, host?: string): ReturnType<typeof createServer>;
 }
-//# sourceMappingURL=server.d.ts.map

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
@@ -171,4 +179,3 @@ function loadJson(body) {
         return {};
     }
 }
-//# sourceMappingURL=server.js.map

package/dist/signing.d.ts

@@ -39,4 +39,3 @@ export interface VerifyOptions {
  * the exact raw request body bytes.
  */
 export declare function verifyRequest(secret: string, headers: Headers, method: string, path: string, body: Buffer, opts?: VerifyOptions): void;
-//# sourceMappingURL=signing.d.ts.map

package/dist/signing.js

@@ -112,4 +112,3 @@ export function verifyRequest(secret, headers, method, path, body, opts = {}) {
         throw new VerificationError("bad_signature", "signature mismatch");
     }
 }
-//# sourceMappingURL=signing.js.map

package/dist/simulator.d.ts

@@ -35,4 +35,3 @@ export interface GoofspielSimResult {
 /** Play one Goofspiel match: your agent (seat 0) vs a baseline (seat 1). Throws
  *  {@link SimulationError} if your agent returns an illegal or malformed move. */
 export declare function simulateGoofspiel(agent: Agent, opts?: GoofspielSimOptions): Promise<GoofspielSimResult>;
-//# sourceMappingURL=simulator.d.ts.map

package/dist/simulator.js

@@ -106,4 +106,3 @@ function shuffle(arr, rng) {
         [arr[i], arr[j]] = [arr[j], arr[i]];
     }
 }
-//# sourceMappingURL=simulator.js.map