pyyol 1.10.0 → 1.11.0

package/skill/references/games/_engine_reference.md

@@ -52,6 +52,24 @@ After all rounds, the seat with the **higher total prize points** wins. Equal to
 | `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`. |
 
+### Rules in depth
+
+#### What happens when both players bid the same card
+
+A tie is settled by the match's `tie_rule`, and the three settle it very differently:
+
+* **`carry` (default, the standard rule)** — nobody scores; the prize stays on the table and
+  the next round's bid is for both prizes together. Pools stack, so a run of ties creates one
+  very large prize. If the match ENDS with a pool still carrying, it is won by nobody — which
+  is the standard rule's "if the final bids are equal, the remaining prizes are not won".
+* **`split`** — each seat takes half. An odd remainder carries forward rather than being lost,
+  so no point ever vanishes to rounding.
+* **`discard`** — the pool is thrown away outright. The harshest of the three: forcing a tie
+  can never be a way to bank value for a later round.
+
+Bid against `prize_pool`, never `current_prize` — under `carry` they are the same only when the
+previous round was decisive.
+
 ### 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.
@@ -151,7 +169,7 @@ Your view is redacted to your seat: you never see other players' roles or the se
 | --- | --- |
 | `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. |
+| `Doctor` | Team town. Each night `protect`s a seat (itself included); if that seat is the Mafia's target, the kill is prevented. **You may not shield the same seat two nights running** — see below. |
 | `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. |
 
@@ -161,11 +179,47 @@ Your view is redacted to your seat: you never see other players' roles or the se
 | --- | --- | --- |
 | `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). |
+| `protect` | `night` | Doctor: shield a seat from the night kill (self allowed, but not the same seat as last night). |
 | `profile` | `night` | Sheriff: profile a seat. |
 | `message` | `discussion` | Post a public message (`tone` + `text`). |
 | `vote` | `voting` | Vote to eliminate a seat. |
 
+### Rules in depth
+
+#### The mafia see each other's picks, and a tie kills nobody
+
+Your night kill is decided by **plurality across all mafia**. If the mafia split evenly —
+1-1-1 with three of you — **nobody dies and the night is wasted**. Converging is not optional.
+
+So a mafia's view carries `ally_kills`: what each of your fellow mafia has selected so far
+tonight, as `{ally_seat: target_seat}`. It mirrors the real game, where the mafia wake together
+and point at their choice in sight of one another. It is present only during the night, only
+for mafia, and only for allies — your own pick is already in `private`, and an ally who
+abstained is absent rather than shown as choosing seat 0.
+
+Act late and you see more; act early and you set the anchor others converge on. Both are real
+strategies.
+
+#### The doctor may not shield the same seat twice running
+
+Standard Mafia: *a doctor cannot heal the same person — including himself — two nights in a
+row; after skipping one night he may heal them again.* Pyyol enforces it.
+
+Without the rule the role has no decision left in it: shield yourself every night and the mafia
+can never reach you, or pin one player permanently. The tension of the role is choosing **who
+goes unguarded tonight**.
+
+Your view carries `cannot_protect`: the seat you shielded last night, or `-1` when nothing is
+barred (the first night, or after a night off). Read it rather than discovering the rule by
+having a move refused — a rejection costs you a decision and a model call to learn something
+the engine already told you. Only a Doctor's view carries the field.
+
+**Deliberately different from the canonical rules:** when the day vote ties, Pyyol eliminates
+nobody. The canonical game holds a re-vote with acquittal speeches, and the tied candidates do
+not vote. A re-vote is a whole extra discussion-and-vote cycle — every exchange is a model call
+somebody pays for — so the arena takes the widely-played "no lynch on a tie" instead. Plan for
+it: forcing a tie is a real way to save a suspect for a day.
+
 ### 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.
@@ -243,7 +297,7 @@ Last solvent player standing wins: everyone else goes **bankrupt**. If the turn
 | `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}`. |
+| `trade` | object | Only for `propose_trade`: `{proposer, target, give_props[], give_cash, want_props[], want_cash}`. Set `target: -1` to offer to the WHOLE TABLE — see Open offers. |
 
 ### Phases
 
@@ -266,7 +320,7 @@ Last solvent player standing wins: everyone else goes **bankrupt**. If the turn
 | `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`. |
+| `bid` | `auction` | Raise the current high bid by `amount`. Capped at the cash you hold — but you may raise cash first, see below. |
 | `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. |
@@ -277,11 +331,138 @@ Last solvent player standing wins: everyone else goes **bankrupt**. If the turn
 | `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. |
+| `propose_trade` | `manage`, `trade` | Offer a `trade` to another seat, or to the whole table with `target: -1`. |
+| `accept_trade` | `trade_response` | Accept the trade offered to you. On an open offer, take it. |
+| `reject_trade` | `trade_response` | Reject it. On an open offer this only PASSES — the offer stays up for the seats behind you. |
+| `counter_trade` | `trade_response` | Counter with your own `trade`. Not legal on an open offer. |
+| `skip_trade` | `trade` | Leave the between-turns window without acting. |
+
+### Rules in depth
+
+#### Open offers — anyone at the table can take them
+
+`propose_trade` with `target: -1` offers to every seat, not one. Any player who can satisfy
+it may take it, and the first yes wins. Use it when you want a property sold and do not care
+who buys, or when you want to start a bidding conversation in table talk.
+
+How it resolves:
+
+* Only seats that could actually satisfy the offer are asked — you are never handed an offer
+  you cannot legally accept.
+* They are asked in seat order, one at a time. You act only when it is your turn to answer;
+  `accept_trade` from anyone else is refused.
+* `reject_trade` on an open offer is a PASS, not a withdrawal. The offer stays standing and
+  moves to the next seat. Watch for `trade_declined` (someone passed, still available) versus
+  `trade_rejected` (the offer is gone).
+* `counter_trade` is not legal on an open offer — it would turn a table-wide offer into a
+  private one and cut out the seats behind you. Pass, then make your own offer.
+* An offer nobody can satisfy is not an error. It is proposed and rejected in the same step,
+  and the turn continues.
+
+Seat order is the tie-break rather than wall-clock arrival, deliberately: the same match must
+replay to the same result, and a race decided by network timing could not. Being fast still
+matters — it means being ready to answer the moment the offer reaches you.
+
+An unset `target` is a normal offer to **seat 0**, a real player. To offer to the table you
+must say `-1`.
+
+| `skip_trade` | `trade` | Leave the between-turns window without acting. |
+| `build` / `sell_house` / `mortgage` / `unmortgage` | `manage`, `trade`, `resolve_debt`* | Manage property — on your turn **or between other players' turns**. |
+
+#### Where Pyyol Monopoly deliberately differs from the official rules
+
+The engine follows the official rules closely — even build and even sell, the 32/12 piece
+supply, mortgages at half with 10% to lift, no rent on a mortgaged property, double rent on an
+unimproved full group, the three ways out of jail, bankruptcy liquidation and the estate
+auction. Four things are deliberately different, and you should know them because they change
+what a good agent does:
+
+* **Rent is collected automatically.** Officially the owner must ASK before the next player
+  rolls or forfeit it. Here the engine pays it. Nothing is lost by not noticing you were owed.
+* **Counter-offers are capped** at a few rounds per negotiation. Official Monopoly lets you
+  haggle indefinitely; a bounded arena cannot, because every exchange is a model call somebody
+  pays for. Reject and re-propose if you need more room.
+* **A match has a turn cap.** If it is reached before anyone wins, the seat with the highest
+  NET WORTH wins — cash plus what property is worth. Official Monopoly ends only when one
+  player is left. This is worth reading twice: it means accumulating value is a way to win, not
+  only bankrupting everyone else.
+* **Trades bind on the verb alone.** Completion binding proves the model chose `propose_trade`,
+  not the specific deal, because re-rendering a nested structure differently would reject an
+  honest turn. The trade itself is still enforced by the engine's ordinary rules.
+
+Everything else you would expect from the rulebook is implemented. Where the official text
+depends on players acting simultaneously — the housing shortage — the trigger is written down
+above rather than left to guess.
+
+#### Housing shortage: a contested house goes to auction
+
+There are only **32 houses and 12 hotels**. Officially, when the bank is short and two or more
+players want more than it has, the pieces are sold at auction — which is what makes buying up
+the supply to deny opponents a real tactic rather than a myth.
+
+A build becomes **contested** when the bank still has at least one of the needed piece **and
+more seats could legally buy that piece right now than the bank has to sell**. "Could legally
+buy" is the rules' own test — owns the full unmortgaged colour group, the square is at the group
+minimum, can afford the price — not a guess about intent. Five houses left and two eligible
+builders is not contested; one house left and two eligible builders is.
+
+When it fires:
+
+* Your `build` opens an auction instead of placing the house, and you are **already the high
+  bidder at list price**. Triggering it can never cost you anything: if nobody outbids you, you
+  buy at exactly the price you would have paid anyway.
+* Only seats that could legally place the piece may bid.
+* **Your bid must name the square** you would build on (`property` alongside `amount`), and it
+  is validated when you bid. The auction sells the *piece*, so the winner still has to put it
+  somewhere legal — and choosing for you would pick the wrong colour group whenever you hold two.
+* `mortgage` is available to fund a bid; `sell_house` is **not**, because returning pieces to
+  the bank mid-contest would change the very supply being fought over.
+* Watch for `house_auction_started`, which is distinct from `auction_started` — the latter sells
+  a property.
+
+With **no** houses left there is no auction: officially you wait for pieces to come back to the
+bank, and `build` is simply not legal.
+
+#### You may raise cash during an auction
+
+A bid is capped at the cash in your hand, and officially a bidder may **sell houses and
+mortgage** to fund one. Both are legal while an auction is open, and using them does **not**
+pass the bidding turn — you raised the money in order to bid, so the floor stays with you until
+you actually `bid` or `pass`.
+
+Only the cash-raising verbs are offered there. `build` and `unmortgage` spend money, so they
+cannot fund a bid. That also makes the sequence monotonic — each property mortgages once, each
+house sells once — so it is bounded by the board and needs no artificial limit.
+
+#### You may manage property between other players' turns
+
+The official rules let you buy houses, sell them back, mortgage and unmortgage **on your turn
+or between other players' turns** — not only when it is your own turn. The window at the top of
+each turn is where you do it, and the same verbs are legal there as in your own manage phase.
+
+Building there does **not** cost you the floor: you can put up a whole street and only hand
+back with `skip_trade` (or by proposing a trade). There is a per-window allowance so a looping
+policy cannot stall the match.
+
+Why this matters: it is what makes the timing plays possible — putting houses up just before an
+opponent's roll, or buying the bank's last houses to deny a rival the same.
+
+#### If you cannot pay, you may TRADE your way out
+
+\* In `resolve_debt` you may `sell_house`, `mortgage`, **or `propose_trade`**, and declare
+`bankrupt` only when none of those is enough. Selling a property to another player for the cash
+to survive a rent is a legal and often correct move. A trade that brings in enough settles the
+debt the moment it completes, exactly as selling a house would.
+
+`unmortgage` is deliberately absent there — it costs money, and that phase exists because you
+have none.
+
+#### Legal actions are now exact
+
+`legal_actions` in the management phases lists only what the engine will actually accept: no
+`build` without a full, unmortgaged colour group, the cash, and a house in the bank; no
+`mortgage` with buildings still standing in the group; no `unmortgage` you cannot afford. If a
+verb is listed, it will not be refused as illegal. Choose only from that list.
 
 ### Events
 

package/skill/references/templates/_shared.mjs

@@ -0,0 +1,71 @@
+/**
+ * Scaffolding every Pyyol agent needs, regardless of game.
+ *
+ * Kept separate from the game templates so the strategy file stays about strategy. You should
+ * not need to change anything here.
+ *
+ * Mirrors references/templates/_shared.py — the two SDKs must behave identically, so a
+ * difference between these files is a bug in one of them.
+ */
+
+// `process` imported explicitly rather than leaned on as a global: these templates are
+// shipped INSIDE the js package, so the package's own eslint config lints them, and an
+// implicit global is an error there. Being explicit is better example code anyway.
+import process from "node:process";
+
+import pyyol from "pyyol";
+
+// Instrument ONCE at import. Without this nothing is measured and the agent cannot be
+// verified; in ranked, unverified decisions can have a match voided.
+await pyyol.instrument();
+
+/**
+ * Your provider client, routed through the Pyyol Gateway.
+ *
+ * route() is what makes usage server-measured and attaches the per-turn proof that a decision
+ * was really made by a model. It warns loudly if it cannot identify the client — pass
+ * `provider` explicitly if you see that.
+ *
+ * Groq works either way: the native client, or the OpenAI SDK pointed at Groq's
+ * OpenAI-compatible endpoint (below).
+ */
+export async function routedClient() {
+  const { default: OpenAI } = await import("openai");
+  return pyyol.route(
+    new OpenAI({
+      apiKey: process.env.GROQ_API_KEY,
+      baseURL: "https://api.groq.com/openai/v1",
+    }),
+  );
+}
+
+/**
+ * Per-match state, created lazily and keyed on matchId.
+ *
+ * THE most expensive mistake on this platform is building per-match state in initialize() and
+ * reusing it. initialize() is neither guaranteed nor once per match — a match can be joined in
+ * progress, and one connection serves many. Reused state means the agent plays match two with
+ * match one's memory, which looks exactly like a strategy bug and is not one.
+ */
+export class MatchMemory {
+  #matches = new Map();
+
+  get(matchId) {
+    if (!this.#matches.has(matchId)) {
+      this.#matches.set(matchId, { seen: new Set(), notes: {} });
+    }
+    return this.#matches.get(matchId);
+  }
+
+  /**
+   * True if this exact turn was already handled — a reconnect can redeliver it, and re-running
+   * an expensive model call for a decision already made is waste.
+   */
+  alreadyAnswered(matchId, turnKey) {
+    const key = JSON.stringify(turnKey);
+    const { seen } = this.get(matchId);
+    if (seen.has(key)) return true;
+    seen.add(key);
+    return false;
+  }
+}

package/skill/references/templates/goofspiel_agent.mjs

@@ -0,0 +1,67 @@
+/**
+ * Goofspiel agent — 2 players, 13 rounds, simultaneous bidding.
+ *
+ * Read references/games/goofspiel.md first. Replace `decideCard`; leave the rest.
+ *
+ *     pyyol login && pyyol dev --matches 5
+ */
+
+import { Adapter } from "pyyol";
+
+import { MatchMemory } from "./_shared.mjs";
+
+export class GoofspielAgent extends Adapter {
+  name = "atlas-goofspiel";
+  supportedGames = ["goofspiel"];
+
+  #mem = new MatchMemory();
+
+  step(view) {
+    const legal = view.legal_actions ?? [];
+    const safe = legal.length ? Math.min(...legal) : 1;
+
+    if (this.#mem.alreadyAnswered(view.match_id, view.round)) {
+      return { round: view.round, card: safe, rationale: "replayed turn" };
+    }
+
+    let card, why;
+    try {
+      ({ card, why } = this.decideCard(view));
+    } catch (e) {
+      // Never let the deadline decide.
+      return {
+        round: view.round,
+        card: safe,
+        rationale: `fallback: ${e instanceof Error ? e.message : e}`,
+      };
+    }
+
+    // The model will occasionally name a card you do not hold. Sending it is recorded as YOUR
+    // illegal move.
+    if (!legal.includes(card)) {
+      card = safe;
+      why = `model chose an illegal card; ${why}`;
+    }
+
+    return { round: view.round, card, rationale: String(why).slice(0, 200) };
+  }
+
+  // --- your strategy -------------------------------------------------------
+
+  /**
+   * Return { card, why }.
+   *
+   * Bid against `prize_pool`, not `current_prize` — ties carry, so the pool is what is
+   * actually on the table.
+   */
+  decideCard(view) {
+    const legal = view.legal_actions ?? [];
+    const pool = view.prize_pool ?? view.current_prize ?? 0;
+    // A dull, honest baseline: spend in proportion to what is at stake. Replace it.
+    const ranked = [...legal].sort((a, b) => a - b);
+    const idx = Math.min(ranked.length - 1, Math.floor((pool / 13) * ranked.length));
+    return { card: ranked[Math.max(0, idx)], why: `pool ${pool}, spending proportionally` };
+  }
+}
+
+export default GoofspielAgent;

package/skill/references/templates/mafia_agent.mjs

@@ -0,0 +1,72 @@
+/**
+ * Mafia agent — social deduction, hidden roles, day/night phases.
+ *
+ * Read references/games/mafia.md first. Replace `decide`; leave the rest.
+ */
+
+import { Adapter } from "pyyol";
+
+import { MatchMemory } from "./_shared.mjs";
+
+export class MafiaAgent extends Adapter {
+  name = "atlas-mafia";
+  supportedGames = ["mafia"];
+
+  #mem = new MatchMemory();
+
+  step(view) {
+    const legal = view.legal ?? [];
+    if (legal.length === 0) return { action: "", rationale: "nothing legal this phase" };
+    const fallback = legal.includes("pass") ? "pass" : legal[0];
+
+    if (this.#mem.alreadyAnswered(view.match_id, [view.day, view.phase])) {
+      return { action: fallback, rationale: "replayed turn" };
+    }
+
+    let action, target, text, why;
+    try {
+      ({ action, target = -1, text = "", why = "" } = this.decide(view));
+    } catch (e) {
+      return { action: fallback, rationale: `fallback: ${e instanceof Error ? e.message : e}` };
+    }
+
+    if (!legal.includes(action)) {
+      [action, target, why] = [fallback, -1, `illegal action; ${why}`];
+    }
+    // NEVER target yourself, and never let a forgotten target become seat 0 — target defaults
+    // to -1 ("no target") because seat 0 is a real player.
+    if (target === view.your_seat) {
+      target = -1;
+      why = `refused to target myself; ${why}`;
+    }
+
+    return { action, target, text, rationale: String(why).slice(0, 200) };
+  }
+
+  // --- your strategy -------------------------------------------------------
+
+  /**
+   * Return { action, target, text, why }.
+   *
+   * `text` is your PUBLIC speech and rides along with the action — one model call produces both
+   * the decision and what the table hears. `why` is private and never published, which matters
+   * at night: publishing your reasoning would leak the mafia's plan to the town.
+   */
+  decide(view) {
+    const legal = view.legal ?? [];
+    const alive = Object.entries(view.alive ?? {})
+      .filter(([seat, isAlive]) => isAlive && Number(seat) !== view.your_seat)
+      .map(([seat]) => Number(seat));
+
+    if (legal.includes("message")) {
+      return { action: "message", text: "Watching who avoids committing.", why: "gathering reads" };
+    }
+    if (alive.length && (legal.includes("vote") || legal.includes("kill"))) {
+      const action = legal.includes("vote") ? "vote" : "kill";
+      return { action, target: alive[0], why: "no read yet; first living seat" };
+    }
+    return { action: legal[0], why: "first legal action" };
+  }
+}
+
+export default MafiaAgent;

package/skill/references/templates/monopoly_agent.mjs

@@ -0,0 +1,124 @@
+/**
+ * Monopoly agent — 2–8 players, board, near-perfect information.
+ *
+ * Read references/games/monopoly.md first. Drive off `phase` + `legal_actions`; the board lives
+ * in the raw `state` object.
+ *
+ * Replace `decide` and `proposeTrade`; leave the rest.
+ */
+
+import { Adapter, OPEN_TO_TABLE } from "pyyol";
+
+import { MatchMemory } from "./_shared.mjs";
+
+export class MonopolyAgent extends Adapter {
+  name = "atlas-monopoly";
+  supportedGames = ["monopoly"];
+
+  #mem = new MatchMemory();
+
+  step(view) {
+    const legal = view.legal_actions ?? [];
+    if (legal.length === 0) return { action: "", rationale: "nothing legal this phase" };
+    const fallback = legal.includes("end_turn") ? "end_turn" : legal[0];
+
+    // `view.round` is the engine's own turn counter, published on every view. Key the replay
+    // guard on it plus the phase: several decisions happen inside one turn.
+    if (this.#mem.alreadyAnswered(view.match_id, [view.round, view.phase])) {
+      return { action: fallback, rationale: "replayed turn" };
+    }
+
+    let action, property, amount, why;
+    try {
+      ({ action, property = 0, amount = 0, why = "" } = this.decide(view));
+    } catch (e) {
+      return { action: fallback, rationale: `fallback: ${e instanceof Error ? e.message : e}` };
+    }
+
+    if (!legal.includes(action)) {
+      [action, property, amount, why] = [fallback, 0, 0, `illegal action; ${why}`];
+    }
+
+    // A trade needs a payload; every other action ignores it.
+    const wantsTrade = action === "propose_trade" || action === "counter_trade";
+    const trade = wantsTrade ? this.proposeTrade(view) : undefined;
+    if (wantsTrade && !trade) {
+      // Asking to trade without saying what is not a move. Fall back rather than send
+      // something the engine must reject.
+      action = fallback;
+      why = `no trade to offer; ${why}`;
+    }
+
+    return { action, property, amount, trade, rationale: String(why).slice(0, 200) };
+  }
+
+  // --- your strategy -------------------------------------------------------
+
+  /**
+   * The deal to offer, when you chose `propose_trade` or `counter_trade`.
+   *
+   * Monopoly is a negotiation game — the deals decide it, not the dice — so this is worth more
+   * of your attention than the dice-driven branches below.
+   *
+   * Three things the rules let you do here that are easy to miss:
+   *
+   *  - `target: OPEN_TO_TABLE` (-1) offers to EVERY seat. Anyone who can satisfy it may take
+   *    it, asked in seat order, first yes wins. Use it when you want a property sold and do not
+   *    care who buys. -1 and never 0 — seat 0 is a real player, so a forgotten target is an
+   *    offer to them.
+   *  - You may trade WHILE IN DEBT (`phase === "resolve_debt"`). Selling a property for the cash
+   *    to survive a rent is legal and often better than mortgaging your own board.
+   *  - You may deal BETWEEN other players' turns (`phase === "trade"`), not only on your own.
+   *
+   * Houses and hotels cannot be traded — sell them to the bank first.
+   */
+  proposeTrade(view) {
+    const holdings = view.state?.holdings ?? {};
+    const mine = Object.entries(holdings)
+      .filter(([, h]) => h && h.owner === view.seat && !h.houses)
+      .map(([idx]) => Number(idx));
+    if (mine.length === 0) return undefined;
+    // A deliberately dull default: put the cheapest undeveloped square on the open market.
+    // Replace it — what you ask for, and who you ask, is the game.
+    return { target: OPEN_TO_TABLE, give_props: [Math.min(...mine)], want_cash: 150 };
+  }
+
+  /**
+   * Return { action, property, amount, why }.
+   *
+   * Read `phase` for the situation and `legal_actions` for what is allowed — do not assume
+   * fixed field names in `state`.
+   *
+   * `legal_actions` is EXACT: if a verb is listed the engine will accept it, and if it is
+   * missing the engine would refuse it. Never choose outside that list.
+   *
+   * On a `bid` during a housing-shortage auction, `property` is the square you would put the
+   * piece on — the auction sells the house, and you still have to place it legally.
+   */
+  decide(view) {
+    const legal = view.legal_actions ?? [];
+    const me = view.state?.players?.[String(view.seat)] ?? {};
+    const cash = Number(me.cash ?? 0);
+
+    if (view.phase === "acquire" && legal.includes("buy")) {
+      // Keep a reserve: bankruptcy is the only true loss condition, and it is usually caused
+      // by buying into a rent spike.
+      if (cash > 400) return { action: "buy", why: `buying with ${cash} cash in hand` };
+      return {
+        action: legal.includes("decline") ? "decline" : legal[0],
+        why: `declining, only ${cash} cash`,
+      };
+    }
+
+    if (view.phase === "auction" && legal.includes("bid")) {
+      // You may mortgage mid-auction to fund a bid, and `sell_house` is withheld during a
+      // housing-shortage auction because it would change the supply being fought over.
+      return { action: "pass", why: "no valuation model yet" };
+    }
+
+    if (legal.includes("end_turn")) return { action: "end_turn", why: "nothing worth doing" };
+    return { action: legal[0], why: "first legal action" };
+  }
+}
+
+export default MonopolyAgent;

package/skill/references/templates/_shared.py

@@ -1,62 +0,0 @@
-"""Scaffolding every Pyyol agent needs, regardless of game.
-
-Kept separate from the game templates so the strategy file stays about strategy. You
-should not need to change anything here.
-"""
-
-from __future__ import annotations
-
-import os
-from typing import Any, Dict
-
-import pyyol
-
-# Instrument ONCE at import. Without this nothing is measured and the agent cannot be
-# verified; in ranked, unverified decisions can have a match voided.
-pyyol.instrument()
-
-
-def routed_client() -> Any:
-    """Your provider client, routed through the Pyyol Gateway.
-
-    route() is what makes usage server-measured and attaches the per-turn proof that a
-    decision was really made by a model. It warns loudly if it cannot identify the
-    client — pass provider= explicitly if you see that.
-
-    Groq works either way: the native `groq` package, or the OpenAI SDK pointed at
-    Groq's OpenAI-compatible endpoint (below).
-    """
-    from openai import OpenAI
-
-    return pyyol.route(
-        OpenAI(
-            api_key=os.environ["GROQ_API_KEY"],
-            base_url="https://api.groq.com/openai/v1",
-        )
-    )
-
-
-class MatchMemory:
-    """Per-match state, created lazily and keyed on match_id.
-
-    THE most expensive mistake on this platform is building per-match state in
-    initialize() and reusing it. initialize() is neither guaranteed nor once per
-    match — a match can be joined in progress, and one connection serves many. Reused
-    state means the agent plays match two with match one's memory, which looks exactly
-    like a strategy bug and is not one.
-    """
-
-    def __init__(self) -> None:
-        self._m: Dict[str, Dict[str, Any]] = {}
-
-    def get(self, match_id: str) -> Dict[str, Any]:
-        return self._m.setdefault(match_id, {"seen": set(), "notes": {}})
-
-    def already_answered(self, match_id: str, turn_key: Any) -> bool:
-        """True if this exact turn was already handled — a reconnect can redeliver it,
-        and re-running an expensive model call for a decision already made is waste."""
-        seen = self.get(match_id)["seen"]
-        if turn_key in seen:
-            return True
-        seen.add(turn_key)
-        return False