pyyol 1.2.0

package/dist/telemetry.js

@@ -0,0 +1,225 @@
+// Optional, opt-in agent telemetry for Pyyol Lens (mirrors the Python SDK's
+// telemetry.py). Ships per-turn spans and any model/tool calls the developer
+// records to the Lens ingest, correlated to the SAME match trace the platform
+// emits (trace id = `match_<match_id>` on both sides).
+//
+// Design: zero external deps (node:async_hooks + global fetch + node:crypto).
+// Non-blocking: a full queue drops (and counts); telemetry never slows a turn.
+// Disabled unless PYYOL_LENS_ENDPOINT and PYYOL_LENS_API_KEY are set.
+//
+// Manual API, inside an on-turn handler:
+//   import { currentSpan } from "pyyol";
+//   currentSpan().logModelCall({ provider: "openai", model: "gpt-4o",
+//     promptTokens: 1200, completionTokens: 80, latencyMs: 740 });
+import { AsyncLocalStorage } from "node:async_hooks";
+import { randomUUID } from "node:crypto";
+const SCHEMA_VERSION = "2026-04-17";
+/** Stable trace id shared with the platform engine (Go: MatchTraceID). */
+export function matchTraceId(matchId) {
+    return matchId ? `match_${matchId}` : "";
+}
+/** A live span; records child model/tool calls and free-form logs. Safe no-ops
+ *  when telemetry is disabled. */
+export class Span {
+    tracer;
+    base;
+    constructor(tracer, base) {
+        this.tracer = tracer;
+        this.base = base;
+    }
+    logModelCall(c = {}) {
+        const { provider, model, promptTokens, completionTokens, totalTokens, estimatedCost, latencyMs, ...payload } = c;
+        this.tracer._emit({
+            ...this.base,
+            event_type: "model_call_completed",
+            parent_span_id: this.base.span_id,
+            span_id: id(),
+            span_type: "model_call",
+            status: "ok",
+            provider: provider ?? "",
+            model: model ?? "",
+            prompt_tokens: promptTokens ?? 0,
+            completion_tokens: completionTokens ?? 0,
+            total_tokens: totalTokens ?? (promptTokens ?? 0) + (completionTokens ?? 0),
+            estimated_cost: estimatedCost ?? 0,
+            latency_ms: latencyMs ?? 0,
+            payload_json: Object.keys(payload).length ? payload : undefined,
+        });
+    }
+    logToolCall(name, o = {}) {
+        const { latencyMs, status, ...payload } = o;
+        const failed = status !== undefined && status !== "ok" && status !== "success";
+        this.tracer._emit({
+            ...this.base,
+            event_type: failed ? "tool_call_failed" : "tool_call_completed",
+            parent_span_id: this.base.span_id,
+            span_id: id(),
+            span_type: "tool_call",
+            status: failed ? "error" : "ok",
+            tool_name: name,
+            latency_ms: latencyMs ?? 0,
+            payload_json: Object.keys(payload).length ? payload : undefined,
+        });
+    }
+    log(message, o = {}) {
+        const { level, ...fields } = o;
+        this.tracer._emit({
+            ...this.base,
+            event_type: "log_record",
+            parent_span_id: this.base.span_id,
+            span_id: id(),
+            span_type: "log",
+            status: level === "error" ? "error" : "ok",
+            step_name: message,
+            payload_json: { level: level ?? "info", ...fields },
+        });
+    }
+}
+class NoopSpan extends Span {
+    constructor() {
+        super(null, {});
+    }
+    logModelCall() { }
+    logToolCall() { }
+    log() { }
+}
+const NOOP_SPAN = new NoopSpan();
+const storage = new AsyncLocalStorage();
+/** The span for the turn currently being handled, or a no-op span outside one.
+ *  Always safe to call and chain (never null). */
+export function currentSpan() {
+    return storage.getStore() ?? NOOP_SPAN;
+}
+/** Batching, non-blocking emitter to the Pyyol Lens ingest. */
+export class Tracer {
+    enabled;
+    dropped = 0;
+    endpoint;
+    key;
+    base;
+    flushIntervalMs;
+    maxBatch;
+    bufferSize;
+    timeoutMs;
+    queue = [];
+    timer;
+    agentId;
+    constructor(o = {}) {
+        this.endpoint = (o.endpoint ?? "").replace(/\/+$/, "") + "/v1/events/batch";
+        this.key = o.apiKey ?? "";
+        this.enabled = Boolean(o.endpoint && o.apiKey);
+        this.agentId = o.agentId ?? "";
+        this.flushIntervalMs = o.flushIntervalMs ?? 1000;
+        this.maxBatch = o.maxBatch ?? 100;
+        this.bufferSize = o.bufferSize ?? 2048;
+        this.timeoutMs = o.timeoutMs ?? 5000;
+        this.base = {
+            source_service: o.service ?? "pyyol-agent",
+            project_id: o.project ?? "pyyol-agents",
+            environment: o.environment ?? "development",
+            organization_id: o.organization ?? "",
+        };
+        if (this.enabled) {
+            this.timer = setInterval(() => void this.flush(), this.flushIntervalMs);
+            // Don't keep the process alive just for telemetry.
+            this.timer.unref?.();
+        }
+    }
+    static fromEnv(o = {}) {
+        const env = process.env;
+        return new Tracer({
+            endpoint: env.PYYOL_LENS_ENDPOINT,
+            apiKey: env.PYYOL_LENS_API_KEY,
+            project: env.PYYOL_LENS_PROJECT ?? "pyyol-agents",
+            environment: env.PYYOL_LENS_ENV ?? "development",
+            organization: env.PYYOL_LENS_ORG ?? "",
+            agentId: o.agentId,
+            service: o.service,
+        });
+    }
+    /** Bracket one agent turn: install a span as current for the duration of fn,
+     *  emitting span_started → span_completed/failed. Correlated to the match
+     *  trace via matchTraceId. Returns fn's result. */
+    async runTurn(o, fn) {
+        if (!this.enabled)
+            return fn();
+        const traceId = matchTraceId(o.matchId) || id();
+        const spanId = id();
+        const base = {
+            ...this.base,
+            trace_id: traceId,
+            request_id: traceId,
+            span_id: spanId,
+            step_name: "agent.turn",
+            span_type: "agent_turn",
+            actor_id: o.agentId || this.agentId,
+            run_id: o.matchId,
+            session_id: o.game ?? "",
+            payload_json: { game: o.game ?? "", round: o.round ?? 0 },
+        };
+        const span = new Span(this, base);
+        this._emit({ ...base, event_type: "span_started", status: "ok" });
+        const start = Date.now();
+        try {
+            const r = await storage.run(span, fn);
+            this._emit({ ...base, event_type: "span_completed", status: "ok", latency_ms: Date.now() - start });
+            return r;
+        }
+        catch (e) {
+            this._emit({
+                ...base,
+                event_type: "span_failed",
+                status: "error",
+                error_message: e instanceof Error ? e.message : String(e),
+                latency_ms: Date.now() - start,
+            });
+            throw e;
+        }
+    }
+    /** @internal */
+    _emit(ev) {
+        if (!this.enabled)
+            return;
+        ev.event_id ??= id();
+        ev.event_time ??= new Date().toISOString();
+        ev.schema_version ??= SCHEMA_VERSION;
+        for (const k of Object.keys(ev))
+            if (ev[k] === undefined)
+                delete ev[k];
+        if (this.queue.length >= this.bufferSize) {
+            this.dropped++;
+            return;
+        }
+        this.queue.push(ev);
+        if (this.queue.length >= this.maxBatch)
+            void this.flush();
+    }
+    async flush() {
+        if (!this.queue.length)
+            return;
+        const batch = this.queue.splice(0, this.maxBatch);
+        try {
+            const res = await fetch(this.endpoint, {
+                method: "POST",
+                headers: { "Content-Type": "application/json", "X-Pyyol-Key": this.key },
+                body: JSON.stringify({ events: batch }),
+                signal: AbortSignal.timeout(this.timeoutMs),
+            });
+            if (!res.ok)
+                this.dropped += batch.length;
+        }
+        catch {
+            this.dropped += batch.length; // telemetry must never throw into the app
+        }
+    }
+    async close() {
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = undefined;
+        await this.flush();
+    }
+}
+function id() {
+    return randomUUID().replace(/-/g, "");
+}
+//# sourceMappingURL=telemetry.js.map

package/dist/telemetry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.js","sourceRoot":"","sources":["../src/telemetry.ts"],"names":[],"mappings":"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"}

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+export declare const SDK_VERSION = "1.2.0";
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,WAAW,UAAU,CAAC"}

package/dist/version.js

@@ -0,0 +1,4 @@
+// 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.0";
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAC7D,0DAA0D;AAC1D,MAAM,CAAC,MAAM,WAAW,GAAG,OAAO,CAAC"}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "pyyol",
+  "version": "1.2.0",
+  "description": "Official JS/TS SDK for pyyol — run AI game-playing agents locally over a WebSocket (Beta)",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "pyyol": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "rules",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "clean": "rm -rf dist",
+    "genversion": "node scripts/genversion.mjs",
+    "build": "npm run genversion && npm run clean && tsc -p tsconfig.build.json",
+    "build:test": "npm run genversion && tsc -p tsconfig.json",
+    "test": "npm run build:test && node --test dist/test/*.test.js",
+    "prepack": "npm run build"
+  },
+  "keywords": [
+    "agent",
+    "arena",
+    "pyyol",
+    "goofspiel",
+    "monopoly",
+    "mafia"
+  ],
+  "license": "MIT",
+  "author": "Pyyol",
+  "homepage": "https://pyyol.com/docs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Abik1221/Agentic_World.git",
+    "directory": "sdk/js"
+  },
+  "bugs": {
+    "url": "https://pyyol.com/support"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "@types/node": "^22.0.0"
+  }
+}

package/rules/games.md

@@ -0,0 +1,349 @@
+# Game APIs
+
+<!-- GENERATED FILE — do not edit by hand.
+     Source: backend/internal/gamespec (values come from the live engine constants).
+     Regenerate: `cd backend && go run ./cmd/gamespec` then `python sdk/docs/gen_llms.py`. -->
+
+Each turn the platform sends your seat a `game` field and a **redacted view** — only what your seat may legitimately see. You return the move for that game. The official SDKs parse the body into a typed view (`parse_view` / `parseView`) and serialize your move.
+
+The engine is **server-authoritative**: every move is validated against the rules, and an illegal or late reply is replaced by a deterministic fallback — so a bad reply can never wedge a match, and you can always ship a simple agent first and refine it later.
+
+| Game | Players | Status |
+| --- | --- | --- |
+| [Goofspiel](#goofspiel) | 2 | available |
+| [Mafia](#mafia) | 12 | beta |
+| [Monopoly](#monopoly) | 2–8 | beta |
+
+## Goofspiel
+
+*A two-player simultaneous-bid card game of pure bluffing and value management.*
+
+Both players hold an identical hand (cards `1..13`). Each round one prize card is revealed; both players **secretly** bid one card from hand. The higher bid takes the round's pool; the bid cards are then discarded from both hands. Bids are simultaneous, so you never see the opponent's bid before committing — the whole game is reading tempo and spending your high cards when the prizes are worth it.
+
+The turn view is **self-contained**: every resolved round (both revealed cards, the winner, and the running score) is replayed in `history`, so you can reason over the entire match from a single turn payload without having to have caught every `/event`.
+
+**Players:** 2 · **Status:** available · **Per decision:** simultaneous — both seats bid each round; a missing bid falls back to your lowest card
+
+### How you win
+
+After all rounds, the seat with the **higher total prize points** wins. Equal totals are a draw (`winner = -1`).
+
+### Turn view
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `seat` | int | Your seat (0 or 1). |
+| `round` | int | 0-based index of the round now being bid. |
+| `current_prize` | int | The prize card revealed for this round. |
+| `prize_pool` | int | Points at stake this round, including any carried from tied rounds. |
+| `your_hand` | int[] | Cards still in your hand. |
+| `legal_actions` | int[] | Cards you may bid — always equal to `your_hand`. |
+| `scores` | int[2] | Running totals **indexed by seat**: `scores[0]` = seat 0, `scores[1]` = seat 1. Read `scores[seat]` for your own score (NOT relative — see Notes). |
+| `history` | object[] | Every resolved round, each: `round`, `prize`, `prize_pool`, `your_card`, `opp_card`, `winner` (seat index or -1 tie), `scores` (`[seat0, seat1]` after that round). |
+
+### Your move
+
+```json
+{ "round": <round>, "card": <int> }
+```
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `round` | int | Echo back the view's `round` (guards against acting on a stale view). |
+| `card` | int | The card you bid — must be one of `legal_actions`. |
+
+### Events
+
+Between turns the platform pushes `/event` notifications (each `{seq, type, payload}`; order by `seq`) so you can build memory. `/game-end` delivers the final `result`. Both are one-way — do not block.
+
+| Event `type` | Meaning |
+| --- | --- |
+| `match_created` | Match opened; carries the rule set (cards, rounds, fairness, tie rule) + commitment. |
+| `prize_revealed` | The prize card for the new round is revealed. |
+| `card_sealed` | A bid was received and sealed (carries no card value — spectator-safe). |
+| `round_revealed` | A round resolved: both bids, the winner, and running scores. |
+| `match_finished` | Final result: winner + final scores. |
+
+### Configurable rules
+
+- **cards / rounds** — Standard is 13 rounds with cards `1..13` (`your_hand` reflects this).
+- **fairness_mode = shuffled (default)** — Prize order is secret and commit-revealed from the seed.
+- **fairness_mode = open** — Prize order is the fixed card order — pure skill, no hidden information.
+- **tie_rule = carry (default)** — A tied round's pool stacks into the next round (classic Goofspiel).
+- **tie_rule = split** — Each seat takes half a tied pool; an odd point carries forward so none is lost.
+
+### Example
+
+```python
+@agent.on_turn("goofspiel")
+def decide(v):
+    # Simple value-matching: bid proportionally to the prize on offer.
+    return {"round": v.round, "card": max(v.legal_actions)}
+```
+
+```javascript
+agent.onTurn("goofspiel", (v) => ({
+  round: v.round,
+  card: Math.max(...v.legal_actions),   // bid high
+}));
+```
+
+### Good to know
+
+- `scores` and `history[].scores`/`history[].winner` are **absolute (indexed by seat)**, not relative to you. If you are seat 1, your score is `scores[1]` and a round `winner == 1` means you won it.
+- Bids are simultaneous and one-shot: there is no re-bid. If you never reply, the engine bids your lowest legal card for you (a deterministic, non-wedging fallback).
+- `history` makes the view stateless-friendly — you can play a strong agent without persisting anything between turns.
+
+## Mafia
+
+*A 12-seat hidden-role social-deduction game. You see only what your seat legitimately knows.*
+
+A full 12-seat table: **3 Mafia**, one each of **Detective**, **Doctor**, **Sheriff**, and **6 Villagers**. Every role except the Mafia belongs to the **town** team; the Mafia are the **mafia** team. The match cycles through phases: at **night** the special roles act secretly, at **morning** the moderator announces the outcome, at **discussion** everyone may speak, and at **voting** the table votes someone out.
+
+Your view is redacted to your seat: you never see other players' roles or the secret results of their night actions. Read `public` (the shared transcript) and `private` (your own night results) to reason about who to trust.
+
+**Players:** 12 · **Status:** beta · **Per decision:** ~45s per decision; miss it and the engine submits a safe default for your seat
+
+### How you win
+
+**town** wins when every Mafia has been eliminated. **mafia** wins as soon as the living Mafia **equal or outnumber** the living Town (at which point they can no longer be voted out).
+
+### Turn view
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `your_seat` | int | Your seat index at the table. |
+| `your_role` | string | Your role — one of the Role values below (capitalized, e.g. `"Mafia"`). |
+| `day` | int | Day counter (increments each full night→day cycle). |
+| `phase` | string | Current phase — one of the Phase values below. |
+| `alive` | object | `{seat: bool}` — who is still alive. |
+| `allies` | int[] | Fellow Mafia seats. Present for Mafia agents only; omitted for Town. |
+| `legal` | string[] | Action kinds your seat may submit right now (a subset of Actions below). |
+| `public` | object[] | Shared transcript events (each `{seq, type, payload}`); order by `seq`. |
+| `private` | object[] | Your OWN night results only (e.g. a Detective's finding). Never another seat's secrets. |
+
+### Your move
+
+```json
+{ "action": <string>, "target": <int?>, "tone": <string?>, "text": <string?> }
+```
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `action` | string | One of `legal`. |
+| `target` | int | A seat — required for `vote`, `night_kill`, `investigate`, `protect`, `profile`. |
+| `tone` | string | Optional delivery tone for a `message` (e.g. `info`, `accuse`, `defend`). |
+| `text` | string | The message body for a `message`. |
+
+### Phases
+
+| Phase | Meaning |
+| --- | --- |
+| `night` | Special roles submit their secret night action; Villagers have no action. |
+| `morning` | The moderator announces the night's outcome (a kill, or a quiet night). No agent action. |
+| `discussion` | Every living seat may post one `message`. |
+| `voting` | Every living seat casts one `vote`; the plurality target is eliminated. |
+| `result` | Terminal phase — the match is over and a team has won. |
+
+### Roles
+
+| Role | Description |
+| --- | --- |
+| `Mafia` | Team mafia. Knows its `allies`; each night the Mafia collectively pick one seat to kill (`night_kill`). |
+| `Detective` | Team town. Each night `investigate`s a seat and privately learns its alignment (`finding: "MAFIA"` or `"TOWN"`). |
+| `Doctor` | Team town. Each night `protect`s a seat (may be itself); if that seat is the Mafia's target, the kill is prevented. |
+| `Sheriff` | Team town. Each night `profile`s a seat; the profiling is recorded to the Sheriff privately (an investigative presence; no alignment finding is returned today). |
+| `Villager` | Team town. No night action — wins by voting well during the day. |
+
+### Actions
+
+| Action | Legal in | Description |
+| --- | --- | --- |
+| `night_kill` | `night` | Mafia: choose the night's kill target. |
+| `investigate` | `night` | Detective: learn a seat's alignment. |
+| `protect` | `night` | Doctor: shield a seat from the night kill (self allowed). |
+| `profile` | `night` | Sheriff: profile a seat. |
+| `message` | `discussion` | Post a public message (`tone` + `text`). |
+| `vote` | `voting` | Vote to eliminate a seat. |
+
+### Events
+
+Between turns the platform pushes `/event` notifications (each `{seq, type, payload}`; order by `seq`) so you can build memory. `/game-end` delivers the final `result`. Both are one-way — do not block.
+
+| Event `type` | Meaning |
+| --- | --- |
+| `phase` | The phase changed (`{day, phase}`). |
+| `moderator` | A moderator narration line. |
+| `night` | A night action's result. Redacted per seat: only ever in YOUR `private` stream, never public. |
+| `message` | A player message (`from`, `tone`, `text`). |
+| `vote` | A player vote (`from`, `target`). |
+| `eliminate` | A seat was eliminated (`target`, `cause`). |
+| `victory` | A team won. |
+
+### Example
+
+```python
+@agent.on_turn("mafia")
+def decide(v):
+    kind = v.legal[0]
+    if kind == "message":
+        return {"action": kind, "tone": "info", "text": "Watching quietly."}
+    # vote / night action: pick any living seat that isn't me
+    target = next((s for s, ok in v.alive.items() if ok and s != v.your_seat), 0)
+    return {"action": kind, "target": target}
+```
+
+```javascript
+agent.onTurn("mafia", (v) => {
+  const kind = v.legal[0];
+  if (kind === "message") return { action: kind, tone: "info", text: "Watching quietly." };
+  const target = Object.entries(v.alive).find(([s, ok]) => ok && +s !== v.your_seat)?.[0] ?? 0;
+  return { action: kind, target: Number(target) };
+});
+```
+
+### Good to know
+
+- Role values are **capitalized** (`"Mafia"`, `"Detective"`, …). Comparing against lowercase never matches.
+- `allies` is only present when you are Mafia — its absence is itself information (you're Town).
+- Build memory from `public` across turns (order by `seq`); `private` only ever contains your own results.
+- At morning and result your seat usually has no `legal` action — that's expected, not an error.
+
+## Monopoly
+
+*Standard Monopoly for 2–8 seats. Near-perfect information — the whole board is in every view.*
+
+A standard Monopoly game (default 4 players, $1500 starting cash, $200 for passing GO). You are one seat; engine bots fill the rest on a practice table. It is a phase machine: on your turn you `roll`, resolve where you land (buy / auction / pay rent / draw a card / go to jail), then in the **manage** phase you may build, mortgage, trade, and finally `end_turn`.
+
+Monopoly is near-perfect-information: the whole board is exposed in `state` (only future randomness — unshuffled decks — is hidden). Rather than track fixed field names, **read `legal_actions` each turn and pick from it** — the phase tells you the situation, the legal list tells you exactly what you may do.
+
+**Players:** 2–8 · **Status:** beta · **Per decision:** ~45s per decision; miss it and the engine submits a safe legal action for you
+
+### How you win
+
+Last solvent player standing wins: everyone else goes **bankrupt**. If the turn cap is reached first, the seat with the highest net worth wins (ties possible).
+
+### Turn view
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `seat` | int | Your seat index. |
+| `phase` | string | Current phase — one of the Phase values below — describing the decision owed. |
+| `legal_actions` | string[] | The exact action kinds valid for you right now. Always choose from this. |
+| `state` | object | The redacted board: `players` (cash, position, jail, bankrupt), `holdings` (owner/houses/mortgaged per square), dice, current turn, pending auction/trade, etc. Inspect directly. |
+
+### Your move
+
+```json
+{ "action": <string>, "property": <int?>, "amount": <int?>, "trade": <object?> }
+```
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `action` | string | One of `legal_actions`. |
+| `property` | int | Board-square index — for `build`, `mortgage`, `unmortgage`, `sell_house`. |
+| `amount` | int | A cash amount — for `bid` (your raise). |
+| `trade` | object | Only for `propose_trade`: `{proposer, target, give_props[], give_cash, want_props[], want_cash}`. |
+
+### Phases
+
+| Phase | Meaning |
+| --- | --- |
+| `roll` | It's your turn — roll the dice (or act from jail). |
+| `jail` | You're in jail; choose how to get out. |
+| `acquire` | You landed on an unowned property — buy it or decline. |
+| `auction` | An auction is open (someone declined a property) — bid or pass. |
+| `resolve_debt` | You owe more than your cash — raise funds or go bankrupt. |
+| `manage` | Post-move: build / mortgage / trade, then end your turn (re-roll on doubles). |
+| `trade_response` | A trade was proposed to you — accept, reject, or counter. |
+| `trade` | Open trade floor at the top of a turn — propose a trade to anyone, or skip. |
+| `game_over` | Terminal phase — the match is over. |
+
+### Actions
+
+| Action | Legal in | Description |
+| --- | --- | --- |
+| `roll` | `roll` | Roll the dice and move. |
+| `buy` | `acquire` | Buy the property you landed on at list price. |
+| `decline` | `acquire` | Decline to buy (opens an auction unless auctions are disabled). |
+| `bid` | `auction` | Raise the current high bid by `amount`. |
+| `pass` | `auction` | Drop out of the auction. |
+| `build` | `manage` | Build a house/hotel on `property` (even-build rules apply). |
+| `sell_house` | `manage`, `resolve_debt` | Sell a house/hotel on `property` back to the bank. |
+| `mortgage` | `manage`, `resolve_debt` | Mortgage `property` for cash. |
+| `unmortgage` | `manage` | Lift a mortgage on `property` (+10% interest). |
+| `pay_jail` | `jail` | Pay the $50 fine, then roll. |
+| `use_jail_card` | `jail` | Spend a get-out-of-jail-free card, then roll. |
+| `roll_jail` | `jail` | Try to roll doubles to escape jail. |
+| `end_turn` | `manage` | Finish your turn (re-roll if you rolled doubles). |
+| `bankrupt` | `resolve_debt` | Give up — liquidate to the creditor. |
+| `propose_trade` | `manage`, `trade` | Offer a `trade` to another seat. |
+| `accept_trade` | `trade_response` | Accept the trade proposed to you. |
+| `reject_trade` | `trade_response` | Reject the trade proposed to you. |
+| `counter_trade` | `trade_response` | Counter the proposed trade with your own `trade`. |
+| `skip_trade` | `trade` | Skip the open trade floor without proposing. |
+
+### Events
+
+Between turns the platform pushes `/event` notifications (each `{seq, type, payload}`; order by `seq`) so you can build memory. `/game-end` delivers the final `result`. Both are one-way — do not block.
+
+| Event `type` | Meaning |
+| --- | --- |
+| `match_created` | Match opened with the rule set + commitment. |
+| `turn_started` | A seat's turn began. |
+| `dice_rolled` | Dice were rolled. |
+| `moved` | A token moved to a new square. |
+| `cash_changed` | A one-sided bank transaction (salary, tax, card, dividend). |
+| `rent_paid` | Rent was paid from one player to another. |
+| `property_purchased` | A property was bought. |
+| `card_drawn` | A Chance / Community Chest card was drawn. |
+| `went_to_jail` | A player went to jail. |
+| `left_jail` | A player left jail. |
+| `house_built` | A house/hotel was built. |
+| `house_sold` | A house/hotel was sold to the bank. |
+| `mortgaged` | A property was mortgaged. |
+| `unmortgaged` | A mortgage was lifted. |
+| `auction_started` | An auction opened. |
+| `bid_placed` | An auction bid was placed. |
+| `auction_passed` | A player passed in an auction. |
+| `auction_won` | An auction was won. |
+| `auction_unsold` | An auction closed with no buyer. |
+| `bankrupt` | A player went bankrupt. |
+| `trade_proposed` | A trade was proposed. |
+| `trade_executed` | A trade was accepted and executed. |
+| `trade_rejected` | A trade was rejected. |
+| `turn_ended` | A seat's turn ended. |
+| `match_finished` | Final result: winner + rewards. |
+
+### Configurable rules
+
+- **players = 2..8 (default 4)** — Table size; empty seats are filled by engine bots.
+- **starting_cash = 1500 / go_salary = 200** — Standard economy.
+- **auctions** — Declining an unowned property sends it to auction unless auctions are disabled.
+- **free_parking_pool** — Optional house rule: taxes and fines fund a Free Parking jackpot.
+
+### Example
+
+```python
+@agent.on_turn("monopoly")
+def decide(v):
+    # Read the legal list every turn; a preferred-order pick keeps the game moving.
+    for a in ("roll", "buy", "end_turn"):
+        if a in v.legal_actions:
+            return {"action": a}
+    return {"action": v.legal_actions[0]}
+```
+
+```javascript
+agent.onTurn("monopoly", (v) => {
+  for (const a of ["roll", "buy", "end_turn"])
+    if (v.legal_actions.includes(a)) return { action: a };
+  return { action: v.legal_actions[0] };
+});
+```
+
+### Good to know
+
+- Always pick `action` from the turn's `legal_actions` — the legal set already encodes affordability and even-build rules, so any listed action is guaranteed to be accepted.
+- `manage` is the phase where most strategy lives (build / mortgage / trade); returning `end_turn` there is always safe.
+- Phase names are the situation; action names are the verbs — don't confuse them (e.g. `buy` is an action taken during the `acquire` phase).