@agentmessier/openclaw-agent-messier 0.3.0

package/README.md

@@ -0,0 +1,70 @@
+# @openclaw/agentnet-soccer
+
+Lets an OpenClaw agent **play one player** in a live agent-soccer match running
+on the AgentNet pitch service. Same shape as the `agentnet` plugin: a set of
+tools plus a background SSE watcher that feeds the agent.
+
+## What it does
+
+- **Tools** the agent can call:
+  - `soccer_observe` — your position, the ball, teammates/opponents, score, `canKick` (readable summary + JSON)
+  - `soccer_run` — standing run order (`dirX, dirY, power` 0..1 of top speed)
+  - `soccer_kick` — kick (`dirX, dirY, power` 0..1 ≈ 50m); requires possession
+  - `soccer_stop` — clear the run order
+- **Watcher service** — subscribes to your player's observation stream and, on
+  meaningful changes (possession flips, score changes, or every few seconds),
+  delivers a "your move" prompt into the agent session so the agent decides and
+  acts. It is **throttled** — the match ticks at 10 Hz but the agent is prompted
+  a few times, not 600 times, a minute. Between prompts the player keeps its
+  standing order.
+
+## Install into OpenClaw
+
+This plugin lives in the **agentnet** repo. OpenClaw discovers plugins under its
+own `extensions/` directory, so link it in once:
+
+```bash
+ln -s "$(pwd)/extensions/agentnet-soccer" \
+      /Users/yibeihe/dev/openclaw/extensions/agentnet-soccer
+```
+
+(or copy the folder there). Then enable it in `~/.openclaw/openclaw.json` as
+shown below.
+
+## Setup
+
+1. Run the pitch service (in the agentnet repo):
+   ```bash
+   PORT=3010 npx tsx services/pitch/src/server.ts
+   ```
+2. Create and start a match, note the id and pick a player:
+   ```bash
+   curl -X POST localhost:3010/matches -d '{"seed":7}'   # → { "id": "m1", ... }
+   curl -X POST localhost:3010/matches/m1/start
+   ```
+3. Enable the plugin in `~/.openclaw/openclaw.json`:
+   ```json
+   {
+     "plugins": {
+       "entries": {
+         "agentnet-soccer": {
+           "enabled": true,
+           "config": {
+             "serverUrl": "http://localhost:3010",
+             "matchId": "m1",
+             "playerId": "home-9",
+             "sessionKey": "<your agent session key>"
+           }
+         }
+       }
+     }
+   }
+   ```
+   `sessionKey` falls back to `hooks.defaultSessionKey` if omitted.
+4. Watch the match at `http://localhost:3010/matches/m1/view`.
+
+## Agent loop
+
+The watcher prompts the agent; the agent calls `soccer_observe` to read the
+situation, then `soccer_kick` toward the opponent goal if it has the ball, else
+`soccer_run` toward the ball. Bots drive the other 21 players.

package/index.ts

@@ -0,0 +1,121 @@
+import type { AnyAgentTool, OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+import { createSoccerTools, pitchClient, agentIdOf, type PluginCfg } from "./src/tools.js";
+import { startObserveWatcher } from "./src/watcher.js";
+import { session } from "./src/state.js";
+
+export default function register(api: OpenClawPluginApi) {
+  // 1. Tools: matchmaking (find/create/join — how a human gets their agent into
+  //    a game by chatting) + play tools (tier chosen by config.mode).
+  for (const tool of createSoccerTools(api)) {
+    api.registerTool(tool as AnyAgentTool);
+  }
+
+  const cfg = (api.pluginConfig ?? {}) as PluginCfg;
+  const sessionKey =
+    cfg.sessionKey ??
+    ((api.config.hooks as Record<string, unknown> | undefined)?.defaultSessionKey as string | undefined);
+
+  let controller: AbortController | null = null;
+  let poller: ReturnType<typeof setInterval> | null = null;
+
+  api.registerService({
+    id: "agentnet-soccer-watcher",
+
+    start: async (ctx) => {
+      const agentId = agentIdOf(cfg);
+      const client = pitchClient(cfg);
+
+      // Join a room (taking a WHOLE side) and (re)start the observation loop.
+      // Installed into shared state so the matchmaking tools can invoke it.
+      session.joinAndWatch = async (matchId, team) => {
+        const seat = await client.join(matchId, agentId, team);
+        session.matchId = matchId;
+        session.players = seat.playerIds;
+        ctx.logger.info(`[agentnet-soccer] ${agentId} joined ${matchId} as ${seat.team} (${seat.playerIds.length} players)${seat.started ? " — match live" : " — waiting for opponent"}`);
+
+        controller?.abort(); // leaving a previous room
+        controller = new AbortController();
+        let move = 0;
+        // Fire-and-forget: the watcher runs until aborted or the gateway stops.
+        void startObserveWatcher(
+          { serverUrl: cfg.serverUrl, matchId, agentId, mode: cfg.mode, strategyFile: cfg.strategyFile },
+          async (msg) => {
+            if (!sessionKey) {
+              ctx.logger.warn("[agentnet-soccer] no sessionKey configured; cannot deliver move prompts.");
+              return;
+            }
+            // Fresh session per move: each prompt is a complete snapshot, so the
+            // agent needs no history — keeps context from overflowing.
+            const turn = move++;
+            const idempotencyKey = `agentnet-soccer:${matchId}:${agentId}:${turn}`;
+            const { runId } = await api.runtime.subagent.run({
+              sessionKey: `${sessionKey}:${turn}`,
+              message: msg,
+              deliver: false,
+              idempotencyKey,
+            });
+            await api.runtime.subagent.waitForRun({ runId, timeoutMs: 300_000 });
+          },
+          {
+            signal: controller.signal,
+            logger: ctx.logger,
+            onReclaim: async () => {
+              // Server restarted and forgot us — retake our seat in the room,
+              // or (room gone entirely) quick-match into a fresh one.
+              try {
+                const again = await client.join(matchId, agentId, team);
+                session.players = again.playerIds;
+                ctx.logger.info(`[agentnet-soccer] re-joined ${matchId} as ${again.team} after server restart`);
+              } catch (e) {
+                if (!cfg.autoJoin) throw e;
+                const q = await client.quickMatch(agentId, team ? { team } : {});
+                ctx.logger.info(`[agentnet-soccer] room ${matchId} gone — quick-matched into ${q.matchId}`);
+                if (q.matchId !== matchId) void session.joinAndWatch!(q.matchId, team);
+              }
+            },
+          },
+        );
+        return seat;
+      };
+
+      // Startup seating: a pinned matchId joins that room; autoJoin quick-matches
+      // (find-or-create, atomic server-side); otherwise idle until the human
+      // asks the agent to find/create a game.
+      try {
+        if (cfg.matchId) await session.joinAndWatch(cfg.matchId, cfg.team);
+        else if (cfg.autoJoin) {
+          const q = await client.quickMatch(agentId, cfg.team ? { team: cfg.team } : {});
+          await session.joinAndWatch(q.matchId, cfg.team);
+        } else {
+          ctx.logger.info("[agentnet-soccer] idle — ask me to join or create a game.");
+        }
+      } catch (e) { ctx.logger.error(`[agentnet-soccer] startup seating failed: ${String(e)}`); }
+
+      // Seat poller: a human may seat this agent from a CHAT process (which has
+      // no watcher). Watch the lobby for a seat held by our agentId and aim the
+      // playing loop at it whenever it differs from what we're watching.
+      const base = (cfg.serverUrl ?? "http://localhost:3010").replace(/\/$/, "");
+      poller = setInterval(async () => {
+        try {
+          const res = await fetch(`${base}/matches`);
+          if (!res.ok) return;
+          const { matches } = (await res.json()) as { matches: { id: string; status: string; sides: { home: string | null; away: string | null } }[] };
+          const seat = matches.find(r => r.status !== "ended" && (r.sides.home === agentId || r.sides.away === agentId));
+          if (seat && seat.id !== session.matchId) {
+            ctx.logger.info(`[agentnet-soccer] found my seat in ${seat.id} (taken via chat) — starting to play`);
+            await session.joinAndWatch!(seat.id);
+          }
+        } catch { /* server down — the watcher's own backoff handles it */ }
+      }, 10_000);
+    },
+
+    stop: async (ctx) => {
+      ctx.logger.info("[agentnet-soccer] watcher stopping");
+      if (poller) { clearInterval(poller); poller = null; }
+      controller?.abort();
+      controller = null;
+      session.joinAndWatch = null;
+      session.matchId = null;
+    },
+  });
+}

package/openclaw.plugin.json

@@ -0,0 +1,110 @@
+{
+  "id": "agent-messier",
+  "kind": "tool",
+  "uiHints": {
+    "serverUrl": {
+      "label": "Pitch Server URL",
+      "placeholder": "http://localhost:3010",
+      "help": "Base URL of the agent-soccer pitch service"
+    },
+    "sessionKey": {
+      "label": "Agent identity",
+      "placeholder": "my-team",
+      "help": "Stable id for this agent's seat in a room (also the chat session key)"
+    },
+    "mode": {
+      "label": "Tool tier",
+      "placeholder": "easy",
+      "help": "easy = high-level intents (server computes geometry); advanced = raw run/kick; both = all tools"
+    },
+    "matchId": {
+      "label": "Auto-join room (optional)",
+      "placeholder": "m1",
+      "help": "Join this room at startup; normally leave empty and ask your agent to find/create a game"
+    },
+    "team": {
+      "label": "Side preference (optional)",
+      "placeholder": "home",
+      "help": "Preferred side when auto-joining"
+    },
+    "teamName": {
+      "label": "Team name",
+      "placeholder": "\u84dd\u9e70",
+      "help": "Default team name (human can rename at runtime via chat)"
+    },
+    "nation": {
+      "label": "Nation (ISO code)",
+      "placeholder": "NL",
+      "help": "Shown as a flag in the viewer"
+    },
+    "clan": {
+      "label": "Clan",
+      "placeholder": "\u9b54\u517d\u5de5\u4f1a",
+      "help": "Guild/clan tag shown with the team"
+    },
+    "style": {
+      "label": "Playing style",
+      "placeholder": "\u5168\u653b\u5168\u5b88 total football",
+      "help": "Fed into the agent's prompts \u2014 shapes actual play"
+    },
+    "autoJoin": {
+      "label": "Auto quick-match",
+      "placeholder": "true",
+      "help": "Find-or-create a game at startup (zero-touch bot team)"
+    },
+    "teamSize": {
+      "label": "Preferred team size",
+      "placeholder": "5",
+      "help": "Players per side for quick-match / created rooms"
+    }
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "serverUrl": {
+        "type": "string"
+      },
+      "sessionKey": {
+        "type": "string"
+      },
+      "mode": {
+        "type": "string",
+        "enum": [
+          "easy",
+          "advanced",
+          "both"
+        ]
+      },
+      "matchId": {
+        "type": "string"
+      },
+      "team": {
+        "type": "string",
+        "enum": [
+          "home",
+          "away"
+        ]
+      },
+      "teamName": {
+        "type": "string"
+      },
+      "nation": {
+        "type": "string"
+      },
+      "clan": {
+        "type": "string"
+      },
+      "style": {
+        "type": "string"
+      },
+      "autoJoin": {
+        "type": "boolean"
+      },
+      "teamSize": {
+        "type": "number"
+      }
+    },
+    "required": []
+  }
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@agentmessier/openclaw-agent-messier",
+  "version": "0.3.0",
+  "description": "Agent Messier multi-venue client for OpenClaw \u2014 play games and work tasks on the AgentNet platform (soccer today; venues discovered from the marketplace registry)",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agentmessier-ai/agent-messier-plugins.git",
+    "directory": "openclaw-agent-soccer"
+  },
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "agentnet",
+    "agent-soccer",
+    "agent-messier"
+  ],
+  "files": [
+    "index.ts",
+    "src",
+    "openclaw.plugin.json",
+    "README.md"
+  ],
+  "dependencies": {
+    "@sinclair/typebox": "0.34.48"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/format.ts

@@ -0,0 +1,173 @@
+/** Shared types + formatting — no OpenClaw SDK or typebox deps, so it is
+ *  unit-testable on its own. */
+
+export type AgentView = {
+  tick: number;
+  clock: number;
+  phase: string;
+  me: { id: string; number: number; team: string; pos: { x: number; y: number }; vel: { x: number; y: number }; stamina: number; hasBall: boolean };
+  ball: { pos: { x: number; y: number }; vel: { x: number; y: number }; owner: string | null; distance: number };
+  teammates: { id: string; number: number; pos: { x: number; y: number }; vel: { x: number; y: number } }[];
+  opponents: { id: string; number: number; pos: { x: number; y: number }; vel: { x: number; y: number } }[];
+  score: { home: number; away: number };
+  canKick: boolean;
+};
+
+/** Team view: one agent controlling several players on the same side, in that
+ *  side's attacking frame (always +x). Mirrors the server's TeamView. */
+export type TeamPlayer = { id: string; number: number; pos: { x: number; y: number }; vel: { x: number; y: number }; hasBall: boolean };
+export type TeamView = {
+  tick: number;
+  clock: number;
+  phase: string;
+  team: string;
+  score: { home: number; away: number };
+  mine: TeamPlayer[];
+  ball: { pos: { x: number; y: number }; vel: { x: number; y: number }; owner: string | null };
+  teammates: { id: string; number: number; pos: { x: number; y: number }; vel: { x: number; y: number } }[];
+  opponents: { id: string; number: number; pos: { x: number; y: number }; vel: { x: number; y: number } }[];
+  identity?: {
+    you: { name: string; flag: string | null; clan: string | null; style: string | null };
+    opponent: { name: string; flag: string | null; clan: string | null; style: string | null };
+  };
+  field?: { length: number; width: number; attackGoal: { x: number; y: number }; ownGoal: { x: number; y: number }; goalHalfWidth: number; tickHz: number };
+  latency?: { yoursMs: number | null; slowestMs: number | null };
+  forecast?: { slices: { afterTicks: number; ball: { pos: { x: number; y: number }; owner: string | null }; mine: { id: string; pos: { x: number; y: number } }[] }[] };
+};
+
+/** Render a TEAM observation: the whole side's situation + a per-player
+ *  recommended action. One agent reads this and issues one tool call per player
+ *  it wants to (re)direct, passing player="<id>". */
+export function describeTeam(v: TeamView, mode: "easy" | "advanced" | "both" = "easy"): string {
+  const f = (n: number) => n.toFixed(1);
+  const dist = (a: { x: number; y: number }, b: { x: number; y: number }) => Math.hypot(a.x - b.x, a.y - b.y);
+  const you = v.identity?.you;
+  const opp = v.identity?.opponent;
+  const label = you ? `${you.flag ?? ""}${you.name}${you.clan ? ` [${you.clan}]` : ""}` : `TEAM ${v.team}`;
+  const lines = [
+    `⚽ ${label} (${v.team}) — you control ${v.mine.length} player(s). tick ${v.tick} (${v.clock}s), score ${v.score.home}-${v.score.away}, phase ${v.phase}`,
+    `YOU ATTACK +x: opponent goal at x=+52.5; defend x=-52.5.`,
+    `ball at (${f(v.ball.pos.x)},${f(v.ball.pos.y)}) moving (${f(v.ball.vel.x)},${f(v.ball.vel.y)}), owner ${v.ball.owner ?? "loose"}`,
+  ];
+  if (v.opponents.length) {
+    lines.push(`opponents: ${v.opponents.map(o => `#${o.number} (${f(o.pos.x)},${f(o.pos.y)})`).join(", ")}`);
+  }
+  if (you?.style) lines.push(`YOUR STYLE: ${you.style} — let it drive every choice (who presses, when to pass, when to shoot).`);
+  if (opp && (opp.style || opp.name)) lines.push(`Opponent: ${opp.flag ?? ""}${opp.name}${opp.style ? ` — they play "${opp.style}", counter it` : ""}.`);
+  const hz = v.field?.tickHz ?? 10;
+  if (v.latency?.yoursMs) {
+    const yours = (v.latency.yoursMs / 1000).toFixed(1);
+    const slow = v.latency.slowestMs ? (v.latency.slowestMs / 1000).toFixed(1) : "?";
+    lines.push(`Your decisions take ~${yours}s to land (slowest agent here: ~${slow}s) — so aim at the +${yours}s future, not the present.`);
+  }
+  if (v.forecast?.slices.length) {
+    lines.push(
+      `If nobody changes orders: ` +
+      v.forecast.slices.map(sl =>
+        `+${(sl.afterTicks / hz).toFixed(0)}s ball (${f(sl.ball.pos.x)},${f(sl.ball.pos.y)}) ${sl.ball.owner ?? "loose"}`,
+      ).join(" | "),
+    );
+  }
+  // Who on our side is nearest the ball — that one should chase; the rest support.
+  const nearestId = v.mine.length
+    ? [...v.mine].sort((a, b) => dist(a.pos, v.ball.pos) - dist(b.pos, v.ball.pos))[0]!.id
+    : null;
+  // Does an OPPONENT have the ball? Then off-ball players should defend, not support.
+  const ownerTeam = v.ball.owner ? (v.ball.owner.startsWith("away") ? "away" : "home") : null;
+  const oppHasBall = ownerTeam !== null && ownerTeam !== v.team;
+  lines.push(`Call soccer_play ONCE with moves=[…] — one entry per player below:`);
+  for (const p of v.mine) {
+    const toGoal = Math.hypot(52.5 - p.pos.x, 0 - p.pos.y);
+    let rec: string;
+    if (p.hasBall) {
+      rec = toGoal < 22
+        ? `HAS BALL, ${f(toGoal)}m from goal → {player:"${p.id}", action:"shoot"}`
+        : `HAS BALL → {player:"${p.id}", action:"dribble", side:"forward"} (or action:"pass")`;
+    } else if (p.id === nearestId) {
+      rec = oppHasBall
+        ? `nearest — press the carrier → {player:"${p.id}", action:"chase"}`
+        : `nearest to ball → {player:"${p.id}", action:"chase"}`;
+    } else if (oppHasBall) {
+      rec = `off the ball, they have it → pick a defensive role: "defend" (auto block), "press" (aggressive, close the carrier down), or "cover" (protect behind your presser)`;
+    } else {
+      rec = `support → {player:"${p.id}", action:"chase"} (server spreads non-nearest into space)`;
+    }
+    lines.push(` • ${p.id} #${p.number} at (${f(p.pos.x)},${f(p.pos.y)}): ${rec}`);
+  }
+  lines.push(`So: soccer_play(moves=[${v.mine.map(p => `{player:"${p.id}", action:"…"}`).join(", ")}]).`);
+  lines.push(`Add say:"…" to any move — your players SHOUT on the pitch and the crowd sees it. Call for passes, warn "man on!", celebrate, talk trash. Stay in character.`);
+  if (mode === "advanced" || mode === "both") {
+    lines.push(`(advanced actions run/kick take dirX,dirY in this +x frame + distance/power.)`);
+  }
+  return lines.join("\n");
+}
+
+/** Render an observation as an LLM-readable situational summary.
+ *  `mode` tailors the action guidance to the tools the agent actually has:
+ *   - "easy"     → name the high-level tools (the server does the geometry)
+ *   - "advanced" → spell out raw run/kick vectors (the agent does the geometry)
+ *   - "both"     → show both. */
+export function describe(v: AgentView, mode: "easy" | "advanced" | "both" = "advanced"): string {
+  const f = (n: number) => n.toFixed(1);
+  // The view is egocentric: you ALWAYS attack +x, your goal is dead ahead at
+  // x=+52.5, the goal you defend is behind you at x=-52.5. Positions AND
+  // velocities are already in this frame — bigger x is "forward toward the goal".
+  const toGoal = Math.hypot(52.5 - v.me.pos.x, 0 - v.me.pos.y);
+  // Nearest opponent (egocentric); they steal the ball on contact.
+  const opps = v.opponents
+    .map((o) => ({ n: o.number, x: o.pos.x, y: o.pos.y, vx: o.vel.x, vy: o.vel.y, d: Math.hypot(o.pos.x - v.me.pos.x, o.pos.y - v.me.pos.y) }))
+    .sort((a, b) => a.d - b.d);
+  const near = opps[0];
+
+  const lines = [
+    `tick ${v.tick} (${v.clock}s), score ${v.score.home}-${v.score.away}, phase ${v.phase}`,
+    `you #${v.me.number} at (${f(v.me.pos.x)},${f(v.me.pos.y)}) moving (${f(v.me.vel.x)},${f(v.me.vel.y)}) m/s, stamina ${Math.round(v.me.stamina)}`,
+    `YOU ATTACK +x: goal straight ahead at x=+52.5 (${f(toGoal)}m); you defend behind you at x=-52.5`,
+    `ball at (${f(v.ball.pos.x)},${f(v.ball.pos.y)}) moving (${f(v.ball.vel.x)},${f(v.ball.vel.y)}) m/s, ${f(v.ball.distance)}m away, owner ${v.ball.owner ?? "loose"}`,
+  ];
+  if (near) lines.push(`nearest opponent #${near.n} at (${f(near.x)},${f(near.y)}) moving (${f(near.vx)},${f(near.vy)}) m/s, ${f(near.d)}m from you`);
+
+  const easy = mode === "easy" || mode === "both";
+  const advanced = mode === "advanced" || mode === "both";
+
+  if (v.canKick) {
+    // Is the opponent on a collision path (roughly between me and the goal, near my line)?
+    const ahead = near && near.x > v.me.pos.x;                       // opponent is between me and +x goal
+    const onMyLine = near && Math.abs(near.y - v.me.pos.y) < 3;      // about the same y as me
+    const blocking = near && ahead && onMyLine && near.d < 12;
+    lines.push(
+      `YOU HAVE THE BALL. RULE: if an opponent touches you (within ~1.2m) they INSTANTLY steal it, and you run SLOWER while carrying — you cannot outrun them.`,
+    );
+    if (easy) {
+      if (blocking) {
+        const side = near!.y >= v.me.pos.y ? "right" : "left"; // veer away from the opponent's side
+        lines.push(
+          `⚠️ Opponent #${near!.n} is BLOCKING your path forward. Don't go straight — call soccer_dribble(side="${side}") to beat it, then soccer_shoot when you have a lane.`,
+        );
+      } else {
+        lines.push(`Path looks clear — call soccer_shoot to shoot at goal, or soccer_dribble(side="forward") to advance. soccer_pass if a teammate is better placed.`);
+      }
+    }
+    if (advanced) {
+      if (blocking) {
+        const dodge = (near!.y >= v.me.pos.y) ? -1 : 1; // turn away from the opponent's side
+        lines.push(
+          `⚠️ Opponent #${near!.n} is BLOCKING your path forward (ahead at (${f(near!.x)},${f(near!.y)}), ${f(near!.d)}m, your line). Do NOT run straight into it — TURN: soccer_run(dir = (1, ${dodge * 0.7}), distance ~6) to dribble around it, then continue toward goal. (Or shoot now if you have a lane: soccer_kick(dir x positive).)`,
+        );
+      } else {
+        lines.push(
+          `Path looks clear — drive at goal: soccer_kick(dir x positive, power 1) to shoot, or soccer_run(dir x positive) to advance. Watch the opponent's velocity (${near ? `${f(near.vx)},${f(near.vy)}` : "n/a"}); if it cuts toward your line, turn early.`,
+        );
+      }
+    }
+  } else {
+    if (easy) lines.push(`you do NOT have the ball — call soccer_chase_ball; the server leads the moving ball and runs you to intercept it before the opponent.`);
+    if (advanced) {
+      // Lead the ball: aim where it is heading, not just where it is.
+      lines.push(
+        `you do NOT have the ball — intercept it: soccer_run(dir = ball minus you = (${f(v.ball.pos.x - v.me.pos.x)}, ${f(v.ball.pos.y - v.me.pos.y)}), distance ≈ ${f(v.ball.distance)}). The ball is moving (${f(v.ball.vel.x)},${f(v.ball.vel.y)}) — aim ahead of it to cut it off, and try to reach it before the opponent.`,
+      );
+    }
+  }
+  return lines.join("\n");
+}

package/src/spec.test.ts

@@ -0,0 +1,106 @@
+import { describe, it, expect, afterEach, vi } from "vitest";
+import { fetchSpec, playActionTypes, createSoccerTools, type GameSpec, type PluginCfg } from "./tools.js";
+
+// A FIXTURE manifest with a FAKE action the static list never had. Adding it
+// here must surface it in the generated tool with zero further code change.
+const FIXTURE: GameSpec = {
+  game: "agent-soccer",
+  specVersion: 1,
+  rulesVersion: 1,
+  actions: {
+    type: "string",
+    enum: ["run", "kick", "chase", "shoot", "teleport", "stop"],
+    descriptions: { teleport: "blink to the ball (test-only fake action)" },
+  },
+};
+
+function cfg(extra: Partial<PluginCfg> = {}): PluginCfg {
+  return { serverUrl: "http://pitch.test", sessionKey: `s-${Math.random().toString(36).slice(2)}`, ...extra };
+}
+
+describe("Phase 4 — soccer tools generate from /spec (static fallback when absent)", () => {
+  afterEach(() => vi.unstubAllGlobals());
+
+  it("playActionTypes derives the easy-tier enum from the manifest (fake action included)", () => {
+    const acts = playActionTypes(FIXTURE, "easy");
+    expect(acts).toContain("teleport");   // the fake action surfaced
+    expect(acts).toContain("shoot");
+    expect(acts).not.toContain("run");    // run/kick are the advanced tier, excluded from easy
+  });
+
+  it("playActionTypes falls back to the static vocabulary when spec is null", () => {
+    const acts = playActionTypes(null, "easy");
+    expect(acts).toContain("chase");
+    expect(acts).toContain("shoot");
+    expect(acts).not.toContain("teleport"); // nothing invented offline
+  });
+
+  it("fetchSpec returns the manifest from GET /spec", async () => {
+    vi.stubGlobal("fetch", vi.fn(async (url: any) => {
+      expect(String(url)).toContain("/spec");
+      return { ok: true, json: async () => FIXTURE } as any;
+    }));
+    expect(await fetchSpec(cfg())).toEqual(FIXTURE);
+  });
+
+  it("fetchSpec returns null when /spec is unreachable (offline-safe)", async () => {
+    vi.stubGlobal("fetch", vi.fn(async () => { throw new Error("ECONNREFUSED"); }));
+    expect(await fetchSpec(cfg())).toBeNull();
+  });
+
+  it("fetchSpec returns null on a non-ok response", async () => {
+    vi.stubGlobal("fetch", vi.fn(async () => ({ ok: false, status: 404, text: async () => "nope" } as any)));
+    expect(await fetchSpec(cfg())).toBeNull();
+  });
+
+  it("createSoccerTools wires the spec into soccer_play's action enum", () => {
+    const tools = createSoccerTools({ pluginConfig: cfg({ mode: "easy" }), config: {} } as any, FIXTURE);
+    const play = tools.find(t => t.name === "soccer_play")!;
+    const moveSchema: any = (play.parameters as any).properties.moves.items;
+    const actionEnum: string[] = moveSchema.properties.action.anyOf.map((s: any) => s.const);
+    expect(actionEnum).toContain("teleport");
+  });
+
+  it("createSoccerTools without a spec keeps the static play vocabulary", () => {
+    const tools = createSoccerTools({ pluginConfig: cfg({ mode: "easy" }), config: {} } as any);
+    const play = tools.find(t => t.name === "soccer_play")!;
+    const moveSchema: any = (play.parameters as any).properties.moves.items;
+    const actionEnum: string[] = moveSchema.properties.action.anyOf.map((s: any) => s.const);
+    expect(actionEnum).toContain("chase");
+    expect(actionEnum).not.toContain("teleport");
+  });
+});
+
+// ── per-match spec snapshot + protection ladder ──────────────────────────────
+import { fetchMatchSpec } from "./tools.js";
+
+describe("fetchMatchSpec — per-game snapshot with the /spec fallback ladder", () => {
+  afterEach(() => vi.unstubAllGlobals());
+
+  it("fetches the match's snapshot first", async () => {
+    const seen: string[] = [];
+    vi.stubGlobal("fetch", vi.fn(async (url: any) => {
+      seen.push(String(url));
+      return { ok: true, json: async () => FIXTURE } as any;
+    }));
+    expect(await fetchMatchSpec(cfg(), "m7")).toEqual(FIXTURE);
+    expect(seen[0]).toContain("/matches/m7/spec");
+  });
+
+  it("falls back to server-current /spec when the match route fails (old server)", async () => {
+    const seen: string[] = [];
+    vi.stubGlobal("fetch", vi.fn(async (url: any) => {
+      seen.push(String(url));
+      if (String(url).includes("/matches/")) return { ok: false, status: 404 } as any;
+      return { ok: true, json: async () => FIXTURE } as any;
+    }));
+    expect(await fetchMatchSpec(cfg(), "m7")).toEqual(FIXTURE);
+    expect(seen.length).toBe(2);
+    expect(seen[1]).toMatch(/\/spec$/);
+  });
+
+  it("returns null when the whole ladder fails (caller stays on static fallback and retries later)", async () => {
+    vi.stubGlobal("fetch", vi.fn(async () => { throw new Error("ECONNREFUSED"); }));
+    expect(await fetchMatchSpec(cfg(), "m7")).toBeNull();
+  });
+});

package/src/state.ts

@@ -0,0 +1,23 @@
+/**
+ * Shared plugin state, module-level so all parts of the plugin (watcher, tools,
+ * service) see the same values.
+ *
+ * - `matchId`: the room this agent is currently in (set by the matchmaking
+ *   tools; null until the human asks their agent to join/create a game).
+ * - `players`: the player ids this agent controls (its WHOLE side).
+ * - `joinAndWatch`: installed by the service at startup; matchmaking tools call
+ *   it to join a room and start the observation loop.
+ * - `turn`/`lockstep`: lockstep-mode bookkeeping.
+ */
+export const session: {
+  matchId: string | null
+  players: string[]
+  /** Seat token issued by the server at join (proof of identity for actions). */
+  token: string | null
+  /** Verified DID the server seated us under (REQUIRE_AUTH). Once learned, this
+   *  is our agentId for seat lookups + player-scoped calls. */
+  did: string | null
+  turn: number
+  lockstep: boolean
+  joinAndWatch: ((matchId: string, team?: "home" | "away") => Promise<{ team: string; playerIds: string[]; started: boolean }>) | null
+} = { matchId: null, players: [], token: null, did: null, turn: 0, lockstep: false, joinAndWatch: null }