@agentmessier/openclaw-agent-messier 0.3.0 → 0.3.2

package/index.ts

@@ -1,16 +1,45 @@
 import type { AnyAgentTool, OpenClawPluginApi } from "openclaw/plugin-sdk/core";
-import { createSoccerTools, pitchClient, agentIdOf, type PluginCfg } from "./src/tools.js";
+import { memberTools, venuesTool, agentIdOf, identityOf, venueUrl, type PluginCfg } from "./src/tools.js";
+import { defaultVenueTools, defaultRealtimeVenue, joinVenue } from "./src/generate.js";
 import { startObserveWatcher } from "./src/watcher.js";
 import { session } from "./src/state.js";
 
+/** A lobby row is "ours" if it references our agentId anywhere (soccer puts it in
+ *  sides.home/away; a generic venue may shape it differently). Deep, shape-blind. */
+function referencesAgent(value: unknown, agentId: string): boolean {
+  if (value === agentId) return true;
+  if (Array.isArray(value)) return value.some((v) => referencesAgent(v, agentId));
+  if (value && typeof value === "object") return Object.values(value).some((v) => referencesAgent(v, agentId));
+  return false;
+}
+const ENDED = new Set(["ended", "finished", "completed", "done", "cancelled", "canceled"]);
+
 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)) {
+  const cfg = (api.pluginConfig ?? {}) as PluginCfg;
+
+  // 1. Tools: per-venue lifecycle tools GENERATED from each venue's spec
+  //    (soccer_matches/join/observe/play, work_observe/act, …) + soccer member
+  //    perks (skins/rename/claim) + the platform `venues` registry tool. A new
+  //    venue appears here from its spec with zero plugin code.
+  for (const tool of [...defaultVenueTools(cfg), ...memberTools(cfg), venuesTool(cfg)]) {
     api.registerTool(tool as AnyAgentTool);
   }
 
-  const cfg = (api.pluginConfig ?? {}) as PluginCfg;
+  // 2. Autoplay watcher. It drives ONE realtime venue (streams observations,
+  //    seats the agent, offers hands-free play) entirely from {venue, spec} —
+  //    seating via spec.client.join, observe/act endpoints via spec.routes, the
+  //    move prompt naming spec.client.act.tool. No venue is hardcoded here;
+  //    soccer is simply the only realtime venue today. Seatless/poll venues
+  //    (taskmarket) have no autoplay loop, so the service no-ops for them.
+  const realtime = defaultRealtimeVenue();
+  if (!realtime) return;
+  const { venue, spec } = realtime;
+  const label = venue.id;
+  const actTool = spec.client!.act.tool;
+  const lobbyRoute = spec.client?.lobby?.route;
+  const roomIdField = spec.client?.join?.seat.id ?? "id";
+  const base = venueUrl(venue.origin, cfg);
+
   const sessionKey =
     cfg.sessionKey ??
     ((api.config.hooks as Record<string, unknown> | undefined)?.defaultSessionKey as string | undefined);
@@ -19,35 +48,37 @@ export default function register(api: OpenClawPluginApi) {
   let poller: ReturnType<typeof setInterval> | null = null;
 
   api.registerService({
-    id: "agentnet-soccer-watcher",
+    id: `agentnet-${venue.id}-watcher`,
 
     start: async (ctx) => {
       const agentId = agentIdOf(cfg);
-      const client = pitchClient(cfg);
+      // Config-derived join body. For soccer these are teamSize/team/identity; a
+      // venue whose spec doesn't use them simply leaves the cfg fields unset and
+      // the server ignores the extras. joinVenue itself stays venue-agnostic.
+      const joinExtra = (): Record<string, unknown> => ({ teamSize: cfg.teamSize, team: cfg.team, identity: identityOf(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"}`);
+      // Seat into a room (matchId omitted = quickmatch find-or-create) and
+      // (re)start the observation loop. Installed into shared state so the
+      // generated *_join tool / chat handoff can drive it.
+      session.joinAndWatch = async (matchId, params) => {
+        const seat = await joinVenue(venue, spec, cfg, { matchId, params: params ?? {}, extra: joinExtra() });
+        ctx.logger.info(`[${label}] ${agentId} seated in ${seat.id} (${seat.controls?.length ?? 0} to control)${seat.started ? " — 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 },
+          { serverUrl: cfg.serverUrl, matchId: seat.id!, agentId, mode: cfg.mode, strategyFile: cfg.strategyFile, actTool, label },
           async (msg) => {
             if (!sessionKey) {
-              ctx.logger.warn("[agentnet-soccer] no sessionKey configured; cannot deliver move prompts.");
+              ctx.logger.warn(`[${label}] 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 idempotencyKey = `agentnet:${venue.id}:${seat.id}:${agentId}:${turn}`;
             const { runId } = await api.runtime.subagent.run({
               sessionKey: `${sessionKey}:${turn}`,
               message: msg,
@@ -60,17 +91,16 @@ export default function register(api: OpenClawPluginApi) {
             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.
+              // Server restarted and forgot us — re-seat into the same room via
+              // seatRoute, or (room gone) quickmatch 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`);
+                const again = await joinVenue(venue, spec, cfg, { matchId: seat.id, extra: joinExtra() });
+                ctx.logger.info(`[${label}] re-seated in ${again.id} 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);
+                const q = await joinVenue(venue, spec, cfg, { extra: joinExtra() });
+                ctx.logger.info(`[${label}] room ${seat.id} gone — re-quickmatched into ${q.id}`);
+                if (q.id !== seat.id) void session.joinAndWatch!(undefined);
               }
             },
           },
@@ -78,39 +108,42 @@ export default function register(api: OpenClawPluginApi) {
         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.
+      // Startup seating: a pinned matchId seats that room; autoJoin quick-matches
+      // (find-or-create, atomic server-side); otherwise idle until asked.
       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)}`); }
+        if (cfg.matchId) await session.joinAndWatch(cfg.matchId);
+        else if (cfg.autoJoin) await session.joinAndWatch(undefined);
+        else ctx.logger.info(`[${label}] idle — ask me to join or create a game.`);
+      } catch (e) { ctx.logger.error(`[${label}] 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);
+      // Seat poller: when the agent is IDLE, a seat may be taken from ANOTHER
+      // process (a chat turn, the generated *_join tool, the dashboard). Poll the
+      // venue's lobby for a non-ended room referencing our agentId and adopt it.
+      // Driven by spec.client.lobby.route — no hardcoded /matches path. Skipped
+      // when a match is pinned (explicit room wins) or the venue has no lobby.
+      // Critically it only adopts while idle (session.matchId empty): once we're
+      // in a match it must NOT yank us into some other (e.g. stale) room.
+      if (lobbyRoute && !cfg.matchId) {
+        poller = setInterval(async () => {
+          if (session.matchId) return; // already seated/playing → nothing to adopt
+          try {
+            const res = await fetch(`${base}${lobbyRoute}`);
+            if (!res.ok) return;
+            const data = (await res.json()) as Record<string, any>;
+            const rows = (data.matches ?? data.rows ?? []) as Record<string, any>[];
+            const mine = rows.find((r) => !ENDED.has(String(r.status ?? "")) && referencesAgent(r, agentId));
+            const id = mine?.id ?? mine?.[roomIdField];
+            if (id) {
+              ctx.logger.info(`[${label}] found my seat in ${id} (taken elsewhere) — starting to play`);
+              await session.joinAndWatch!(id);
+            }
+          } catch { /* server down — the watcher's own backoff handles it */ }
+        }, 10_000);
+      }
     },
 
     stop: async (ctx) => {
-      ctx.logger.info("[agentnet-soccer] watcher stopping");
+      ctx.logger.info(`[${label}] watcher stopping`);
       if (poller) { clearInterval(poller); poller = null; }
       controller?.abort();
       controller = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentmessier/openclaw-agent-messier",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "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",

package/src/generate.test.ts

@@ -0,0 +1,124 @@
+import { describe, it, expect, afterEach, vi } from "vitest";
+import { generateVenueTools, defaultVenueTools, joinVenue, seatOf, defaultRealtimeVenue, isRealtimeVenue, _resetSeats } from "./generate.js";
+import { session } from "./state.js";
+import type { GameSpec, PluginCfg } from "./tools.js";
+
+function cfg(extra: Partial<PluginCfg> = {}): PluginCfg {
+  return { serverUrl: "http://pitch.test", sessionKey: "did:wba:me", ...extra };
+}
+
+// A venue the plugin has NEVER heard of — proves tools come from the spec, not code.
+const GOLF_VENUE = { id: "agent-golf", origin: "http://golf.test", specUrl: "/spec" };
+const GOLF_SPEC: GameSpec = {
+  game: "agent-golf", specVersion: 1, rulesVersion: 1,
+  actions: { type: "string", enum: ["drive", "chip", "putt"], descriptions: { drive: "tee shot", putt: "on the green" } },
+  observe: { mode: "stream", suggestedIntervalMs: 3000 },
+  routes: { observe: "/rounds/{matchId}/agents/{did}/observe", act: "/rounds/{matchId}/players/{playerId}/swing" },
+  client: {
+    prefix: "golf", noun: "round",
+    lobby: { tool: "golf_rounds", route: "/rounds", params: {}, summary: "List rounds." },
+    join: { tool: "golf_join", route: "/quickround", seatRoute: "/rounds/{matchId}/join", params: { holes: { type: "integer" } }, seat: { id: "matchId", token: "token", controls: "playerIds" }, summary: "Join a round." },
+    autoplay: { tool: "golf_autoplay", summary: "Hands-free." },
+    observe: { tool: "golf_observe", params: {}, summary: "See the course." },
+    act: { tool: "golf_play", params: { club: { type: "string" } }, summary: "Swing." },
+  },
+};
+
+describe("generated tool surface comes entirely from the spec", () => {
+  it("baked soccer + taskmarket specs generate their canonical named tools", () => {
+    const names = defaultVenueTools(cfg()).map(t => t.name);
+    // soccer (a game, seated): lobby + join + observe + batch play
+    expect(names).toEqual(expect.arrayContaining(["soccer_matches", "soccer_join", "soccer_observe", "soccer_play"]));
+    // taskmarket (seatless work): observe + act, NO lobby/join
+    expect(names).toEqual(expect.arrayContaining(["work_observe", "work_act"]));
+    expect(names).not.toContain("work_join");
+  });
+
+  it("golf thesis: a brand-new venue's spec yields golf_* tools with ZERO plugin code", () => {
+    _resetSeats();
+    const tools = generateVenueTools(GOLF_VENUE, GOLF_SPEC, cfg());
+    const names = tools.map(t => t.name);
+    expect(names).toEqual(["golf_rounds", "golf_join", "golf_observe", "golf_play"]);
+
+    // The act tool is BATCH (golf seats players) and carries the spec's action enum.
+    const play = tools.find(t => t.name === "golf_play")!;
+    const enumList = (play.parameters as any).properties.moves.items.properties.type.enum;
+    expect(enumList).toEqual(["drive", "chip", "putt"]);
+    // Per-action descriptions from the spec flow into the tool description.
+    expect(play.description).toContain("drive: tee shot");
+  });
+
+  it("the act enum tracks the spec — a server-added action surfaces with no plugin edit", () => {
+    _resetSeats();
+    const evolved: GameSpec = { ...GOLF_SPEC, actions: { ...GOLF_SPEC.actions!, enum: [...GOLF_SPEC.actions!.enum, "flop"] } };
+    const play = generateVenueTools(GOLF_VENUE, evolved, cfg()).find(t => t.name === "golf_play")!;
+    expect((play.parameters as any).properties.moves.items.properties.type.enum).toContain("flop");
+  });
+});
+
+describe("joinVenue — the one spec-driven seating path (tool + service share it)", () => {
+  afterEach(() => { vi.unstubAllGlobals(); _resetSeats(); });
+
+  it("quickmatch (no matchId) posts to client.join.route and reads the seat block", async () => {
+    let url = "", body: any = null;
+    vi.stubGlobal("fetch", vi.fn(async (u: any, init?: any) => {
+      url = String(u); body = JSON.parse(init.body);
+      return { ok: true, json: async () => ({ matchId: "r7", token: "tok", playerIds: ["p1", "p2"], did: "did:wba:me", started: false }) } as any;
+    }));
+    const seat = await joinVenue(GOLF_VENUE, GOLF_SPEC, cfg({ sessionKey: "did:wba:me" }), { params: { holes: 9 } });
+    expect(url).toBe("http://golf.test/quickround");
+    expect(body.agentId).toBe("did:wba:me");
+    expect(body.holes).toBe(9);                       // whitelisted join param
+    expect(seat.id).toBe("r7");                        // seat.id field from spec
+    expect(seat.controls).toEqual(["p1", "p2"]);       // seat.controls field
+    expect(seat.token).toBe("tok");
+    expect(seatOf("agent-golf")?.id).toBe("r7");
+    expect(session.matchId).toBe("r7");                // mirrored for the watcher
+  });
+
+  it("rejoining a KNOWN room uses seatRoute with {matchId} substituted", async () => {
+    let url = "";
+    vi.stubGlobal("fetch", vi.fn(async (u: any) => {
+      url = String(u);
+      return { ok: true, json: async () => ({ matchId: "r7", token: "t", playerIds: ["p1"] }) } as any;
+    }));
+    await joinVenue(GOLF_VENUE, GOLF_SPEC, cfg(), { matchId: "r7" });
+    expect(url).toBe("http://golf.test/rounds/r7/join");
+  });
+
+  it("rejoin response without the seat-id field falls back to the matchId joined with", async () => {
+    _resetSeats();
+    // per-room join responses omit matchId (you already know it from the URL) —
+    // seat.id must still resolve, or the observe loop 404s and reclaim-loops.
+    vi.stubGlobal("fetch", vi.fn(async () =>
+      ({ ok: true, json: async () => ({ token: "t", playerIds: ["p1", "p2", "p3"], started: true }) }) as any));
+    const seat = await joinVenue(GOLF_VENUE, GOLF_SPEC, cfg(), { matchId: "r7" });
+    expect(seat.id).toBe("r7");
+    expect(session.matchId).toBe("r7");
+  });
+
+  it("service extras (teamSize/identity) ride along but tool calls omit them", async () => {
+    let body: any = null;
+    vi.stubGlobal("fetch", vi.fn(async (_u: any, init?: any) => {
+      body = JSON.parse(init.body);
+      return { ok: true, json: async () => ({ matchId: "r1", token: "t", playerIds: [] }) } as any;
+    }));
+    await joinVenue(GOLF_VENUE, GOLF_SPEC, cfg(), { params: { holes: 18 }, extra: { teamSize: 5, identity: { name: "Eagles" } } });
+    expect(body).toMatchObject({ holes: 18, teamSize: 5, identity: { name: "Eagles" } });
+  });
+});
+
+describe("realtime-venue detection (which venue the autoplay watcher drives)", () => {
+  it("a streamed + seated + autoplay venue is realtime; seatless/poll is not", () => {
+    expect(isRealtimeVenue(GOLF_SPEC)).toBe(true);
+    expect(isRealtimeVenue({ ...GOLF_SPEC, observe: { mode: "poll", suggestedIntervalMs: 1000 } })).toBe(false);
+    expect(isRealtimeVenue({ ...GOLF_SPEC, client: { ...GOLF_SPEC.client!, join: null } } as GameSpec)).toBe(false);
+    expect(isRealtimeVenue(null)).toBe(false);
+  });
+
+  it("the baked defaults pick soccer (realtime), never the seatless taskmarket", () => {
+    const rt = defaultRealtimeVenue();
+    expect(rt?.venue.id).toBe("agent-soccer");
+    expect(rt?.spec.client?.act.tool).toBe("soccer_play");
+  });
+});

package/src/generate.ts

@@ -0,0 +1,275 @@
+/**
+ * Generic per-venue tool generator (venue-agnostic-plugins.md §5.2) — the
+ * OpenClaw counterpart of the Hermes generate.py. Given a registry venue + its
+ * /spec (with a `client` lifecycle block), emit the named tools as
+ * `AnyAgentTool[]`. Handlers are GENERIC: endpoints from spec.routes, seat
+ * fields from spec.client.join.seat, action enum from spec.actions. Adding a
+ * venue = a registry row + a spec; no per-game code here.
+ *
+ * The act tool is a BATCH `moves` tool when the venue seats multiple players
+ * (a game — preserves the autoplay watcher's "one call, all players" prompt),
+ * and a SINGLE action when seatless (a work market). Names + descriptions come
+ * from the spec, so generated tools are as well-described as hand-crafted ones.
+ */
+import { Type } from "@sinclair/typebox";
+import type { AnyAgentTool } from "openclaw/plugin-sdk/core";
+import { ok, err, venueUrl, agentIdOf, apiKeyOf, rememberDid, rememberToken, type GameSpec, type PluginCfg } from "./tools.js";
+import { session } from "./state.js";
+
+export type Venue = { id: string; origin: string; specUrl?: string };
+export type Seat = { id?: string; token?: string; controls?: string[]; agentId?: string; started?: boolean; managerUrl?: string };
+
+// Seat per venue (id/token/controls/agentId). The soccer seat is mirrored into
+// `session` so the existing service watcher + seat-poller keep working.
+const seats = new Map<string, Seat>();
+export function _resetSeats(): void { seats.clear(); }
+export function seatOf(venueId: string): Seat | undefined { return seats.get(venueId); }
+
+function sub(route: string, kv: Record<string, string>): string {
+  return Object.entries(kv).reduce((r, [k, v]) => r.replace(`{${k}}`, encodeURIComponent(v)), route);
+}
+function did(venueId: string, cfg: PluginCfg): string {
+  return seats.get(venueId)?.agentId ?? agentIdOf(cfg);
+}
+
+/** One HTTP call to a venue, with every available auth header (the server uses
+ *  what it needs: Bearer→DID for games, x-caller-did for work, seat token for acts). */
+async function vfetch(base: string, path: string, opts: { method?: string; body?: unknown; cfg: PluginCfg; token?: string; did: string }): Promise<{ ok: boolean; status: number; data: any }> {
+  const headers: Record<string, string> = { "x-caller-did": opts.did, "x-agent-runtime": "openclaw-plugin/0.2.0" };
+  const key = apiKeyOf(opts.cfg); if (key) headers["Authorization"] = `Bearer ${key}`;
+  if (opts.token) headers["x-agent-token"] = opts.token;
+  if (opts.body !== undefined) headers["Content-Type"] = "application/json";
+  const res = await fetch(`${base}${path}`, { method: opts.method ?? "GET", headers, ...(opts.body !== undefined ? { body: JSON.stringify(opts.body) } : {}) });
+  const data = await res.json().catch(() => ({}));
+  return { ok: res.ok, status: res.status, data };
+}
+
+function asXY(v: unknown): { x: number; y: number } | null {
+  if (Array.isArray(v) && v.length === 2) { const x = Number(v[0]), y = Number(v[1]); return Number.isFinite(x) && Number.isFinite(y) ? { x, y } : null; }
+  return null;
+}
+function whitelist(params: Record<string, unknown>, props: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const k of Object.keys(props)) {
+    if (k === "player" || params[k] === undefined) continue; // player is the routing key, not a body field
+    out[k] = asXY(params[k]) ?? params[k];
+  }
+  return out;
+}
+
+// JSON-Schema props (from the spec) double as the TypeBox `parameters` object —
+// TypeBox schemas ARE plain JSON-schema at runtime, so the SDK accepts this.
+function paramsSchema(props: Record<string, unknown>, extra: Record<string, unknown> = {}, required: string[] = []): unknown {
+  return { type: "object", properties: { ...props, ...extra }, ...(required.length ? { required } : {}) };
+}
+
+/** Seat into a venue from its spec.client.join — the one join path, shared by
+ *  the generated `*_join` tool AND the autoplay service. `route` finds-or-creates
+ *  (quickmatch); `seatRoute` (if present) rejoins a KNOWN room. `extra` lets the
+ *  service inject config-derived body fields (teamSize/team/identity for soccer)
+ *  without this generic helper knowing any venue's semantics. Persists token+DID
+ *  to the cross-process cache so a seat taken here is usable from another process. */
+export async function joinVenue(
+  venue: Venue, spec: GameSpec, cfg: PluginCfg,
+  opts: { matchId?: string; params?: Record<string, unknown>; extra?: Record<string, unknown> } = {},
+): Promise<Seat> {
+  const j = spec.client?.join;
+  if (!j) throw new Error(`${venue.id} is not joinable (no client.join in spec)`);
+  const sm = j.seat;
+  const base = venueUrl(venue.origin, cfg);
+  const meId = agentIdOf(cfg);
+  const route = opts.matchId && j.seatRoute ? sub(j.seatRoute, { matchId: opts.matchId }) : j.route;
+  const body = { agentId: meId, ...(opts.extra ?? {}), ...whitelist(opts.params ?? {}, j.params ?? {}) };
+  const r = await vfetch(base, route, { cfg, did: meId, method: "POST", body });
+  if (!r.ok) throw new Error(`join ${venue.id}: ${r.status} ${JSON.stringify(r.data)}`);
+  const d = r.data;
+  if (typeof d.did === "string") rememberDid(cfg, d.did);     // cross-process identity
+  if (typeof d.token === "string") rememberToken(cfg, d.token); // cross-process seat token
+  // A rejoin via seatRoute already KNOWS the room (it's in the URL), so the
+  // server's response omits it — fall back to the matchId we joined with, or
+  // seat.id ends up undefined and the observe loop hits /…//… → 404 → reclaim.
+  const seat: Seat = { id: d[sm.id] ?? opts.matchId, token: d[sm.token], controls: d[sm.controls] ?? [], agentId: d.did ?? meId, started: d.started, managerUrl: d.managerUrl };
+  seats.set(venue.id, seat);
+  // soccer back-compat: the service watcher + seat-poller read `session`.
+  session.matchId = seat.id ?? null; session.players = seat.controls ?? []; session.token = seat.token ?? null; session.did = seat.agentId ?? null;
+  return seat;
+}
+
+export function generateVenueTools(venue: Venue, spec: GameSpec, cfg: PluginCfg): AnyAgentTool[] {
+  const c = spec.client!;
+  const base = venueUrl(venue.origin, cfg);
+  const enumList = spec.actions?.enum ?? [];
+  const descs = spec.actions?.descriptions ?? {};
+  const out: AnyAgentTool[] = [];
+
+  if (c.lobby) {
+    const s = c.lobby;
+    out.push({ name: s.tool, label: s.tool, description: s.summary, parameters: paramsSchema(s.params ?? {}),
+      async execute(_id, params) {
+        const r = await vfetch(base, s.route, { cfg, did: did(venue.id, cfg) });
+        if (!r.ok) return ok({ error: r.data?.error ?? `lobby ${r.status}` });
+        let rows = (r.data?.matches ?? r.data?.rows ?? []) as Record<string, unknown>[];
+        const want = String((params as any).status ?? "").trim().toLowerCase();
+        if (want) rows = rows.filter(x => x["status"] === want);
+        return ok({ count: rows.length, rows, hint: `join with ${c.prefix}_join` });
+      } } as AnyAgentTool);
+  }
+
+  if (c.join) {
+    const s = c.join;
+    out.push({ name: s.tool, label: s.tool, description: s.summary, parameters: paramsSchema(s.params ?? {}),
+      async execute(_id, params) {
+        try {
+          const seat = await joinVenue(venue, spec, cfg, { params: params as Record<string, unknown> });
+          return ok({ joined: seat.id, yours: seat.controls, watchUrl: `${base}/matches/${seat.id}/view`, managerUrl: seat.managerUrl,
+            note: `seated. observe with ${c.observe.tool}, then ${c.act.tool}.${seat.managerUrl ? " GIVE YOUR HUMAN the managerUrl — their console for this room." : ""}` });
+        } catch (e) { return ok({ error: String(e instanceof Error ? e.message : e) }); }
+      } } as AnyAgentTool);
+  }
+
+  // observe
+  {
+    const s = c.observe;
+    const route = spec.routes?.["state"] ?? spec.routes?.["observe"] ?? "/matches/{matchId}/agents/{did}/observe";
+    out.push({ name: s.tool, label: s.tool, description: s.summary, parameters: paramsSchema(s.params ?? {}),
+      async execute(_id, params) {
+        const seat = seats.get(venue.id) ?? {}; const d = did(venue.id, cfg);
+        let path = sub(route, { matchId: seat.id ?? "", did: d });
+        if ((s.params ?? {})["cursor"] !== undefined) path += `?cursor=${Number((params as any).cursor ?? 0)}`;
+        const r = await vfetch(base, path, { cfg, did: d });
+        if (!r.ok) return ok({ error: r.status === 404 ? "your match/seat is gone — join again" : (r.data?.error ?? `observe ${r.status}`) });
+        return ok({ view: r.data, hint: `order with ${c.act.tool}` });
+      } } as AnyAgentTool);
+  }
+
+  // act — BATCH (moves[]) for venues that seat multiple players (a game), else SINGLE.
+  {
+    const s = c.act;
+    const actRoute = spec.routes?.["act"] ?? "/matches/{matchId}/players/{playerId}/action";
+    const batch = !!c.join?.seat?.controls; // games seat players → batch; seatless work → single
+    const desc = s.summary + (Object.keys(descs).length ? " Actions — " + enumList.filter(a => descs[a]).map(a => `${a}: ${descs[a]}`).join("; ") : "");
+    if (batch) {
+      out.push({ name: s.tool, label: s.tool,
+        description: desc + " Set actions for ALL players you control in ONE call: pass moves=[{player, type, …}], one per player.",
+        parameters: paramsSchema({}, { moves: { type: "array", items: paramsSchema(s.params ?? {}, { player: { type: "string", description: "your player id, e.g. home-9" }, type: { type: "string", enum: enumList, description: "the action" } }, ["player", "type"]) } }, ["moves"]),
+        async execute(_id, params) {
+          const seat = seats.get(venue.id) ?? {}; const d = did(venue.id, cfg);
+          const applied: unknown[] = [];
+          for (const m of ((params as any).moves ?? []) as Record<string, unknown>[]) {
+            const action = String(m.type ?? "").trim();
+            if (!enumList.includes(action)) { applied.push({ player: m.player, error: `type must be one of ${JSON.stringify(enumList)}` }); continue; }
+            const path = sub(actRoute, { matchId: seat.id ?? "", did: d, playerId: String(m.player ?? "") });
+            const body = { agentId: d, type: action, ...whitelist(m, s.params ?? {}), ...(session.lockstep ? { turn: session.turn } : {}) };
+            const r = await vfetch(base, path, { cfg, did: d, method: "POST", body, token: seat.token });
+            applied.push(r.ok ? { player: m.player, type: action } : { player: m.player, error: r.data?.error ?? r.status });
+          }
+          return ok({ applied });
+        } } as AnyAgentTool);
+    } else {
+      out.push({ name: s.tool, label: s.tool, description: desc,
+        parameters: paramsSchema(s.params ?? {}, { type: { type: "string", enum: enumList, description: "the action" } }, ["type"]),
+        async execute(_id, params) {
+          const p = params as Record<string, unknown>; const action = String(p.type ?? "").trim();
+          if (!enumList.includes(action)) return ok({ error: `type must be one of ${JSON.stringify(enumList)}` });
+          const seat = seats.get(venue.id) ?? {}; const d = did(venue.id, cfg);
+          const path = sub(actRoute, { matchId: seat.id ?? "", did: d, playerId: String(p.player ?? "") });
+          const r = await vfetch(base, path, { cfg, did: d, method: "POST", body: { type: action, ...whitelist(p, s.params ?? {}) }, token: seat.token });
+          if (!r.ok) return ok({ error: r.data?.error ?? `act ${r.status}` });
+          return ok({ type: action, result: r.data });
+        } } as AnyAgentTool);
+    }
+  }
+
+  return out;
+}
+
+// ── discovery + offline fallback (mirrors generate.py) ────────────────────────
+const DEFAULT_VENUES: Venue[] = [
+  { id: "agent-soccer", origin: "pitch", specUrl: "/spec" },
+  { id: "taskmarket", origin: "taskmarket", specUrl: "/spec" },
+];
+
+export async function discoverVenues(cfg: PluginCfg): Promise<Venue[]> {
+  try {
+    const res = await fetch(`${venueUrl("pitch", cfg)}/platform/marketplaces`);
+    if (res.ok) { const { marketplaces } = (await res.json()) as { marketplaces: Venue[] }; if (marketplaces?.length) return marketplaces; }
+  } catch { /* offline */ }
+  return DEFAULT_VENUES;
+}
+
+export async function fetchVenueSpec(venue: Venue, cfg: PluginCfg): Promise<GameSpec | null> {
+  try {
+    const res = await fetch(`${venueUrl(venue.origin, cfg)}${venue.specUrl ?? "/spec"}`);
+    if (res.ok) { const s = (await res.json()) as GameSpec; if (s?.client) return s; }
+  } catch { /* offline → caller skips this venue's generated tools */ }
+  return null;
+}
+
+/** Every venue's generated tools — discovered from the registry, spec per venue. */
+export async function allVenueTools(cfg: PluginCfg): Promise<AnyAgentTool[]> {
+  const out: AnyAgentTool[] = [];
+  for (const v of await discoverVenues(cfg)) {
+    const spec = await fetchVenueSpec(v, cfg);
+    if (spec?.client) out.push(...generateVenueTools(v, spec, cfg));
+  }
+  return out;
+}
+
+// ── baked default specs (offline-safe) — register() is sync (can't await a
+// fetch), so it generates from these; they mirror the server's client blocks.
+const DEFAULT_SPECS: Record<string, GameSpec> = {
+  "agent-soccer": {
+    game: "agent-soccer", specVersion: 1, rulesVersion: 2,
+    actions: { type: "string", enum: ["run", "kick", "chase", "shoot", "dribble", "pass", "defend", "press", "cover", "idle", "stop"], descriptions: {} },
+    observe: { mode: "stream", suggestedIntervalMs: 3000 },
+    routes: { observe: "/matches/{matchId}/agents/{did}/observe", state: "/matches/{matchId}/agents/{did}/state", act: "/matches/{matchId}/players/{playerId}/action" },
+    client: {
+      prefix: "soccer", noun: "match",
+      lobby: { tool: "soccer_matches", route: "/matches", params: { status: { type: "string", enum: ["live", "waiting", "ended"] } }, summary: "List soccer matches: live, open seats, scores." },
+      join: { tool: "soccer_join", route: "/quickmatch", seatRoute: "/matches/{matchId}/join", params: { teamSize: { type: "integer" }, team: { type: "string" }, name: { type: "string" }, nation: { type: "string" }, clan: { type: "string" }, style: { type: "string" } }, seat: { id: "matchId", token: "token", controls: "playerIds" }, summary: "Join a match and take a whole side (quickmatch). The match starts when both sides fill." },
+      observe: { tool: "soccer_observe", params: {}, summary: "See the pitch from your side's POV: ball, your players, opponents, score." },
+      act: { tool: "soccer_play", params: { dir: { type: "array", items: { type: "number" } }, distance: { type: "number" }, power: { type: "number" }, say: { type: "string" } }, summary: "Order your players — a standing action per player (run/kick need dir)." },
+      autoplay: { tool: "soccer_autoplay", summary: "Hands-free play (handled by the watcher service)." },
+    },
+  },
+  "taskmarket": {
+    game: "taskmarket", specVersion: 1, rulesVersion: 1,
+    actions: { type: "string", enum: ["post", "bid", "accept", "deliver", "confirm", "cancel", "dispute"], descriptions: {} },
+    observe: { mode: "poll", suggestedIntervalMs: 30000 },
+    routes: { observe: "/agents/{did}/observe", act: "/agents/{did}/action" },
+    client: {
+      prefix: "taskmarket", noun: "task", lobby: null, join: null,
+      observe: { tool: "work_observe", params: { cursor: { type: "number" } }, summary: "See the task market: events, your posts/bids, the open market, per-task legalActions." },
+      act: { tool: "work_act", params: { taskId: { type: "string" }, title: { type: "string" }, description: { type: "string" }, budget: { type: "number" }, price: { type: "number" }, message: { type: "string" }, etaHours: { type: "number" }, bidId: { type: "string" }, result: { type: "string" } }, summary: "Act in the task market: post/bid/accept/deliver/confirm/cancel/dispute." },
+    },
+  },
+};
+
+/** Sync tool generation from the baked default venues — used by register()
+ *  (which can't await). Live discovery (new venues) uses allVenueTools(). */
+export function defaultVenueTools(cfg: PluginCfg): AnyAgentTool[] {
+  const out: AnyAgentTool[] = [];
+  for (const v of DEFAULT_VENUES) {
+    const spec = DEFAULT_SPECS[v.id];
+    if (spec?.client) out.push(...generateVenueTools(v, spec, cfg));
+  }
+  return out;
+}
+
+/** Does a spec describe a venue the autoplay watcher can drive? It must stream
+ *  observations, seat the agent (players to control), and offer hands-free play.
+ *  Soccer qualifies; the seatless poll-based taskmarket does not. */
+export function isRealtimeVenue(spec?: GameSpec | null): boolean {
+  return !!spec && spec.observe?.mode === "stream" && !!spec.client?.join?.seat && !!spec.client?.autoplay;
+}
+
+/** The realtime venue the watcher service should drive, from the baked defaults
+ *  (register() is sync). Null when none is realtime. Drives seating/observe/act
+ *  entirely from {venue, spec} — no soccer literals in the service. */
+export function defaultRealtimeVenue(): { venue: Venue; spec: GameSpec } | null {
+  for (const venue of DEFAULT_VENUES) {
+    const spec = DEFAULT_SPECS[venue.id];
+    if (isRealtimeVenue(spec)) return { venue, spec };
+  }
+  return null;
+}