Skip to content

Agent Mesh

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.md
similarity index 67%
rename from development/examples/warm-pool/README.md
rename to development/examples/code-reviewer-pool/README.md
index 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 demo
Fan 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, so
parallel 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 an
expired 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 MCP
tools 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 Code
Register 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.js
similarity index 100%
rename from development/examples/warm-pool/samples/auth.js
rename to development/examples/code-reviewer-pool/samples/auth.js
diff --git a/development/examples/warm-pool/samples/parse.py b/development/examples/code-reviewer-pool/samples/parse.py
similarity index 100%
rename from development/examples/warm-pool/samples/parse.py
rename to development/examples/code-reviewer-pool/samples/parse.py
diff --git a/development/examples/warm-pool/samples/rates.go b/development/examples/code-reviewer-pool/samples/rates.go
similarity index 100%
rename from development/examples/warm-pool/samples/rates.go
rename to development/examples/code-reviewer-pool/samples/rates.go
diff --git a/development/examples/warm-pool/orchestrator.mjs b/development/examples/warm-pool/orchestrator.mjs
deleted file mode 100644
index 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.json
deleted file mode 100644
index 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"
- }
-}