pyyol 1.10.1 → 1.12.0

package/dist/movetools.js

@@ -92,9 +92,32 @@ const SCHEMAS = {
             },
             property: {
                 type: "integer",
-                description: "Board index of the property this action concerns, or 0.",
+                description: "Board index of the property this action concerns, or 0. On a bid during a " +
+                    "HOUSING SHORTAGE auction this is the square you would put the piece on.",
             },
             amount: { type: "integer", description: "Coin amount this action carries, or 0." },
+            // The trade payload. OPTIONAL and NOT part of the canonical bound form — a trade binds
+            // on its verb alone (a nested structure re-rendered cosmetically differently would
+            // reject an honest turn), so nothing here can cost a turn its binding. Without it a
+            // bound agent could act but never DEAL, which is most of Monopoly.
+            trade: {
+                type: "object",
+                description: "Required to propose or counter a trade. Ignored for other actions.",
+                properties: {
+                    target: {
+                        type: "integer",
+                        description: "Seat to offer to, or -1 to offer to the WHOLE TABLE (any player who can " +
+                            "satisfy it may take it). Never 0 for 'everyone' — seat 0 is a real player.",
+                    },
+                    give_props: { type: "array", items: { type: "integer" }, description: "Squares you give." },
+                    give_cash: { type: "integer", description: "Cash you give." },
+                    give_cards: { type: "integer", description: "Get-out-of-jail-free cards you give." },
+                    want_props: { type: "array", items: { type: "integer" }, description: "Squares you want." },
+                    want_cash: { type: "integer", description: "Cash you want." },
+                    want_cards: { type: "integer", description: "Get-out-of-jail-free cards you want." },
+                },
+                required: ["target"],
+            },
         },
         required: ["kind"],
     },
@@ -183,6 +206,17 @@ export function moveTool(game, provider = "openai", planRounds) {
  * Worth using. Without it a model may answer in prose, and a turn with no tool call is
  * unverified — the agent keeps playing but earns no completion binding.
  */
+/**
+ * The tool_choice value that FORCES the model to answer with the move tool.
+ *
+ * NOT every model accepts forcing. Some advertise tool support and still reject a
+ * required/named tool_choice — observed live: OpenRouter's `openai/gpt-oss-20b:free` answers
+ * `inference-enforced tool_choice (required/named) is not supported`, HTTP 400, on every call.
+ *
+ * If you see that, send `"auto"` instead. Binding reads the RESPONSE, so forcing is only a way
+ * to raise the hit rate — a model that emits the tool call on its own binds exactly the same.
+ * Forcing is the default because most models take it and it wastes fewer turns.
+ */
 export function moveToolChoice(game, provider = "openai") {
     const name = moveToolName(game);
     if (!name)

package/dist/runtime.d.ts

@@ -1,19 +1,3 @@
-/**
- * The Pyyol Runtime Connector — the local-runtime transport for JS/TS.
- *
- * Your agent runs on your own machine and dials OUT over a single persistent
- * WebSocket to the platform. The platform pushes match lifecycle down that socket
- * and reads decisions back over it, so a laptop behind NAT works with zero
- * networking config — you never host an inbound endpoint. This is the Beta model.
- *
- * The connector owns registration, heartbeats, automatic reconnection with
- * exponential backoff, and request/response correlation; it dispatches frames to
- * the handlers you registered on your `Agent`. No game logic lives here.
- *
- *     const agent = new Agent({ supportedGames: ["goofspiel"], name: "OlympAI" });
- *     agent.onTurn("goofspiel", (v) => ({ round: v.round, card: Math.max(...v.legal_actions) }));
- *     await agent.run({ url: "wss://pyyol.example/v1/agent/connect", agentId: "ag_…", token: "…" });
- */
 import type { Agent } from "./server.js";
 export declare const PROTOCOL_VERSION = "1.0";
 /** A minimal structural type for a WHATWG WebSocket (Node 22+ global, or `ws`). */
@@ -75,6 +59,7 @@ export declare class RuntimeConnector {
     private registered;
     private refreshAttempts;
     private turnNo;
+    private watchOffered;
     private readonly tracer;
     constructor(agent: Agent, opts: RuntimeOptions);
     /** The gateway echoes the newest published version on the registered frame.
@@ -84,6 +69,23 @@ export declare class RuntimeConnector {
     run(): Promise<void>;
     stop(): void;
     /** Emit a live-feed line to the CLI/console, if a sink was provided. */
+    /**
+     * Offer "browser or terminal?" when a match is found, without blocking anything.
+     *
+     * `pyyol run` is the path a developer is actually on when they type a command and a
+     * staked match appears, and until now that match simply began — no choice, and no way
+     * to reach the live table except finding it yourself.
+     *
+     * Never awaited by the caller. The prompt waits up to ten seconds for a keystroke, and
+     * the dispatch loop cannot afford that: the heartbeat that keeps the connection alive
+     * and the first turn of the match are both queued behind it. A developer who stepped
+     * away for coffee would come back to a forfeited stake.
+     *
+     * Opt out with PYYOL_WATCH=terminal (or browser to skip straight to opening it).
+     * Anything non-interactive is already handled inside askWatch, which prints nothing at
+     * all without a TTY on both ends.
+     */
+    private offerWatch;
     private feed;
     /** Warn (once) when connecting over cleartext ws:// to a non-local host — the
      *  register token is sent in the clear (mirrors the Python connector). */

package/dist/runtime.js

@@ -1,5 +1,23 @@
+/**
+ * The Pyyol Runtime Connector — the local-runtime transport for JS/TS.
+ *
+ * Your agent runs on your own machine and dials OUT over a single persistent
+ * WebSocket to the platform. The platform pushes match lifecycle down that socket
+ * and reads decisions back over it, so a laptop behind NAT works with zero
+ * networking config — you never host an inbound endpoint. This is the Beta model.
+ *
+ * The connector owns registration, heartbeats, automatic reconnection with
+ * exponential backoff, and request/response correlation; it dispatches frames to
+ * the handlers you registered on your `Agent`. No game logic lives here.
+ *
+ *     const agent = new Agent({ supportedGames: ["goofspiel"], name: "OlympAI" });
+ *     agent.onTurn("goofspiel", (v) => ({ round: v.round, card: Math.max(...v.legal_actions) }));
+ *     await agent.run({ url: "wss://pyyol.example/v1/agent/connect", agentId: "ag_…", token: "…" });
+ */
+import { spawn } from "node:child_process";
 import { SDK_VERSION } from "./server.js";
 import { Tracer, runTurnUsage } from "./telemetry.js";
+import { askWatch, watchUrl, WATCH_BROWSER, WATCH_TERMINAL } from "./watch.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";
@@ -89,6 +107,10 @@ export class RuntimeConnector {
     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)
+    // The watch prompt is offered ONCE per connection, not once per match: being asked
+    // before every match of a long run is the thing you learn to dread, and a timed-out
+    // prompt has left a reader on stdin that would swallow the next one.
+    watchOffered = false;
     // 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.
@@ -145,6 +167,48 @@ export class RuntimeConnector {
         void this.tracer.close();
     }
     /** Emit a live-feed line to the CLI/console, if a sink was provided. */
+    /**
+     * Offer "browser or terminal?" when a match is found, without blocking anything.
+     *
+     * `pyyol run` is the path a developer is actually on when they type a command and a
+     * staked match appears, and until now that match simply began — no choice, and no way
+     * to reach the live table except finding it yourself.
+     *
+     * Never awaited by the caller. The prompt waits up to ten seconds for a keystroke, and
+     * the dispatch loop cannot afford that: the heartbeat that keeps the connection alive
+     * and the first turn of the match are both queued behind it. A developer who stepped
+     * away for coffee would come back to a forfeited stake.
+     *
+     * Opt out with PYYOL_WATCH=terminal (or browser to skip straight to opening it).
+     * Anything non-interactive is already handled inside askWatch, which prints nothing at
+     * all without a TTY on both ends.
+     */
+    async offerWatch(payload) {
+        if (this.watchOffered)
+            return;
+        this.watchOffered = true;
+        try {
+            const matchId = String(payload.match_id ?? "");
+            const game = String(payload.game ?? "");
+            if (!matchId || !game)
+                return;
+            const url = watchUrl(game, matchId);
+            if (!url)
+                return; // no link rather than one onto someone else's match
+            const env = String(process.env.PYYOL_WATCH ?? "").trim().toLowerCase();
+            const preset = env === WATCH_BROWSER || env === WATCH_TERMINAL ? env : "";
+            // Bounded by the countdown: the platform starts play whether or not this was
+            // answered, so a longer wait asks about a decision that has already passed.
+            const choice = preset || (await askWatch(`${game} · ${matchId}`, url));
+            if (choice !== WATCH_BROWSER)
+                return;
+            const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+            spawn(cmd, [url], { detached: true, stdio: "ignore" }).unref();
+        }
+        catch {
+            // Watching is a courtesy; the match is not. Nothing here may reach the run loop.
+        }
+    }
     feed(kind, detail) {
         this.opts.onFeed?.(kind, detail);
     }
@@ -384,6 +448,12 @@ export class RuntimeConnector {
             case INITIALIZE: {
                 const ack = await this.agent.ackInitialize(frame.payload ?? {});
                 send({ t: RESPONSE, id: frame.id ?? "", payload: ack });
+                // AFTER the ack, and deliberately NOT awaited. On the socket path the platform
+                // treats a delivered initialize frame as the acknowledgement, so anything before
+                // the ack delays the answer that keeps this seat in the match — and awaiting the
+                // prompt here would stall every frame queued behind it, including the heartbeat
+                // holding the connection open and the first turn of the match.
+                void this.offerWatch(frame.payload ?? {});
                 break;
             }
             case EVENT:
@@ -391,7 +461,12 @@ export class RuntimeConnector {
                     match_id: frame.match_id ?? "", game: frame.game ?? "",
                     seq: frame.seq ?? 0, type: frame.kind ?? "", payload: frame.payload,
                 });
-                this.feed("event", `${frame.kind ?? "event"}${frame.seq !== undefined ? ` seq=${frame.seq}` : ""}`);
+                if (frame.kind === "match_start") {
+                    this.feed("match_start", countdownLine(frame.payload));
+                }
+                else {
+                    this.feed("event", `${frame.kind ?? "event"}${frame.seq !== undefined ? ` seq=${frame.seq}` : ""}`);
+                }
                 break;
             case GAME_END:
                 await this.agent.notifyGameEnd({
@@ -404,3 +479,43 @@ export class RuntimeConnector {
         }
     }
 }
+/** How long until play begins, as a line for the terminal.
+ *
+ *  Mirrors _countdown_line in the Python SDK, and must keep mirroring it: the two SDKs
+ *  disagreeing about when a match starts is the same class of divergence sdk/conformance
+ *  exists to prevent.
+ *
+ *  The platform sends an ABSOLUTE `starts_at` and its own `server_now`, never a duration.
+ *  Both are needed. The instant is what the browser counts to as well, so the two surfaces
+ *  agree instead of each counting down from ten and drifting apart; `server_now` is what
+ *  makes this line correct on a machine whose clock is wrong.
+ *
+ *  So the remaining time is measured against the SERVER's clock:
+ *
+ *      remaining = starts_at - server_now
+ *
+ *  Reading Date.now() here would reintroduce exactly the skew that pair exists to remove — a
+ *  developer whose laptop is two minutes fast would see a countdown that had already ended on
+ *  a match that has not started.
+ *
+ *  Fails soft to "match starting": a malformed timestamp must never stop an agent playing.
+ *  The countdown is a courtesy, the match is not.
+ */
+function countdownLine(payload) {
+    if (!payload || typeof payload !== "object")
+        return "match starting";
+    const p = payload;
+    const starts = parseTs(p.starts_at);
+    const now = parseTs(p.server_now);
+    if (starts === null || now === null)
+        return "match starting";
+    const secs = Math.max(0, Math.round((starts - now) / 1000));
+    return `match starts in ${secs}s`;
+}
+/** Parse an RFC3339 timestamp to epoch ms, or null. Go emits a trailing Z, which Date handles. */
+function parseTs(v) {
+    if (typeof v !== "string" || !v)
+        return null;
+    const t = Date.parse(v);
+    return Number.isNaN(t) ? null : t;
+}

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "1.10.1";
+export declare const SDK_VERSION = "1.12.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.10.1"; // x-release-please-version
+export const SDK_VERSION = "1.12.0"; // x-release-please-version

package/dist/watch.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The watch prompt: where a developer chooses to follow a match.
+ *
+ * Mirrors `pyyol/console.py::ask_watch` in the Python SDK. The two must behave
+ * identically — a developer who switches language should not discover that one of them
+ * hangs their CI and the other does not.
+ *
+ * A match used to open a browser tab on its own the moment it started. That is the wrong
+ * default in both directions: on a remote box or in tmux the tab goes nowhere, and a
+ * developer who ran a command in a terminal did not necessarily ask to have their screen
+ * taken over. So we ask, once, and remember.
+ */
+export declare const WATCH_BROWSER = "browser";
+export declare const WATCH_TERMINAL = "terminal";
+export type WatchChoice = typeof WATCH_BROWSER | typeof WATCH_TERMINAL;
+export interface AskWatchOpts {
+    /** Seconds before the default is taken. Must not outlive the start countdown. */
+    timeoutMs?: number;
+    stdin?: NodeJS.ReadableStream & {
+        isTTY?: boolean;
+    };
+    stdout?: NodeJS.WritableStream & {
+        isTTY?: boolean;
+    };
+    color?: boolean;
+}
+export declare const DEFAULT_DASHBOARD: string;
+/** Browser URL for a specific live match, or "" when it cannot be named exactly. */
+export declare function watchUrl(arena: string, matchId: string, dashboard?: string): string;
+/**
+ * Ask where to watch this match.
+ *
+ * Three rules keep this from becoming a liability:
+ *
+ * **It never blocks a machine.** No TTY on stdin OR stdout means nobody is there to
+ * answer — CI, a pipe, a systemd unit — so it resolves to the terminal default without
+ * printing a prompt at all. A prompt that can hang a pipeline is worse than no prompt.
+ *
+ * **It never outlives the countdown.** The read is bounded and defaults on expiry. The
+ * match begins whether or not this question was answered, and a prompt still on screen
+ * after play started is asking about a decision that is already gone.
+ *
+ * **It never keeps the process alive.** The readline interface is closed and stdin is
+ * paused on every path, including the timeout. A lingering stdin listener would hold the
+ * event loop open and a finished `pyyol play` would simply never exit.
+ */
+export declare function askWatch(label: string, url: string, opts?: AskWatchOpts): Promise<WatchChoice>;

package/dist/watch.js

@@ -0,0 +1,122 @@
+/**
+ * The watch prompt: where a developer chooses to follow a match.
+ *
+ * Mirrors `pyyol/console.py::ask_watch` in the Python SDK. The two must behave
+ * identically — a developer who switches language should not discover that one of them
+ * hangs their CI and the other does not.
+ *
+ * A match used to open a browser tab on its own the moment it started. That is the wrong
+ * default in both directions: on a remote box or in tmux the tab goes nowhere, and a
+ * developer who ran a command in a terminal did not necessarily ask to have their screen
+ * taken over. So we ask, once, and remember.
+ */
+import { createInterface } from "node:readline";
+export const WATCH_BROWSER = "browser";
+export const WATCH_TERMINAL = "terminal";
+// Stripping ANSI escapes is how a row's true on-screen width is measured.
+// eslint-disable-next-line no-control-regex -- matching them is the point
+const ANSI = /\x1b\[[0-9;]*m/g;
+const visibleLen = (s) => s.replace(ANSI, "").length;
+export const DEFAULT_DASHBOARD = (process.env.PYYOL_DASHBOARD || "").replace(/\/$/, "") || "https://pyyol.com";
+/**
+ * Where a running match is watched in the browser, per game. Verified against the
+ * client's routes: Goofspiel and Monopoly take ?match= at the top level; Mafia's viewer
+ * lives under /arena. A wrong path is worse than no link — it lands the developer on a
+ * DIFFERENT live match and everything they see is someone else's game.
+ *
+ * Lives here rather than in cli.ts because the runtime needs it too, and the runtime
+ * cannot import the CLI (the CLI imports the runtime). One copy, so the two paths cannot
+ * drift into disagreeing about where a match is watched.
+ */
+const WATCH_ROUTE = {
+    goofspiel: "/goofspiel",
+    mafia: "/arena/mafia",
+    monopoly: "/monopoly",
+};
+/** Browser URL for a specific live match, or "" when it cannot be named exactly. */
+export function watchUrl(arena, matchId, dashboard = DEFAULT_DASHBOARD) {
+    const route = WATCH_ROUTE[arena];
+    if (!route || !matchId || !dashboard)
+        return "";
+    // encodeURIComponent (not encodeURI) so a slash is escaped too, and cannot alter the
+    // path instead of the query.
+    return `${dashboard.replace(/\/$/, "")}${route}?match=${encodeURIComponent(matchId)}`;
+}
+/**
+ * Ask where to watch this match.
+ *
+ * Three rules keep this from becoming a liability:
+ *
+ * **It never blocks a machine.** No TTY on stdin OR stdout means nobody is there to
+ * answer — CI, a pipe, a systemd unit — so it resolves to the terminal default without
+ * printing a prompt at all. A prompt that can hang a pipeline is worse than no prompt.
+ *
+ * **It never outlives the countdown.** The read is bounded and defaults on expiry. The
+ * match begins whether or not this question was answered, and a prompt still on screen
+ * after play started is asking about a decision that is already gone.
+ *
+ * **It never keeps the process alive.** The readline interface is closed and stdin is
+ * paused on every path, including the timeout. A lingering stdin listener would hold the
+ * event loop open and a finished `pyyol play` would simply never exit.
+ */
+export async function askWatch(label, url, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 10_000;
+    const stdin = opts.stdin ?? process.stdin;
+    const stdout = opts.stdout ?? process.stdout;
+    if (!stdin.isTTY || !stdout.isTTY)
+        return WATCH_TERMINAL;
+    const color = opts.color ?? process.env.NO_COLOR === undefined;
+    const c = (text, code) => (color ? `\x1b[${code}m${text}\x1b[0m` : text);
+    const rows = [
+        c(label, "36"),
+        "",
+        `${c("[b]", "1")} watch the live table in your browser`,
+        `${c("[t]", "1")} follow the logs here          ${c("· default", "90")}`,
+    ];
+    // Sized to the content, measured on the UNCOLOURED text: an escape sequence takes
+    // columns in a string and none on screen, so padding by raw length draws a box that is
+    // crooked exactly when colour is on.
+    const width = Math.max(...rows.map(visibleLen)) + 2;
+    stdout.write("\n" + c("╭─ match found " + "─".repeat(Math.max(0, width - 13)) + "╮", "90") + "\n");
+    for (const r of rows) {
+        stdout.write(c("│", "90") + " " + r + " ".repeat(width - visibleLen(r)) + c("│", "90") + "\n");
+    }
+    stdout.write(c("╰" + "─".repeat(width + 1) + "╯", "90") + "\n");
+    if (url)
+        stdout.write("  " + c(url, "90") + "\n");
+    stdout.write("  " + c("›", "36") + " ");
+    const answer = await readLine(stdin, timeoutMs);
+    if (answer === null) {
+        // Say the default was taken. An unexplained newline reads as a dropped keystroke.
+        stdout.write("\n  " + c(`no answer in ${Math.round(timeoutMs / 1000)}s — following here`, "90") + "\n");
+        return WATCH_TERMINAL;
+    }
+    return answer.trim().toLowerCase().startsWith("b") ? WATCH_BROWSER : WATCH_TERMINAL;
+}
+/** One line from stdin, or null if the timeout wins. Always tears the reader down. */
+function readLine(stdin, timeoutMs) {
+    return new Promise((resolve) => {
+        const rl = createInterface({ input: stdin });
+        let done = false;
+        const finish = (v) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            rl.close();
+            // pause(), or a resumed stdin keeps the event loop alive and the CLI never exits.
+            if (typeof stdin.pause === "function")
+                stdin.pause();
+            resolve(v);
+        };
+        // Deliberately NOT unref'd. An unref'd timer may never fire, and this timer firing
+        // is what RESOLVES the promise — unref turned "defaults after ten seconds" into
+        // "hangs forever" whenever nothing else kept the event loop alive. It is short and
+        // cleared on every answered path, so it cannot hold the process open for long.
+        const timer = setTimeout(() => finish(null), timeoutMs);
+        rl.once("line", (line) => finish(line));
+        // A closed stdin is a non-answer, not a crash mid-match.
+        rl.once("close", () => finish(null));
+        rl.once("error", () => finish(null));
+    });
+}

package/package.json

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