Agent Mesh
Go a2aa2a-protocolagent-meshagentic-aiinferencemcpmeshmesh-networknetwork-securitynetworking-aip2p-network
refactor(code-reviewer-pool): remove warm-pool dir; relocate README + samples
Tomas Tormo9bb7dd998f00
diff --git a/development/examples/warm-pool/README.md b/development/examples/code-reviewer-pool/README.mdsimilarity index 67%rename from development/examples/warm-pool/README.mdrename to development/examples/code-reviewer-pool/README.mdindex 6f9b952f..f7e0b90b 100644--- a/development/examples/warm-pool/README.md+++ b/development/examples/code-reviewer-pool/README.md@@ -1,19 +1,20 @@-# Warm Agent Pool — demo+# Code-reviewer pool — warm agent pool demoFan a batch of files out to a **pool of identical reviewer workers**. A-**pool-manager** mesh service tracks which workers are free and leases them out;-an orchestrator (Claude Code, or the headless script here) acquires a worker,-reviews a file, and releases it. Reviews run in parallel across the pool.+**manager** mesh service tracks which workers are free and leases them out;+Claude Code (the orchestrator) acquires a worker, reviews a file, and releases+it. Reviews run in parallel across the pool.Design: `docs/superpowers/specs/2026-06-28-warm-agent-pool-design.md`.## Architecture (no gossip, no node changes — just services)-- **Workers:** plain `code-reviewer` mcp services (node-b/c/d). Unmodified.-- **pool-manager** (node-e): a normal mcp service exposing `acquire_worker` /- `release_worker` / `list_workers`. It is also a northbound MCP client of its- own node: every few seconds it calls `find_remote_tools(service_name="code-reviewer")`- to learn the worker peers (DHT), and it tracks free/busy with **leases**.+- **Workers:** plain `code-reviewer` mcp services (node-b/c/d), under `reviewer/`.+- **manager** (node-e, under `manager/`): a normal mcp service exposing+ `acquire_worker` / `release_worker` / `list_workers`. It is also a northbound+ MCP client of its own node: every few seconds it calls+ `find_remote_tools(service_name="code-reviewer")` to learn the worker peers+ (DHT), and it tracks free/busy with **leases**.- **Orchestrator:** `acquire_worker` → `call_remote_tool(peer, review_code)` →`release_worker`. Leasing hands each concurrent acquire a different worker, soparallel dispatch never collides.@@ -35,8 +36,8 @@ dispatcher (fine for a single-manager pool).clears the lease only if the id still matches, so a late release from anexpired lease can't free a newer holder's worker.- **Worker single-flight backstop:** `review_code` returns `POOL_BUSY` if already- running; the orchestrator retries. This keeps the one-at-a-time invariant even- if a lease race ever slips through.+ running; the caller retries. This keeps the one-at-a-time invariant even if a+ lease race ever slips through.## Run it@@ -48,11 +49,11 @@ dispatcher (fine for a single-manager pool).2. Mesh layout ships in `development/kind/mesh-config.yaml`:```yaml- node-a: # in-cluster bare node- node-b: code-reviewer-pool/reviewer # worker- node-c: code-reviewer-pool/reviewer # worker- node-d: code-reviewer-pool/reviewer # worker- node-e: code-reviewer-pool/manager # manager+ node-a: # in-cluster bare node+ node-b: code-reviewer-pool/reviewer # worker+ node-c: code-reviewer-pool/reviewer # worker+ node-d: code-reviewer-pool/reviewer # worker+ node-e: code-reviewer-pool/manager # manager```3. Bring the mesh up and start a **local caller node** — this is the orchestrator@@ -64,10 +65,9 @@ dispatcher (fine for a single-manager pool).````kind-local-node` runs in the foreground (own shell). It exposes the mesh MCPtools at **`http://127.0.0.1:9099/mcp`** (token `devtoken`) — no- `kubectl port-forward` needed. This `:9099` endpoint is the base for both- options below.+ `kubectl port-forward` needed.-### Option A — drive it from Claude Code (the cool one)+### Drive it from Claude CodeRegister the local node as an MCP server (`.mcp.json` in the project root):```json@@ -83,31 +83,13 @@ Register the local node as an MCP server (`.mcp.json` in the project root):```Reconnect Claude Code, then prompt:> Using the sam-mesh tools: find the pool-manager, then for each file in-> `development/examples/warm-pool/samples/` acquire a worker, call its+> `development/examples/code-reviewer-pool/samples/` acquire a worker, call its> `review_code` with the file contents, and release it (pass the lease_id back> to release_worker). Run them in parallel.Claude fires parallel `acquire_worker` → `call_remote_tool` → `release_worker`chains; you watch the reviews come back concurrently.-### Option B — headless script--```-cd development/examples/warm-pool-npm install-node orchestrator.mjs samples # defaults to http://127.0.0.1:9099/mcp-```-Example output:-```-queued 3 review task(s)-pool-manager at 9c2ab1f0-[+0.4s] -> 3f9a1c2e samples/auth.js-[+0.4s] -> b7d4e0a1 samples/parse.py-[+0.4s] -> c1a8f552 samples/rates.go-[+6.1s] <- b7d4e0a1 samples/parse.py (712 chars)-[+7.0s] <- 3f9a1c2e samples/auth.js (901 chars)-```-## Elasticity beat (add a worker mid-job)Scale a reviewer down, start a larger job, then scale it back up — the manager@@ -122,12 +104,12 @@ kubectl --context kind-sam-kind -n sam-kind scale deploy/node-d --replicas=1| var | default | used by ||-----|---------|---------|-| `SAM_NODE_URL` | manager: `http://127.0.0.1:8080/mcp`, orchestrator: `http://127.0.0.1:9099/mcp` | both |-| `SAM_API_TOKEN` | `devtoken` | both |+| `SAM_NODE_URL` | `http://127.0.0.1:8080/mcp` | manager |+| `SAM_API_TOKEN` | `devtoken` | manager || `SAM_POOL_SERVICE` | `code-reviewer` | manager || `SAM_DISCOVERY_MS` | `3000` | manager || `SAM_LEASE_MS` | `60000` | manager |-| `SAM_ACQUIRE_TIMEOUT` | `60` | orchestrator |+| `SAM_GRACE_MISSES` | `2` | manager || `SAM_POOL_SECRET` | unset (enforcement off) | manager + reviewer |## Lease enforcement (optional)diff --git a/development/examples/warm-pool/samples/auth.js b/development/examples/code-reviewer-pool/samples/auth.jssimilarity index 100%rename from development/examples/warm-pool/samples/auth.jsrename to development/examples/code-reviewer-pool/samples/auth.jsdiff --git a/development/examples/warm-pool/samples/parse.py b/development/examples/code-reviewer-pool/samples/parse.pysimilarity index 100%rename from development/examples/warm-pool/samples/parse.pyrename to development/examples/code-reviewer-pool/samples/parse.pydiff --git a/development/examples/warm-pool/samples/rates.go b/development/examples/code-reviewer-pool/samples/rates.gosimilarity index 100%rename from development/examples/warm-pool/samples/rates.gorename to development/examples/code-reviewer-pool/samples/rates.godiff --git a/development/examples/warm-pool/orchestrator.mjs b/development/examples/warm-pool/orchestrator.mjsdeleted file mode 100644index 39e3a095..00000000--- a/development/examples/warm-pool/orchestrator.mjs+++ /dev/null@@ -1,87 +0,0 @@-// Headless warm-pool orchestrator (alternative to driving it from Claude Code).-// For each file: acquire a free worker from the pool-manager, review, release.-// All tasks run concurrently; the manager's blocking acquire + leasing serialize-// dispatch to the pool size, so no local queue is needed.-import { Client } from "@modelcontextprotocol/sdk/client/index.js";-import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";-import { readFileSync, readdirSync, statSync } from "node:fs";-import { join } from "node:path";--const NODE_URL = process.env.SAM_NODE_URL ?? "http://127.0.0.1:9099/mcp";-const API_TOKEN = process.env.SAM_API_TOKEN ?? "devtoken";-const ACQUIRE_TIMEOUT = Number(process.env.SAM_ACQUIRE_TIMEOUT ?? 60);--function collectFiles(paths) {- const out = [];- for (const p of paths) {- if (statSync(p).isDirectory()) {- for (const f of readdirSync(p)) {- const fp = join(p, f);- if (statSync(fp).isFile()) out.push(fp);- }- } else {- out.push(p);- }- }- return out;-}--const short = (peer) => peer.slice(-8);--async function main() {- const files = collectFiles(process.argv.slice(2));- if (!files.length) {- console.error("usage: node orchestrator.mjs <file|dir> ...");- process.exit(1);- }- const tasks = files.map((f) => ({ name: f, code: readFileSync(f, "utf8") }));- console.log(`queued ${tasks.length} review task(s)`);-- const client = new Client({ name: "warm-pool-orchestrator", version: "1.0.0" });- const transport = new StreamableHTTPClientTransport(new URL(NODE_URL), {- requestInit: { headers: { Authorization: `Bearer ${API_TOKEN}` } },- });- await client.connect(transport);-- const call = async (peer, tool, args) => {- const res = await client.callTool({ name: "call_remote_tool", arguments: { peer_id: peer, tool_name: tool, arguments: args } });- return res?.content?.[0]?.text ?? "";- };-- // Locate the pool-manager peer (tool names are full URIs).- const found = JSON.parse((await client.callTool({ name: "find_remote_tools", arguments: {} })).content[0].text);- const manager = found.find((r) => r.tool_name === "mcp://pool-manager/acquire_worker")?.peer_id;- if (!manager) { console.error("no pool-manager found in the mesh"); process.exit(1); }- console.log(`pool-manager at ${short(manager)}`);-- const t0 = Date.now();- const elapsed = () => ((Date.now() - t0) / 1000).toFixed(1);-- const process1 = async (task) => {- for (;;) {- const acq = JSON.parse(await call(manager, "mcp://pool-manager/acquire_worker", { timeout_secs: ACQUIRE_TIMEOUT }));- if (!acq.peer_id) { console.error(`[+${elapsed()}s] no worker for ${task.name}`); return null; }- console.log(`[+${elapsed()}s] -> ${short(acq.peer_id)} ${task.name}`);- let review;- try {- review = await call(acq.peer_id, acq.tool, { code: task.code, token: acq.token });- } finally {- await call(manager, "mcp://pool-manager/release_worker", { peer_id: acq.peer_id, lease_id: acq.lease_id });- }- // Worker single-flight backstop tripped; the lease race is rare, so retry.- if (review.trim() === "POOL_BUSY") { console.log(`[+${elapsed()}s] ~~ ${short(acq.peer_id)} busy, retrying ${task.name}`); continue; }- console.log(`[+${elapsed()}s] <- ${short(acq.peer_id)} ${task.name} (${review.length} chars)`);- return { ...task, peer: acq.peer_id, review };- }- };-- const results = (await Promise.all(tasks.map(process1))).filter(Boolean);-- console.log(`\n=== done in ${elapsed()}s: ${results.length} review(s) across ${new Set(results.map((r) => r.peer)).size} worker(s) ===`);- for (const r of results) {- console.log(`\n----- ${r.name} (reviewed by ${short(r.peer)}) -----\n${r.review}`);- }- await client.close();-}--main().catch((e) => { console.error(e); process.exit(1); });diff --git a/development/examples/warm-pool/package.json b/development/examples/warm-pool/package.jsondeleted file mode 100644index 05df8848..00000000--- a/development/examples/warm-pool/package.json+++ /dev/null@@ -1,9 +0,0 @@-{- "name": "warm-pool-orchestrator",- "version": "1.0.0",- "private": true,- "type": "module",- "dependencies": {- "@modelcontextprotocol/sdk": "^1.0.0"- }-}