@agentmessier/openclaw-agent-messier 0.3.0

package/src/venues.test.ts

@@ -0,0 +1,67 @@
+import { describe, it, expect, afterEach, vi } from "vitest";
+import { createSoccerTools, _resetVenueCache, type PluginCfg } from "./tools.js";
+
+const REGISTRY = { marketplaces: [
+  { id: "agent-soccer", name: "Agent Soccer", origin: "pitch", specUrl: "/spec", feeBps: 2000, status: "live", kind: "game" },
+  { id: "taskmarket", name: "Agent Task Market", origin: "taskmarket", specUrl: "/spec", feeBps: 1000, status: "live", kind: "work" },
+] };
+
+const WORK_SPEC = {
+  game: "taskmarket", specVersion: 1, rulesVersion: 1,
+  actions: { type: "string", enum: ["post", "bid", "deliver"], descriptions: {} },
+  observe: { mode: "poll", suggestedIntervalMs: 30000 },
+  routes: { observe: "/agents/{did}/observe", act: "/agents/{did}/action" },
+  instructions: { system: "s", play: "p", output: "o" },
+};
+
+function cfg(extra: Partial<PluginCfg> = {}): PluginCfg {
+  return { serverUrl: "http://pitch.test", sessionKey: "did:wba:me", ...extra };
+}
+function tool(name: string) {
+  const tools = createSoccerTools({ pluginConfig: cfg(), config: {} } as any);
+  return tools.find(t => t.name === name)!;
+}
+async function run(name: string, params: unknown): Promise<any> {
+  const r = await tool(name).execute("id", params as any) as { content: { text: string }[] };
+  return JSON.parse(r.content[0]!.text);
+}
+
+describe("multi-venue tools (marketplace registry → generated work tools)", () => {
+  afterEach(() => { vi.unstubAllGlobals(); _resetVenueCache(); });
+
+  it("venues lists the registry with kinds", async () => {
+    vi.stubGlobal("fetch", vi.fn(async (url: any) => {
+      expect(String(url)).toContain("/platform/marketplaces");
+      return { ok: true, json: async () => REGISTRY } as any;
+    }));
+    const out = await run("venues", {});
+    expect(out.venues.map((v: any) => v.kind)).toEqual(["game", "work"]);
+  });
+
+  it("work_observe substitutes the DID into the venue's route template", async () => {
+    const seen: string[] = [];
+    vi.stubGlobal("fetch", vi.fn(async (url: any, init?: any) => {
+      seen.push(String(url));
+      if (String(url).endsWith("/spec")) return { ok: true, json: async () => WORK_SPEC } as any;
+      expect(init?.headers?.["x-caller-did"]).toBe("did:wba:me");
+      return { ok: true, json: async () => ({ summary: "quiet", events: [], cursor: 0 }) } as any;
+    }));
+    const out = await run("work_observe", {});
+    expect(out.summary).toBe("quiet");
+    expect(seen.some(u => u.includes("/agents/did%3Awba%3Ame/observe") || u.includes("/agents/did:wba:me/observe"))).toBe(true);
+  });
+
+  it("work_act validates against the venue enum and posts the uniform body", async () => {
+    let posted: any = null;
+    vi.stubGlobal("fetch", vi.fn(async (url: any, init?: any) => {
+      if (String(url).endsWith("/spec")) return { ok: true, json: async () => WORK_SPEC } as any;
+      posted = JSON.parse(init.body);
+      return { ok: true, json: async () => ({ id: "task-1", status: "open" }) } as any;
+    }));
+    const bad = await run("work_act", { action: "fly" });
+    expect(bad.error).toContain("post");
+    const ok2 = await run("work_act", { action: "post", title: "t", description: "d", budget: 5 });
+    expect(ok2.result.id).toBe("task-1");
+    expect(posted).toEqual({ type: "post", title: "t", description: "d", budget: 5 });
+  });
+});

package/src/watcher.test.ts

@@ -0,0 +1,121 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, writeFileSync, rmSync, utimesSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { strategyText, _clearStrategyCache, prompt, parseSseBlock } from "./watcher.js";
+import type { TeamView } from "./format.js";
+import type { GameSpec } from "./tools.js";
+
+let dir: string;
+beforeEach(() => { dir = mkdtempSync(join(tmpdir(), "soccer-strat-")); _clearStrategyCache(); });
+afterEach(() => { rmSync(dir, { recursive: true, force: true }); });
+
+const VIEW = {
+  tick: 1, clock: 0, phase: "live", team: "home",
+  score: { home: 0, away: 0 },
+  field: { length: 105, width: 68, attackGoal: { x: 52.5, y: 0 }, ownGoal: { x: -52.5, y: 0 }, goalHalfWidth: 3.66, tickHz: 10 },
+  mine: [{ id: "home-9", number: 9, pos: { x: 0, y: 0 }, vel: { x: 0, y: 0 }, hasBall: true }],
+  ball: { pos: { x: 0, y: 0 }, vel: { x: 0, y: 0 }, owner: "home-9" },
+  teammates: [], opponents: [],
+} as unknown as TeamView;
+
+describe("Phase 5 — strategyText (mtime-cached, capped) + prompt injection", () => {
+  it("returns '' when the file is absent", () => {
+    expect(strategyText(join(dir, "nope.md"))).toBe("");
+    expect(strategyText(undefined)).toBe("");
+  });
+
+  it("reads a present file", () => {
+    const f = join(dir, "strategy.md");
+    writeFileSync(f, "Press high. Keep the ball.");
+    expect(strategyText(f)).toContain("Press high");
+  });
+
+  it("caps the injected text at ~1k chars", () => {
+    const f = join(dir, "strategy.md");
+    writeFileSync(f, "x".repeat(5000));
+    expect(strategyText(f).length).toBeLessThanOrEqual(1000);
+  });
+
+  it("refreshes when the file mtime changes", () => {
+    const f = join(dir, "strategy.md");
+    writeFileSync(f, "first plan");
+    expect(strategyText(f)).toContain("first plan");
+    writeFileSync(f, "second plan");
+    const future = new Date(Date.now() + 5000);
+    utimesSync(f, future, future);
+    const out = strategyText(f);
+    expect(out).toContain("second plan");
+    expect(out).not.toContain("first plan");
+  });
+
+  it("prompt injects the strategy block when a strategyFile is set", () => {
+    const f = join(dir, "strategy.md");
+    writeFileSync(f, "Park the bus. Counter fast.");
+    const p = prompt(VIEW, "easy", f);
+    expect(p.toLowerCase()).toContain("standing instructions");
+    expect(p).toContain("Park the bus");
+  });
+
+  it("prompt has no strategy block when the file is absent", () => {
+    const p = prompt(VIEW, "easy", join(dir, "missing.md"));
+    expect(p.toLowerCase()).not.toContain("standing instructions");
+  });
+});
+
+// ── the self-instructable envelope (generic GSP client) ─────────────────────
+const SPEC = {
+  game: "agent-soccer", specVersion: 1, rulesVersion: 2,
+  actions: { type: "string", enum: ["chase", "shoot", "lob"], descriptions: { lob: "chip it" } },
+  instructions: {
+    system: "You are a decisive tactician.",
+    play: "SERVER PLAY GUIDANCE: lob when the keeper is off his line.",
+    output: 'Reply with ONLY JSON {"moves":{...}}',
+  },
+} as unknown as GameSpec;
+
+const VIEW_WITH_SUMMARY = { ...VIEW, summary: "⚽ SERVER-RENDERED SITUATION." } as TeamView & { summary: string };
+
+describe("generic prompt — instructions + summary come from the server", () => {
+  it("uses the server's instructions and summary when a spec is cached", () => {
+    const p = prompt(VIEW_WITH_SUMMARY, "easy", undefined, SPEC);
+    expect(p).toContain("SERVER-RENDERED SITUATION");
+    expect(p).toContain("SERVER PLAY GUIDANCE");
+    // tool-calling host: act via the play tool, named generically
+    expect(p.toLowerCase()).toContain("play tool");
+    // the plugin's hardcoded soccer prose is gone on this path
+    expect(p).not.toContain("YOU ATTACK +x: opponent goal at x=+52.5");
+  });
+
+  it("keeps the strategy block on the generic path", () => {
+    const f = join(dir, "strategy.md");
+    writeFileSync(f, "Park the bus tonight.");
+    const p = prompt(VIEW_WITH_SUMMARY, "easy", f, SPEC);
+    expect(p).toContain("Park the bus tonight");
+    expect(p).toContain("SERVER PLAY GUIDANCE");
+  });
+
+  it("falls back to local rendering when there is no spec (old server)", () => {
+    const p = prompt(VIEW, "easy", undefined, null);
+    expect(p).toContain("soccer_play"); // the legacy describeTeam path
+  });
+});
+
+describe("parseSseBlock — named events for the handshake", () => {
+  it("parses a named event block", () => {
+    const b = parseSseBlock('event: spec\ndata: {"game":"agent-soccer"}');
+    expect(b.event).toBe("spec");
+    expect(JSON.parse(b.data!)).toEqual({ game: "agent-soccer" });
+  });
+
+  it("parses a plain data block (no event name)", () => {
+    const b = parseSseBlock('data: {"tick":1}');
+    expect(b.event).toBeUndefined();
+    expect(JSON.parse(b.data!)).toEqual({ tick: 1 });
+  });
+
+  it("ignores comments and empty payloads", () => {
+    expect(parseSseBlock(": connected").data).toBeUndefined();
+    expect(parseSseBlock("data: ").data).toBeUndefined();
+  });
+});

package/src/watcher.ts

@@ -0,0 +1,216 @@
+/**
+ * Soccer team-observation watcher — background SSE loop that feeds the agent.
+ *
+ * Subscribes to GET /matches/:id/agents/:agentId/observe, which streams a
+ * TeamView (the agent's whole side) every tick (10 Hz). We never block the
+ * match: the reader keeps only the LATEST view; a single in-flight delivery
+ * feeds the agent the freshest state one decision at a time. While the agent is
+ * thinking, new frames just update `latest`; when it finishes it gets the
+ * newest state. Once the match ends, delivery stops (no prompt = no LLM call).
+ *
+ * SSE loop + exponential-backoff reconnect, signal-abortable.
+ */
+import { statSync, readFileSync } from "node:fs";
+import { describeTeam, type TeamView } from "./format.js";
+import { fetchMatchSpec, type GameSpec, type PluginCfg } from "./tools.js";
+import { session } from "./state.js";
+
+export type WatcherCfg = {
+  serverUrl?: string;
+  matchId: string;
+  /** Stable agent id whose claimed players this watcher drives. */
+  agentId: string;
+  /** Tool tier — tailors the move prompt to the agent's tools. Default "easy". */
+  mode?: "easy" | "advanced" | "both";
+  /** Human-editable strategy.md injected into the move prompt (Phase 5). */
+  strategyFile?: string;
+};
+
+// ── human-editable strategy (Phase 5) ────────────────────────────────────────
+// A markdown file the manager edits; injected into the move prompt. mtime-cached
+// (no re-read per tick), refreshed on edit, capped so it can't blow the prompt.
+const STRATEGY_CAP = 1000;
+const _strategyCache = new Map<string, { mtimeMs: number; text: string }>();
+
+/** Test seam: drop the mtime cache. */
+export function _clearStrategyCache(): void { _strategyCache.clear(); }
+
+/** The manager's standing instructions, mtime-cached + capped. '' when the file
+ *  is unset/absent/unreadable, so no block is injected. */
+export function strategyText(file?: string): string {
+  if (!file) return "";
+  let mtimeMs: number;
+  try { mtimeMs = statSync(file).mtimeMs; }
+  catch { _strategyCache.delete(file); return ""; }
+  const cached = _strategyCache.get(file);
+  if (cached && cached.mtimeMs === mtimeMs) return cached.text;
+  let text: string;
+  try { text = readFileSync(file, "utf8").trim().slice(0, STRATEGY_CAP); }
+  catch { return ""; }
+  _strategyCache.set(file, { mtimeMs, text });
+  return text;
+}
+
+export type WatcherLogger = {
+  info: (msg: string) => void;
+  warn: (msg: string) => void;
+  error: (msg: string) => void;
+};
+
+export type WatcherOptions = {
+  signal?: AbortSignal;
+  logger?: WatcherLogger;
+  /** Called when the server no longer knows our claim (404 — e.g. it restarted).
+   *  Should re-claim players; the watcher then reconnects. */
+  onReclaim?: () => Promise<void>;
+};
+
+/** One SSE block → {event?, data?}. Named events carry the per-match spec
+ *  handshake; plain data blocks are observation frames. Pure, unit-tested. */
+export function parseSseBlock(block: string): { event?: string; data?: string } {
+  let event: string | undefined;
+  let data: string | undefined;
+  for (const line of block.split("\n")) {
+    if (line.startsWith("event: ")) event = line.slice(7).trim();
+    else if (line.startsWith("data: ")) {
+      const payload = line.slice(6).trim();
+      if (payload) data = payload;
+    }
+  }
+  return event !== undefined ? { event, ...(data !== undefined ? { data } : {}) } : (data !== undefined ? { data } : {});
+}
+
+export function prompt(v: TeamView & { summary?: string }, mode: "easy" | "advanced" | "both", strategyFile?: string, spec?: GameSpec | null): string {
+  const standing = strategyText(strategyFile);
+  const stratBlock = standing ? `## Your manager's standing instructions\n${standing}\n\n` : "";
+  const ins = spec?.instructions;
+  if (ins && ins.system && ins.play && v.summary) {
+    // Generic GSP path: the server authored the instructions AND rendered the
+    // situation — the plugin only concatenates. Tool-calling host, so the
+    // direct-JSON `output` contract is replaced by a generic tool-act line
+    // (host concern, not game knowledge).
+    return (
+      `${ins.system}\n\n` +
+      stratBlock +
+      `${v.summary}\n\n` +
+      `${ins.play}\n\n` +
+      `Decide and act now: make ONE call to your play tool with a move for every player you control. ` +
+      `Each is a standing order until you change it.`
+    );
+  }
+  // Fallback (pre-envelope server or handshake not yet arrived): the legacy
+  // plugin-side rendering.
+  return (
+    stratBlock +
+    `${describeTeam(v, mode)}\n\n` +
+    `Decide and act now: make ONE soccer_play call with a move for every player you control. ` +
+    `Each is a standing order until you change it.`
+  );
+}
+
+export async function startObserveWatcher(
+  cfg: WatcherCfg,
+  deliver: (msg: string) => void | Promise<void>,
+  options: WatcherOptions = {},
+): Promise<void> {
+  const { signal, logger } = options;
+  const base = (cfg.serverUrl ?? "http://localhost:3010").replace(/\/$/, "");
+  const url = `${base}/matches/${encodeURIComponent(cfg.matchId)}/agents/${encodeURIComponent(cfg.agentId)}/observe`;
+
+  let latest: TeamView | null = null;
+  let latestSeq = 0;
+  let deliveredSeq = -1;
+  let busy = false;
+
+  // The match's spec snapshot (instructions frozen per game). Normally arrives
+  // as the SSE `event: spec` handshake; the guard below lazily fetches it when
+  // a frame shows up first (handshake lost / pre-envelope server) — at most one
+  // in-flight attempt, re-tried on later frames until it lands. A null spec
+  // only degrades the prompt to the legacy rendering; it never blocks play.
+  let spec: GameSpec | null = null;
+  let specFetching = false;
+  function ensureSpec() {
+    if (spec !== null || specFetching) return;
+    specFetching = true;
+    fetchMatchSpec({ serverUrl: cfg.serverUrl } as PluginCfg, cfg.matchId)
+      .then((s) => { if (s) { spec = s; logger?.info(`[agentnet-soccer] spec recovered via API (rulesVersion ${s.rulesVersion})`); } })
+      .finally(() => { specFetching = false; });
+  }
+
+  function maybeDeliver() {
+    if (busy || signal?.aborted || latest === null || latestSeq === deliveredSeq) return;
+    // Match over → stop prompting. No message to the gateway = no LLM call.
+    if (latest.phase === "ended") { deliveredSeq = latestSeq; return; }
+    busy = true;
+    const seq = latestSeq;
+    const obs = latest;
+    Promise.resolve(deliver(prompt(obs, cfg.mode ?? "easy", cfg.strategyFile, spec)))
+      .catch((e) => logger?.error(`[agentnet-soccer] deliver failed: ${String(e)}`))
+      .finally(() => { deliveredSeq = seq; busy = false; maybeDeliver(); });
+  }
+
+  let attempt = 0;
+  while (true) {
+    if (signal?.aborted) return;
+    try {
+      const res = await fetch(url, { headers: { Accept: "text/event-stream" }, signal });
+      if (res.status === 404 && options.onReclaim) {
+        // Server forgot us (restart) — re-claim our players, then reconnect.
+        try { await options.onReclaim(); } catch (e) { logger?.warn(`[agentnet-soccer] re-claim failed: ${String(e)}`); }
+        await backoff(attempt++, signal);
+        continue;
+      }
+      if (!res.ok || !res.body) { await backoff(attempt++, signal); continue; }
+      attempt = 0;
+      const reader = res.body.getReader();
+      const decoder = new TextDecoder();
+      let buffer = "";
+
+      while (true) {
+        if (signal?.aborted) { reader.cancel().catch(() => {}); return; }
+        let done: boolean, value: Uint8Array | undefined;
+        try { ({ done, value } = await reader.read()); } catch { break; }
+        if (done) break;
+
+        buffer += decoder.decode(value, { stream: true });
+        const blocks = buffer.split("\n\n");
+        buffer = blocks.pop() ?? "";
+
+        for (const block of blocks) {
+          const { event, data } = parseSseBlock(block);
+          if (!data) continue;
+          if (event === "spec") {
+            // The per-game handshake: this match's frozen instructions.
+            try {
+              const s = JSON.parse(data) as GameSpec;
+              if (s && Array.isArray(s.actions?.enum)) spec = s;
+            } catch { /* malformed handshake → the ensureSpec guard recovers */ }
+            continue;
+          }
+          let v: TeamView;
+          try { v = JSON.parse(data) as TeamView; } catch { continue; }
+          if (!v || !Array.isArray(v.mine)) continue; // skip non-team frames
+          ensureSpec(); // protection: frame before handshake → fetch via API
+          // The team stream is authoritative for which players we control, so
+          // a live ratio change on the server is followed without reconnecting.
+          session.players = v.mine.map((p) => p.id);
+          latest = v;
+          latestSeq++;
+          maybeDeliver();
+        }
+      }
+    } catch {
+      if (signal?.aborted) return;
+    }
+    await backoff(attempt++, signal);
+  }
+}
+
+async function backoff(attempt: number, signal?: AbortSignal): Promise<void> {
+  const base = Math.min(1000 * Math.pow(2, attempt), 30000);
+  const delay = base + base * 0.2 * Math.random();
+  await new Promise<void>((resolve) => {
+    const t = setTimeout(resolve, delay);
+    signal?.addEventListener("abort", () => { clearTimeout(t); resolve(); }, { once: true });
+  });
+}