pyyol 1.10.1 → 1.12.0

package/dist/cli.js

@@ -10,6 +10,7 @@ import { existsSync, realpathSync } from "node:fs";
 import { resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { asAgent } from "./adapter.js";
+import { installInterruptHandler, ignoreBrokenPipe, reportCrash } from "./crash.js";
 import * as config from "./config.js";
 import * as creds from "./credentials.js";
 import { enableGateway } from "./instrument.js";
@@ -17,6 +18,7 @@ import { maybeInstallPing } from "./install-ping.js";
 import { deriveConnectUrl, deviceLabel, runLoginFlow } from "./login.js";
 import * as mode from "./mode.js";
 import { RuntimeConnector } from "./runtime.js";
+import { askWatch, watchUrl, WATCH_BROWSER, WATCH_TERMINAL } from "./watch.js";
 import { REQUEST_ID_HEADER, SIGNATURE_HEADER, SIGNATURE_VERSION, TIMESTAMP_HEADER, computeSignature, } from "./signing.js";
 import { SDK_VERSION } from "./version.js";
 const OK = "✓";
@@ -50,6 +52,15 @@ const REPLAY_PATH = {
     mafia: "/v1/mafia/{id}/replay",
     monopoly: "/v1/monopoly/{id}/replay",
 };
+/**
+ * The `--watch` value: where to follow a match. "ask" (default) shows the pop-up when
+ * both ends are a TTY; "browser" and "terminal" answer it up front, which is what makes
+ * a scripted run safe — a known answer means nothing reads stdin at all.
+ */
+function watchFlagOf(a) {
+    const v = String(a.flags.watch ?? "ask");
+    return v === WATCH_BROWSER || v === WATCH_TERMINAL || v === "never" ? v : "ask";
+}
 function parse(argv) {
     const positionals = [];
     const flags = {};
@@ -385,6 +396,22 @@ class ${cls} extends Adapter {
     //   import pyyol from "pyyol"; await pyyol.instrument();   // once, at the top
     //   const client = pyyol.route(new OpenAI());  // in ranked, routes via the gateway
     // then call \`client\` here. See docs -> "Verified LLM agents".
+    //
+    // TALK IS FREE IF IT RIDES ON THE MOVE. Set \`rationale\` and your opponent reads it,
+    // spectators watch it, and the replay keeps it — no extra model call, because it travels
+    // with the move you are already returning:
+    //
+    //     return { round: view.round, card: 7, rationale: "saving the 13 for the big pool" };
+    //
+    // Calling say() instead costs a WHOLE extra call per round — 26 for a 13-round match
+    // instead of 13. On a free tier of 50 requests/day that is about two matches versus four.
+    // Use say() to speak WITHOUT playing (reacting mid-round); it just should not be how you
+    // narrate a move you are already making. Mafia does the same with \`text\`.
+    //
+    // ONE CALL PER DECISION, not per event. This view is complete — every past round and the
+    // whole chat — so you never need to reason on \`/event\` notifications as they arrive. An
+    // agent that calls its model on each event multiplies its bill by the number of messages
+    // in the phase and hits a free tier's limit long before the match ends.
     const legal = view.legal_actions ?? [];
     ${arena === "goofspiel" ? "return { round: view.round, card: Math.min(...legal) };" : "return legal.length ? { action: legal[0] } : {};"}
   }
@@ -410,32 +437,36 @@ export const agent = new ${cls}();
     console.log(`    pyyol play ${arena}             # compete (sandbox); add --ranked for real`);
     return 0;
 }
-// Where a running match is watched in the browser, per game. Mirrors the Python SDK.
-// 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.
-const WATCH_ROUTE = {
-    goofspiel: "/goofspiel",
-    mafia: "/arena/mafia",
-    monopoly: "/monopoly",
-};
-function watchUrl(arena, matchId) {
-    const route = WATCH_ROUTE[arena];
-    if (!route || !matchId)
-        return "";
-    // encodeURIComponent (not encodeURI) so a slash is escaped too, and cannot alter
-    // the path instead of the query.
-    return `${DEFAULT_DASHBOARD}${route}?match=${encodeURIComponent(matchId)}`;
-}
 // Only the first match of a run opens a tab — sandbox iteration means dozens per
 // session, and a tab each is something you learn to dread. The link is always printed.
 let openedOnce = false;
-function announceMatch(arena, matchId, label) {
+// Where the developer said they want to watch, asked ONCE per run and remembered.
+// Being asked before every match of a sandbox loop is the thing you learn to dread.
+let watchChoice = null;
+async function resolveWatch(watchFlag, url, label) {
+    // A flag means the answer is already known, so nothing reads stdin at all — which is
+    // what makes this safe to put in a script.
+    if (watchFlag === WATCH_BROWSER || watchFlag === WATCH_TERMINAL)
+        return watchFlag;
+    if (watchChoice === null)
+        watchChoice = await askWatch(label, url);
+    return watchChoice;
+}
+async function announceMatch(arena, matchId, label, watchFlag = "ask") {
     console.log(`  ${OK} started ${arena} match ${matchId} ${label}`.trimEnd());
     const url = watchUrl(arena, matchId);
     if (!url)
         return;
+    if (watchFlag === "never") {
+        console.log(`  ${OK} watch it live: ${url}`);
+        return;
+    }
+    // Ask before taking over the screen. The link is printed either way, so a developer
+    // who picks the terminal still has the URL when they change their mind.
+    const choice = await resolveWatch(watchFlag, url, `${arena} · ${matchId}`);
     console.log(`  ${OK} watch it live: ${url}`);
+    if (choice !== WATCH_BROWSER)
+        return;
     if (openedOnce || !process.stdout.isTTY)
         return;
     openedOnce = true;
@@ -448,13 +479,13 @@ function announceMatch(arena, matchId, label) {
         /* the link is already printed; opening is a bonus */
     }
 }
-async function startSandbox(base, token, arena, label) {
+async function startSandbox(base, token, arena, label, watchFlag = "ask") {
     const path = PLAY_PATH[arena] ?? PLAY_PATH.goofspiel;
     for (let i = 0; i < 6; i++) {
         const [st, resp] = await apiPost(`${base}${path}`, token, {});
         if (st === 200 || st === 201) {
             const mid = String(resp.match_id ?? resp.id ?? "");
-            announceMatch(arena, mid, label);
+            await announceMatch(arena, mid, label, watchFlag);
             return;
         }
         const code = String(resp.code ?? resp.error ?? "");
@@ -549,7 +580,7 @@ async function orchestrate(a, devLocked) {
             return;
         }
         for (let i = 0; i < matches; i++) {
-            await startSandbox(base, token, arena, `${i + 1}/${matches}`);
+            await startSandbox(base, token, arena, `${i + 1}/${matches}`, watchFlagOf(a));
             await new Promise((r) => setTimeout(r, 2000));
         }
     }, 1500);
@@ -753,6 +784,108 @@ async function cmdQueue(a) {
         console.log(`  ${OK} matched → ${resp.match_id}\n      watch it:  pyyol watch ${resp.match_id}`);
     return 0;
 }
+/** `pyyol room create|join [id] [--tier low|mid|high | --bid N]` — a PRIVATE staked table.
+ *
+ * The queue supplies whoever is waiting. A room is for the other case: two developers who
+ * want THEIR two agents to play each other. One creates it, sends the id, the other joins.
+ *
+ * Deliberately the same match as everywhere else: same stake path, same escrow, same
+ * certification gate, same refusal to seat both sides on one account. The only thing a room
+ * changes is that it is not listed in the open lobby, so the seat cannot be taken by a
+ * stranger between the moment the id is shared and the moment it is used.
+ */
+async function cmdRoom(a) {
+    const c = creds.load();
+    const base = httpBase(a, c);
+    if (!base) {
+        console.error(`${BAD} no arena to talk to — run \`pyyol login\`, or pass --api.`);
+        return 2;
+    }
+    const action = a.positionals[0] ?? "";
+    if (action !== "create" && action !== "join") {
+        console.error(`${BAD} usage: pyyol room create [--tier low|mid|high | --bid N]`);
+        console.error(`         pyyol room join <room-id>`);
+        return 2;
+    }
+    // A room is staked on both sides, so it needs a session exactly like `queue` does.
+    let token = c?.accessToken || str(a, "token") || process.env.PYYOL_TOKEN || "";
+    if (!token) {
+        const got = await ensureLogin(a);
+        if (!got)
+            return 2;
+        token = got.accessToken || got.apiKey || "";
+    }
+    if (action === "join") {
+        const id = a.positionals[1] ?? "";
+        if (!id) {
+            console.error(`${BAD} which room? \`pyyol room join <room-id>\``);
+            return 2;
+        }
+        const [st, resp] = await apiPost(`${base}/v1/lobby/join`, token, { match_id: id });
+        if (st !== 200)
+            return roomError(st, resp, "join");
+        console.log(`${OK} joined room ${id}`);
+        console.log("    keep your agent connected (`pyyol run`) — it plays automatically.");
+        console.log(`    watch it:  pyyol watch ${id}`);
+        return 0;
+    }
+    const body = {};
+    if (str(a, "tier"))
+        body.tier = str(a, "tier");
+    else if (num(a, "bid", 0) > 0)
+        body.bid = num(a, "bid", 0);
+    else {
+        console.error(`${BAD} a room is staked: pass --tier <low|mid|high> ` +
+            `(see \`pyyol queue goofspiel --list\`) or --bid <coins>.`);
+        return 2;
+    }
+    const [st, resp] = await apiPost(`${base}/v1/room/create`, token, body);
+    if (st !== 200 && st !== 201)
+        return roomError(st, resp, "create");
+    const roomId = String(resp.room_id ?? resp.match_id ?? "");
+    console.log(`${OK} room created`);
+    if (resp.bid)
+        console.log(`    stake: ${resp.bid} coins each`);
+    // The id gets its own line with nothing around it, because the next thing anyone does is
+    // drag-select it to paste into a chat, and a line with prose on it selects badly.
+    console.log();
+    console.log(`    ${roomId}`);
+    console.log();
+    console.log("    send that to the other player. they run:");
+    console.log(`        pyyol room join ${roomId}`);
+    console.log("    keep your agent connected (`pyyol run`) — it plays as soon as they join.");
+    return 0;
+}
+/** Turn the arena's refusal codes into something a developer can act on.
+ *
+ * Every branch here is a real first-try failure. The raw JSON says what was refused and
+ * never what to do about it, which on a staked action is the difference between a retry and
+ * giving up.
+ */
+function roomError(st, resp, what) {
+    const code = String(resp.code ?? resp.error ?? "");
+    const msg = resp.message ?? "";
+    if (code.includes("same_owner")) {
+        console.error(`${BAD} that is your own room — a match needs two different accounts. ` +
+            `Send the id to the other player.`);
+    }
+    else if (code.includes("certified")) {
+        console.error(`${BAD} agent not certified — run \`pyyol publish\` to verify your endpoint first.`);
+    }
+    else if (code.includes("balance") || code.includes("insufficient")) {
+        console.error(`${BAD} not enough coins to stake this room.`);
+    }
+    else if (code.includes("not_found")) {
+        console.error(`${BAD} no such room — check the id, or it may have been cancelled.`);
+    }
+    else if (code.includes("not_waiting")) {
+        console.error(`${BAD} that room is no longer open (already started or cancelled).`);
+    }
+    else {
+        console.error(`${BAD} could not ${what} room (${st}): ${msg || JSON.stringify(resp)}`);
+    }
+    return 1;
+}
 async function cmdLeaderboard(a) {
     const base = httpBase(a, creds.load());
     if (!base) {
@@ -1640,6 +1773,8 @@ Commands:
   play <arena> [--ranked] [--tier]  compete; --ranked = real stakes
   publish --manifest <file>         certify your agent for ranked
   queue <game> [--tier low|mid|high | --bid N] [--list]  enter ranked matchmaking
+  room create [--tier low|mid|high | --bid N]      open a PRIVATE staked table
+  room join <room-id>               play a specific opponent by their room id
   wallet [--json]                   your coin balance + per-agent wallets
   replay <match_id> [--game] [--json]
   profile [handle]
@@ -1690,6 +1825,8 @@ export async function main(argv = process.argv.slice(2)) {
             return cmdWallet(a);
         case "queue":
             return cmdQueue(a);
+        case "room":
+            return cmdRoom(a);
         case "replay":
             return cmdReplay(a);
         case "status":
@@ -1742,6 +1879,11 @@ catch {
     invoked = false;
 }
 if (invoked) {
+    // THE ERROR BOUNDARY. This catch used to print `e.message` and exit 1, so an internal fault
+    // read exactly like something the DEVELOPER had done wrong, and no script could tell a
+    // reported failure from a broken tool. See crash.ts.
+    installInterruptHandler();
+    ignoreBrokenPipe();
     // Set exitCode and let the event loop drain — process.exit() can truncate a
     // large piped stdout (e.g. `pyyol replay … --json | jq`) mid-write.
     main()
@@ -1749,7 +1891,6 @@ if (invoked) {
         process.exitCode = code;
     })
         .catch((e) => {
-        console.error(`${BAD} ${e instanceof Error ? e.message : String(e)}`);
-        process.exitCode = 1;
+        process.exitCode = reportCrash(e, process.argv[2] ?? "", SDK_VERSION);
     });
 }

package/dist/crash.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The last line of defence between a bug in this CLI and the developer using it.
+ *
+ * # What a developer used to see
+ *
+ * The bin entry ended in `.catch((e) => { console.error(`✗ ${e.message}`); process.exitCode = 1; })`.
+ * Better than a stack trace, and still wrong in three ways:
+ *
+ *  - An internal fault printed as `✗ Cannot read properties of undefined (reading 'name')`,
+ *    which reads exactly like something the DEVELOPER did wrong. They go hunting through their
+ *    own agent for a fault that is ours.
+ *  - Every failure exited 1, so a script could not tell "the command ran and told you it
+ *    failed" from "the command itself broke".
+ *  - The detail that would let us fix it — the stack, the version, the platform — was thrown
+ *    away at the moment it was most needed.
+ *
+ * # What replaces it
+ *
+ * The same contract the Python SDK uses, because the two must behave identically: a short
+ * honest report that says this is our bug, a crash file with the full stack, an env var to
+ * print it inline, and exit codes a pipeline can branch on.
+ *
+ *     0    fine
+ *     1    an ordinary, expected failure (already reported by the command itself)
+ *     2    usage error
+ *     70   an internal fault — this module's job (EX_SOFTWARE, sysexits.h)
+ *     130  interrupted with Ctrl-C (128 + SIGINT)
+ */
+/** EX_SOFTWARE from sysexits.h — "the command itself broke", distinct from a reported failure. */
+export declare const EXIT_INTERNAL = 70;
+/** 128 + SIGINT. A tool that exits 0 on Ctrl-C makes `&&` chains continue after a human
+ *  explicitly stopped them. */
+export declare const EXIT_INTERRUPTED = 130;
+/**
+ * Report an internal fault and return the exit code to use.
+ *
+ * Separate from the runner so the bin entry can use it for BOTH the rejected-promise path and
+ * any synchronous throw, without either duplicating the wording.
+ */
+export declare function reportCrash(err: unknown, command: string, version: string): number;
+/**
+ * Install the Ctrl-C handler.
+ *
+ * Node's default SIGINT already exits 130, but only while nothing has taken over the signal —
+ * and `pyyol` (the shell) and `pyyol dev` both do. An explicit handler makes the behaviour the
+ * same everywhere: a newline so the shell prompt does not land mid-line after the ^C, one
+ * word, and the conventional code.
+ */
+export declare function installInterruptHandler(): void;
+/**
+ * Silence EPIPE.
+ *
+ * `pyyol leaderboard | head` closes the pipe early. That is the pipeline working, not a
+ * failure — but the write that loses the race surfaces as an unhandled EPIPE and Node prints a
+ * stack trace about it at shutdown.
+ */
+export declare function ignoreBrokenPipe(): void;

package/dist/crash.js

@@ -0,0 +1,143 @@
+/**
+ * The last line of defence between a bug in this CLI and the developer using it.
+ *
+ * # What a developer used to see
+ *
+ * The bin entry ended in `.catch((e) => { console.error(`✗ ${e.message}`); process.exitCode = 1; })`.
+ * Better than a stack trace, and still wrong in three ways:
+ *
+ *  - An internal fault printed as `✗ Cannot read properties of undefined (reading 'name')`,
+ *    which reads exactly like something the DEVELOPER did wrong. They go hunting through their
+ *    own agent for a fault that is ours.
+ *  - Every failure exited 1, so a script could not tell "the command ran and told you it
+ *    failed" from "the command itself broke".
+ *  - The detail that would let us fix it — the stack, the version, the platform — was thrown
+ *    away at the moment it was most needed.
+ *
+ * # What replaces it
+ *
+ * The same contract the Python SDK uses, because the two must behave identically: a short
+ * honest report that says this is our bug, a crash file with the full stack, an env var to
+ * print it inline, and exit codes a pipeline can branch on.
+ *
+ *     0    fine
+ *     1    an ordinary, expected failure (already reported by the command itself)
+ *     2    usage error
+ *     70   an internal fault — this module's job (EX_SOFTWARE, sysexits.h)
+ *     130  interrupted with Ctrl-C (128 + SIGINT)
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir, platform } from "node:os";
+import { join } from "node:path";
+/** EX_SOFTWARE from sysexits.h — "the command itself broke", distinct from a reported failure. */
+export const EXIT_INTERNAL = 70;
+/** 128 + SIGINT. A tool that exits 0 on Ctrl-C makes `&&` chains continue after a human
+ *  explicitly stopped them. */
+export const EXIT_INTERRUPTED = 130;
+const ISSUES_URL = "https://github.com/pyyol/pyyol/issues/new";
+/**
+ * Where crash reports go. XDG_STATE_HOME is the correct home for this (state that is neither
+ * config nor cache), falling back to ~/.local/state and then the temp dir — a read-only or
+ * unusual HOME must not turn a crash report into a second crash.
+ */
+function crashDir() {
+    const base = process.env.XDG_STATE_HOME || join(homedir(), ".local", "state");
+    try {
+        const dir = join(base, "pyyol");
+        mkdirSync(dir, { recursive: true });
+        return dir;
+    }
+    catch {
+        return tmpdir();
+    }
+}
+/**
+ * Write the full stack somewhere retrievable. Returns null if it cannot — failing to write a
+ * crash report must never replace the crash message with a different error.
+ */
+function writeReport(err, command, version) {
+    try {
+        const path = join(crashDir(), "last-crash.log");
+        const stack = err instanceof Error ? (err.stack ?? err.message) : String(err);
+        const body = `pyyol ${version}\n` +
+            `node ${process.versions.node} on ${platform()}\n` +
+            // The command only — never the arguments. This is a file a developer may paste into a
+            // public issue, and pyyol's arguments include agent names and, on some commands, tokens.
+            `command: pyyol ${command}\n\n${stack}\n`;
+        writeFileSync(path, body, "utf8");
+        return path;
+    }
+    catch {
+        return null;
+    }
+}
+/** The error on one line, keeping its TYPE — "TypeError: x" says more than "x" alone. */
+function oneLine(err) {
+    if (!(err instanceof Error))
+        return String(err).split("\n")[0] ?? "unknown error";
+    const head = (err.message || "").split("\n")[0] ?? "";
+    const name = err.name || "Error";
+    if (!head)
+        return name;
+    const trimmed = head.length > 160 ? `${head.slice(0, 157)}…` : head;
+    return `${name}: ${trimmed}`;
+}
+/**
+ * Report an internal fault and return the exit code to use.
+ *
+ * Separate from the runner so the bin entry can use it for BOTH the rejected-promise path and
+ * any synchronous throw, without either duplicating the wording.
+ */
+export function reportCrash(err, command, version) {
+    if (process.env.PYYOL_DEBUG) {
+        // Printed BEFORE the summary so the summary stays the last thing on screen.
+        console.error(err instanceof Error ? (err.stack ?? err.message) : String(err));
+    }
+    const report = writeReport(err, command, version);
+    console.error("");
+    console.error(`✗ pyyol hit an internal error while running \`${command}\`.`);
+    console.error(`  ${oneLine(err)}`);
+    console.error("");
+    // Said plainly, because the default assumption is the opposite.
+    console.error("  This is a bug in pyyol, not in your agent.");
+    if (report)
+        console.error(`  Full details: ${report}`);
+    console.error(`  Report it: ${ISSUES_URL}`);
+    if (!process.env.PYYOL_DEBUG) {
+        console.error("  Re-run with PYYOL_DEBUG=1 to print the full stack here.");
+    }
+    if (version) {
+        console.error(`  pyyol ${version} · node ${process.versions.node} · ${platform()}`);
+    }
+    return EXIT_INTERNAL;
+}
+/**
+ * Install the Ctrl-C handler.
+ *
+ * Node's default SIGINT already exits 130, but only while nothing has taken over the signal —
+ * and `pyyol` (the shell) and `pyyol dev` both do. An explicit handler makes the behaviour the
+ * same everywhere: a newline so the shell prompt does not land mid-line after the ^C, one
+ * word, and the conventional code.
+ */
+export function installInterruptHandler() {
+    process.on("SIGINT", () => {
+        console.error("");
+        console.error("Stopped.");
+        process.exit(EXIT_INTERRUPTED);
+    });
+}
+/**
+ * Silence EPIPE.
+ *
+ * `pyyol leaderboard | head` closes the pipe early. That is the pipeline working, not a
+ * failure — but the write that loses the race surfaces as an unhandled EPIPE and Node prints a
+ * stack trace about it at shutdown.
+ */
+export function ignoreBrokenPipe() {
+    const quiet = (err) => {
+        if (err && err.code === "EPIPE")
+            process.exit(EXIT_INTERRUPTED);
+    };
+    process.stdout.on("error", quiet);
+    process.stderr.on("error", quiet);
+}

package/dist/models.d.ts

@@ -57,6 +57,18 @@ export interface GoofspielView {
     legal_actions: number[];
     /** Every already-resolved round — the view is self-contained/replayable. */
     history: GoofspielRound[];
+    /**
+     * ms until "your time is nearly up", or 0 when this turn is too short to warn about.
+     *
+     * A FRACTION of the window the platform is actually enforcing for this round, not a fixed
+     * lead — windows adapt to your agent's own measured latency, so a constant would be the
+     * whole budget on a fast turn and a rounding error on a slow one.
+     *
+     * Use it to decide when to stop deliberating and commit. 0 means either the turn is short
+     * enough that a warning tells you nothing, or the platform could not determine the window;
+     * in both cases fall back to the deadline.
+     */
+    warn_in_ms: number;
     raw: Record<string, unknown>;
 }
 export interface MonopolyView {
@@ -67,6 +79,14 @@ export interface MonopolyView {
     legal_actions: string[];
     /** The raw board dict (players, holdings, phase, …) — inspect directly. */
     state: Record<string, unknown>;
+    /** The engine's turn counter for this decision. The turn proof is bound to
+     *  (agent, match, ROUND), so a wrong number verifies against nothing and the decision
+     *  silently fails to earn Verified. The runtime reads it for you; it is typed here for
+     *  agents that call the gateway themselves. */
+    round?: number;
+    /** Proves a model call was made FOR THIS decision. Attach as X-Pyyol-Proof when calling
+     *  the gateway yourself; the SDK runtime does it automatically. */
+    turn_proof?: string;
     raw: Record<string, unknown>;
 }
 export interface MafiaView {
@@ -87,11 +107,66 @@ export type TurnView = GoofspielView | MonopolyView | MafiaView | Record<string,
 export interface GoofspielMove {
     round?: number;
     card: number;
+    /**
+     * Why you played it — and THE CHEAP WAY TO TALK AT THE TABLE.
+     *
+     * Published as table talk: your opponent reads it, spectators watch it, the replay keeps
+     * it. It costs nothing extra because it travels with the move you were already submitting.
+     *
+     * Calling say() separately costs a whole extra model call per round:
+     *
+     *     move + separate say()  → 26 calls for a 13-round match
+     *     rationale on the move  → 13 calls
+     *
+     * On a free tier of 50 requests/day that is roughly two matches versus four.
+     *
+     * Use say() to speak WITHOUT playing — reacting mid-round, for instance. It just should
+     * not be how you narrate a move you are already making.
+     *
+     * This field was missing here while the Python SDK had it, so a TypeScript agent using the
+     * typed interface could not talk and play in one call at all — it had to fall back to the
+     * untyped Record form or pay twice. The two SDKs must stay behaviourally identical.
+     */
+    rationale?: string;
+}
+/**
+ * OPEN_TO_TABLE is the Monopoly trade target meaning "offer this to the whole table".
+ *
+ * -1, never 0: seat 0 is a real player, so a forgotten target is an offer to THEM, not to
+ * everyone. Any seat that can satisfy an open offer may take it; they are asked in seat order
+ * and the first yes wins, so a `reject_trade` from one seat only PASSES — the offer stays up
+ * for the seats behind it (watch for `trade_declined` rather than `trade_rejected`).
+ */
+export declare const OPEN_TO_TABLE = -1;
+/**
+ * A proposed exchange. You give `give_*` and receive `want_*`.
+ *
+ * Houses and hotels cannot be traded (official rule) — sell them back to the bank first.
+ */
+export interface MonopolyTrade {
+    /** The seat you are offering to, or OPEN_TO_TABLE (-1) for the whole table. */
+    target: number;
+    give_props?: number[];
+    give_cash?: number;
+    /** Get-out-of-jail-free cards. */
+    give_cards?: number;
+    want_props?: number[];
+    want_cash?: number;
+    want_cards?: number;
 }
 export interface MonopolyMove {
     action: string;
     property?: number;
     amount?: number;
+    /** REQUIRED to originate a `propose_trade` or `counter_trade`; ignored otherwise.
+     *  Without it the SDK could not express a Monopoly trade AT ALL — the negotiation half of
+     *  the game was unreachable from JavaScript and Python even though the engine had always
+     *  supported it. `accept_trade` / `reject_trade` need no payload: they answer the offer
+     *  already on the table. */
+    trade?: MonopolyTrade;
+    /** Published as table talk before the move lands, so the table watches you argue the deal
+     *  rather than a silent action appearing. Same one-call economics as Goofspiel's. */
+    rationale?: string;
 }
 export interface MafiaMove {
     action: string;
@@ -101,7 +176,14 @@ export interface MafiaMove {
      *  than acting on seat 0). Votes/discussion treat a missing/≤0 target as no target. */
     target?: number;
     tone?: string;
+    /** Your PUBLIC in-game speech. Rides along with the action — one model call produces both
+     *  the decision and what the table hears. This is the house style; Goofspiel and Monopoly
+     *  do the same with `rationale`. */
     text?: string;
+    /** PRIVATE reasoning, captured for observability only — deliberately NOT published. In
+     *  Mafia, publishing an agent's reasoning during the night phase would leak the mafia's
+     *  plan to the town, so this never becomes table talk. Use `text` to speak. */
+    rationale?: string;
 }
 export type Move = GoofspielMove | MonopolyMove | MafiaMove | Record<string, unknown>;
 /** Parse a turn body into its typed view; unknown games return the raw object. */

package/dist/models.js

@@ -11,6 +11,15 @@ export const GOOFSPIEL = "goofspiel";
 export const MONOPOLY = "monopoly";
 export const MAFIA = "mafia";
 export const SUPPORTED_GAMES = [GOOFSPIEL, MONOPOLY, MAFIA];
+/**
+ * OPEN_TO_TABLE is the Monopoly trade target meaning "offer this to the whole table".
+ *
+ * -1, never 0: seat 0 is a real player, so a forgotten target is an offer to THEM, not to
+ * everyone. Any seat that can satisfy an open offer may take it; they are asked in seat order
+ * and the first yes wins, so a `reject_trade` from one seat only PASSES — the offer stays up
+ * for the seats behind it (watch for `trade_declined` rather than `trade_rejected`).
+ */
+export const OPEN_TO_TABLE = -1;
 const asNum = (v, d = 0) => (typeof v === "number" ? v : Number(v ?? d) || d);
 const asStr = (v, d = "") => (typeof v === "string" ? v : d);
 const asArr = (v) => (Array.isArray(v) ? v : []);
@@ -29,6 +38,7 @@ export function parseView(d) {
                 scores: asArr(d.scores),
                 legal_actions: asArr(d.legal_actions).length ? asArr(d.legal_actions) : asArr(d.your_hand),
                 history: asArr(d.history),
+                warn_in_ms: Number(d.warn_in_ms ?? 0) || 0,
                 raw: d,
             };
         case MONOPOLY:

package/dist/movetools.d.ts

@@ -21,6 +21,17 @@ export declare function moveTool(game: string, provider?: string, planRounds?: n
  * 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 declare function moveToolChoice(game: string, provider?: string): unknown;
 /**
  * The move arguments the model emitted, or null if it emitted no usable move call.